Parameter variables

Package arguments support variable substitution, which lets you set dynamic values instead of hard-coded strings. You can use variables anywhere you supply argument values — in the -Arguments parameter of Install-UscPackage and in the FillParameters property of a package manifest.

Variables use the following syntax:

${VariableName}

The following variable groups are available.

Environment variables

Environment variables resolve to system-level values on the machine where the package is being installed.

Variable	Description
`${Environment.NetworkServiceUser}`	Localized name of the Network Service account. Use this variable when configuring service accounts.
`${Environment.ProgramFilesX86}`	Path to the Program Files (x86) directory. Use this for 32-bit application installs on 64-bit Windows.
`${Environment.ProgramFiles}`	Path to the Program Files directory. Use this for 64-bit application installs.
`${Environment.FullyQualifiedDomainName}`	Fully qualified domain name (FQDN) of the machine. Use this for network configuration or machine identification in a domain environment.

Package variables

Package variables resolve to values related to the package instance being installed.

Variable	Description
`${Package.InstanceName}`	Name of the instance where the package is being installed. Use this for settings that are specific to the instance, such as database names or service accounts.

System variables

System variables resolve to values detected by Update Service during installation.

Variable	Description
`${System.SqlServerInstance}`	Name of the SQL Server instance, including the machine name. For example, `SQLSERVER\SQLEXPRESS`.
`${System.SqlServerInstanceName}`	Name of the SQL Server instance, without the machine name. For example, `SQLEXPRESS`.
`${System.SqlServerName}`	Name of the SQL Server machine. For example, `SQLSERVER`.

Package argument variables

You can reference a parameter from another package in the dependency tree using the following syntax:

${PackageId.ParameterName}

Where PackageId is the ID of the package and ParameterName is the key of the parameter defined in that package.

Note

Package argument variables are only available when using -Arguments with Install-UscPackage, or in the FillParameters property of a package manifest.

Examples

Pass certificate values between packages

This example sets argument values for the bc-server and bc-web-client packages using parameter values from certificate packages installed in the same operation.

$Arguments = @{
    'bc-server' = @{
        DeveloperServicesEnabled = 'true'
        AllowForceSync = 'true'
        ClientServicesCredentialType = 'NavUserPassword'
        ServicesCertificateThumbprint = '${my-private-certificate.CertificateThumbprint}'
        AllowSessionCallSuspendWhenWriteTransactionStarted = 'true'
    }
    'bc-web-client' = @{
        DnsIdentity = '${my-public-certificate.DnsIdentity}'
    }
}
$Packages = @(
    @{ Id = "my-public-certificate"; Version = "" }
    @{ Id = "my-private-certificate"; Version = "" }
    @{ Id = 'ls-central-demo-database'; Version = '' }
    @{ Id = 'bc-web-client'; Version = '' }
    @{ Id = 'bc-application'; Version = '' }
    @{ Id = 'ls-central-app-runtime'; Version = '' }
    @{ Id = 'map/ls-central-to-bc'; Version = '' }
)

$Packages | Install-UscPackage -InstanceName 'LSCentral' -UpdateStrategy 'Manual' -Arguments $Arguments

${my-private-certificate.CertificateThumbprint} and ${my-public-certificate.DnsIdentity} resolve to the corresponding parameter values from the certificate packages being installed.

Use system and instance variables in a connection string

This example constructs a connection string dynamically using the SQL Server instance and the package instance name.

$Arguments = @{
    'bc-server' = @{
        ConnectionString = 'Data Source=${System.SqlServerInstance};Initial Catalog=${Package.InstanceName};Integrated Security=true'
    }
}
$Packages = @(
    @{ Id = 'bc-server'; Version = '' }
)

$Packages | Install-UscPackage -InstanceName 'LSCentral' -UpdateStrategy 'Manual' -Arguments $Arguments

${System.SqlServerInstance} resolves to the detected SQL Server instance, and ${Package.InstanceName} resolves to LSCentral — the instance name passed to Install-UscPackage.

Use variables in a bundle's FillParameters

You can use variables in the FillParameters property when authoring a bundle package. The variables are resolved when the bundle is installed.

$SetupBundle = @{
    Id = "bundle/my-pos"
    Version = '1.0.0'
    Name = "My POS"
    Instance = $true
    Dependencies = @(
        @{ Id = 'sql-server-express'; Version = "^-"; 'Optional' = $True }
        @{ Id = "bc-web-client"; Version = $BcPlatformVersion }
        @{ Id = 'ls-central-demo-database'; Version = ">=$LsCentralVersion" }
        @{ Id = "bc-application"; Version = $BcAppVersion }
        @{ Id = 'ls-central-app-runtime'; Version = $LsCentralVersion }
        @{ Id = 'ls-central-toolbox-server'; Version = $LsCentralVersion }
        @{ Id = 'ls-dd-server-addin'; Version = "^ >=3.0 <4.0" }
        @{ Id = 'ls-hardware-station'; Version = ">=$LsCentralVersion" }
    )
    OutputDir = (Join-Path $env:TEMP 'PackagesOutput')
    FillParameters = @{
        'bc-server' = @{
            AllowSessionCallSuspendWhenWriteTransactionStarted = 'true'
        }
        'ls-central-demo-database' = @{
            ConnectionString = 'Data Source=${System.SqlServerInstance};Initial Catalog=${Package.InstanceName};Integrated Security=true'
        }
    }
}

New-UssPackage @SetupBundle | Import-UssPackage -Server $Server

The ConnectionString argument for ls-central-demo-database is built from both a system variable and a package variable, so it resolves correctly regardless of the SQL Server configuration or instance name used at install time.