Packaging Script Framework

The packaging script framework lets you consume a PowerShell script as a package.

Use Cases

• Installing a package on an appliance, i.e. Firewall, where PowerShell cannot directly run on it.
• Creating a PowerShell script to install a package that has custom Post or Pre steps during installation.
  • Configure custom registry values for configuration.
• Installing a package that doesn't have an installer. i.e. just copying files to a location.

Requirements of the Script Framework

The script framework consist of a PowerShell module and a manifest file zipped together. The zip structure may also contain other supporting files and scripts as required by the custom code.

The PowerShell module

Required Functions

There are three required functions that must exist in the PowerShell module.

Function Name	Description	Return Type
Test-PackageResource	This function test if the package is in desired state.	Must return a boolean. True for in desired state and false for not in desired state.
Set-PackageResource	This function does the install or uninstall.	None
Get-ParameterMapping	This function helps with complex mappings using Rps-Mapped Parameters.	Function will return a Hashtable for each custom parameter it needs to map.

function Get-ParameterMapping
{
    return @{
            DscEncryptionCertificate = @{
                        EntityClass = 'ResourceItem'
                        EntityType = 'Certificate'
                        Role = 'DscEncryption'
                        IsAssigned = $true
            }
    }
}

Your PowerShell module can include other supporting functions and scripts as required for your package.

Parameters

Test-PackageResource and Set-PackageResource only has one required parameter, Ensure. Ensure states if the package should be 'Present' or 'Absent'. The two methods can have any other parameters that are required for the custom script to run using Rps Mapped Parameters.

Note

For more information on RPS-Mapped Parameters see How to configure Rps-Mapped Parameters.

Example Script Framework

$null = Import-Module -Name 'VMware.PowerCLI'
$null = Set-PowerCLIConfiguration -InvalidCertificateAction Ignore -Confirm:$false -ErrorAction SilentlyContinue -DefaultVIServerMode Multiple -ParticipateInCEIP $false -Scope Session

function Test-PackageResource
{
    [CmdletBinding()]
    Param
    (
        [Parameter(Mandatory = $true)]
        [ValidateScript({[ipaddress]::Parse($_)})]
        [string]
        $IPAddress,

        [Parameter(Mandatory = $true)]
        [string]
        $ComputerName,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $LocalAdmin,

        [Parameter(Mandatory = $true)]
        [string]
        $Ensure
    )

    Write-Verbose "Connecting to ESX at $IPAddress"

    $server = Connect-ViServer -Server $IPAddress -Credential $LocalAdmin -WarningAction SilentlyContinue -ErrorAction Stop

    $virtualSwitches = Get-VirtualSwitch -Name 'PatchedVirtualSwitch' -ErrorAction SilentlyContinue
    if($virtualSwitches)
    {
        if ($ensure -eq 'present')
        {
            return $true
        }
        else
        {
            return $false
        }
    }

    if ($ensure -eq 'Absent')
    {
        return $true
    }
    return $false

    Write-Verbose "Connected to ESX at $IPAddress"
}

function Set-PackageResource
{
   [CmdletBinding()]
    Param
    (
        [Parameter(Mandatory = $true)]
        [ValidateScript({[ipaddress]::Parse($_)})]
        [string]
        $IPAddress,

        [Parameter(Mandatory = $true)]
        [string]
        $ComputerName,

        [Parameter(Mandatory = $true)]
        [PSCredential]
        $LocalAdmin,

        [Parameter(Mandatory = $true)]
        [string]
        $Ensure

    )
    $server = Connect-ViServer -Server $IPAddress -Credential $LocalAdmin -WarningAction SilentlyContinue -ErrorAction Stop
    if ($ensure -eq 'Present')
    {
        New-VirtualSwitch -Server $server -Name 'PatchedVirtualSwitch' -ErrorAction SilentlyContinue
    }
    else
    {
        $vs = Get-VirtualSwitch -Server $server -Name 'PatchedVirtualSwitch'
        $vs | Remove-VirtualSwitch -Server $server -ErrorAction SilentlyContinue -Confirm:$false
    }
    Write-Verbose "Connecting to ESX at $IPAddress"
}

# Sample parameter mapping.  We are not using any complex parameters in this script
function Get-ParameterMapping
{
    @{
        DscEncryptionCertificate = @{
                    EntityClass = 'ResourceItem'
                    EntityType = 'Certificate'
                    Role = 'DscEncryption'
                    IsAssigned = $true
        }
    }
}