Deploy Packages Using PowerShell

You can use the PowerShell snap-in to automate deployment of package files (*.kspx) to target environments. This may be especially useful where it is necessary to make regular or frequent package deployments, or where script-based installations and updates are preferred.

Prerequisites

Microsoft Management Console (MMC) 3.0 or later, and Microsoft PowerShell 3.0 or later, are prerequisites for Package and Deployment. MMC 3.0 and PowerShell 3.0 are components of the Windows Management Framework 3.0 package, available at https://www.microsoft.com/en-us/download/details.aspx?id=34595.

Quick steps

The following high-level steps outline how you use PowerShell deployment:

1. Create a deployment package using Package and Deployment.
2. Open PowerShell. Add the Package and Deployment snap-in.
3. Run the Write-DeploymentConfig command to create the deployment configuration *.XML file for the package file generated in step 1.
4. Edit the deployment configuration file to customize the default settings for the specific deployment.
5. Run the Deploy-Package command to deploy the package.

Loading the PowerShell snap-in and Generating the Configuration File

1. Open Microsoft PowerShell with administrator privileges.

   When copying code from this Help file to the PowerShell interface, make sure there aren't any extra line breaks in the code text.

2. Enter the PowerShell environment setup command. You use this command for every deployment:
   Copy

   Adds the PowerShell Deployment snapin

   1
   add-pssnapin SourceCode.Deployment.PowerShell

3. The Write-DeploymentConfig command takes two arguments, the package file and the XML file, and examines the package and creates the configuration file with default values for all artifacts. This *.XML file is what you edit to change these defaults, then use it with the Deploy-Package command to create or update artifacts on the target environment. An example of this command is as follows:
   Copy

   Scripts the sample XML configuration file to be used for deployment

   1
   Write-DeploymentConfig 'C:\Users\Dewald\Desktop\Perf Packages\RTM\Package3.kspx' 'C:\Users\Dewald\Desktop\Perf Packages\RTM\Package3.xml'

4. You can customize the Write-DeploymentConfig command with the following options:

   • -InputFile (where 'InputFile' is the *.KSPX (package) file to be deployed.)

   • -OutputFile (where 'OutputFile' is the corresponding *.XML configuration file which will be generated.)

   • An optional command is -ConnectionString (connection string to server, for example: “Host=LOCALHOST;Port=5555;Integrated=True;IsPrimaryLogin=True”. Defaults are used if not specified)

5. Edit the contents of the configuration *.XML file to customize the artifact settings, using the ResolveOptions options below.
6. The ResolveOptions section of the *.XML configuration file contains two sub-sections:
   • defaultOptions (This section sets the default action for the namespaces contained in the package.)
   • specificOptions (This section sets actions for each of the artifacts contained in the package.)
   
   

   The following configuration options are supported by the product PowerShell snap-in:

   • Default (Applies the default action)
   • Deploy (Deploys the item)
   • Exclude (Excludes the item)
   • UseExisting (Uses an existing item on the target server)

   You must insert these options into the configuration file. Service instances and environmental fields always default to "UseExisting" and must manually be changed to "Deploy" or "Default". In context of the *.XML, each configuration option must be phrased as an action which is applied to a specific artifact. For example, if you applied the UseExisting configuration command to a 'From Address' field, it would look like the following:
       <resolve name="From Address" namespace="urn:SourceCode/EnvironmentSettings/Fields" action="UseExisting" />

Note that in order for the UseExisting option to function, the item must exist on the target environment. If the item you're deploying has a different name, include the targetName and targetNamespace attributes so that they can be matched on the server.

For information on variables, refer to the 'Assigning Variables' sub-section of 'Creating a Package'.

Deploying the Package

1. Once you have created and edited the package configuration file, use the Deploy-Package command to deploy the package Commands for the Deploy-Package command are:
   • -FileName (Required) The full name and file extension of the package *.kspx file
   • -ConfigFile (Optional) If an *.XML configuration file with the same name as the package file is found in the same folder, it is used. If you have stored the *.XML configuration file in another location, specify the full path
   • -ConnectionString (Optional) The connection string to the server, for example: “Host=LOCALHOST;Port=5555;Integrated=True;IsPrimaryLogin=True”. Defaults are used if not specified
   • -NoAnalyze (Optional) This switch defaults to False which means the package is analyzed before deployed. This is the recommended approach
   
   
2. The following options are available when specifying a -ConnectionString:
   • -K2Host Specify the server name. LOCALHOST is the default
   • -Port The port through which package and deployment connects to the server. S5555 is the default
   • -Integrated (Optional) Specify whether the connection is integrated or not. True is the default and uses credentials of the person executing the command
   • -IsPrimaryLogin (Optional) True is the default
   • -UserName (Required if Integratedis set to 'False') The username used for connecting to the server
   • -Password (Required if Integrated is set to 'False') The password used for connecting to the server
   • -WindowsDomain (Required if Integrated is set to 'False') The domain associated with the UserName
   • -SecurityLabel (Required if Integratedis set to 'False') For example, 'K2'

   A sample Deploy-Package command is as follows:

   Copy

   Scripts the deployment of a package

   1
   Deploy-Package -FileName 'C:\TestPackage.kspx' -ConfigFile 'C\TestPackage.XML'

3. When deployment is successful, deployed items are shown as the PowerShell executes, for example:
   

Important Considerations

You specify service instances using the namespace and class structure, while all other artifacts use the namespace and name structure. All structures must be unique.

For example, the SQL Server Service is specified in the configuration file as shown below. Note that %2E is used to denote a full stop/period character:

1
SourceCode%2ESmartObjects%2EServices%2ESQL%2EsqlServerService

The namespace structure used for Package and Deployment directly relates to the namespace and class within the assembly, which inherits properties from ServiceAssemblyBase. For the SQL Server Service example, the name of the assembly is SourceCode.SmartObjects.Services.SqlServer.dll. However, the namespace and class structure is as follows:

1
2
3
4
5
6
7
8
9
namespace

                SourceCode.SmartObjects.Services.SQL

                {

                public class SqlServerService : ServiceAssemblyBase

            {

More examples

PowerShell deployments to distributed environments

When you use PowerShell to deploy in a distributed environment, i.e. when you're not logged in to the server, you must specify named parameters, including a connection string, in the following format: -FileName -ConfigFile -ConnectionString.

A sample command for deployments to distributed environments might be presented as follows:
Deploy-Package -FileName 'C:\GenericPackage.kspx' -ConfigFile 'C:\GenericPackage.XML' -ConnectionString 'Host=main.hostserver.local;Port=5555;Integrated=True; IsPrimaryLogin=True;SecurityLabelName=K2;UserID=User1; Password=mypassword;WindowsDomain=MYDOMAIN'

CRM

To deploy a CRM SmartObject using PowerShell there must be an existing CRM service instance in the destination environment. The CRM service instance SystemName and GUID must also match the CRM service instance of the source environment. To specify that the service instance should use the existing service instance, update the referenceOptions as follows:

<referenceOptions>

<rebind id="1727" name="CRM_Denallix" baseType="SourceCode.SmartObjects.CRM5Entity.CRMEntityService" action="UseExisting" targetName="CRM_Denallix" />

</referenceOptions>

Deployment log file

By default, the deployment log file is saved to the same location as the package file you used for the deployment.