Create Packages using PowerShell
Use the PowerShell snap-in to automate the creation and deployment of single or multiple artifact packages from source environments to target environments. This is especially useful where you need to make regular or frequent package creation or deployments, or where script-based installations and updates are preferred. See Deploy Packages Using PowerShell for more information about deploying Packages using PowerShell.
- PowerShell package creation uses namespaces. For a detailed explanation, see the Important Considerations section below.
- This method is not faster than creating a package using Package and Deployment, as all the validation and dependency checking is still done through the API. However, it can be scripted or scheduled to run without human intervention.
- SharePoint items can be packaged using PowerShell, however, you cannot deploy packages containing SharePoint artifacts with the Powershell snap-in, you must use Package and Deployment.
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 creation:
- Create a package using Package and Deployment.
- Open PowerShell. Add the Package and Deployment snap-in.
- Run the Write-PackageConfig command to create the package creation configuration *.XML file for the package file generated in step 1.
- Edit the package creation configuration file to customize the settings for the specific package.
- Run the New-Package command to create the package.
Once you have created a package as per step 1 of the Quick steps, follow the steps below to add the PowerShell snap-in and generate the configuration file.
- 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.
- Enter the PowerShell environment setup command to add the PowerShell snap-in. You use this command for every package creation:
- Enter the Write-PackageConfig command to create a configuration file that you will use to customize the artifact settings for creating the package. This command takes two arguments: the package file, and the XML file. It examines the package and creates the configuration file with default values for all artifacts. This *.XML file is what you edit to specify what you want to package, then use the New-Package command to create the package. An example of this command is as follows:
Copy
Scripts the sample XML configuration file to be used for package creation
Write-PackageConfig C:\Powershell\MyPackage.kspx C:\Powershell\MyPackage.xml
Customize the Write-PackageConfig command with the following options:
-InputFile (where 'InputFile' is the *.KSPX (package) file you created.)
-OutputFile (where 'OutputFile' is the corresponding *.XML configuration file that 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)
Example of a generated configuration file
Edit the contents of the configuration *.XML file to customize the artifact settings, using the parameters below:
- <p validate="true"> - Validates package items on creation when this parameter is set to “true”. If any validation errors are detected, an error log file is produced in the same location as the package. If this parameter is set to "false", no validation occurs when the package is created. Copy
Validate package example
<?xml version="1.0" encoding="utf-8"?>
<c xmlns="http://schemas.k2.com/Package">
<p validate="true" > - <p cat=“Category name"> - If you want to specify a category to be packaged, the cat parameter can be used, for example <p cat="Hello World Solution". The entire contents of the category (including dependencies) is packaged. When you specify a category name, the first category that matches that name is used in the package. If the category that you want to package has the same name as another but is nested, you can specify a path in the argument for example cat=“root/Sales/MyLeave”Copy
Example with category specified
<?xml version="1.0" encoding="utf-8"?>
<c xmlns="http://schemas.k2.com/Package">
<p cat="Hello World Solution" validate="true" >
- n – the type name of the item
- ns - the basenamespace of the item
Examples of type names and basenamespaces
- n=“SmartObject” ns=“urn:SourceCode/SmartObjects”
- n=“View” ns=“urn:SourceCode/SmartForms”
- n=“Form” ns=“urn:SourceCode/SmartForms”
- n=“Workflow” ns=@“urn:SourceCode/Workflow”
Example of using exclude parameter to exclude all forms from the package
<?xml version="1.0" encoding="utf-8"?>
<c xmlns="http://schemas.k2.com/Package">
<p validate="true" >
<exs>
<e n="Form" ns="urn:SourceCode/SmartForms">
</exs>
- n - the name of the item
ns - the namespace of the item
includeDependencies – by specifying either "true" or "false", dependencies of that line item are included or excluded when packaging
Example of using include parameter
<incs>
<i n="Validation View" ns="urn:SourceCode/SmartForms/View" includeDependencies="true" />
<i n="ValidSmO" ns="urn:SourceCode/SmartObjects/SmartObject" includeDependencies="true" />
<i n="ValidSmO" ns="urn:SourceCode/SmartObjects/SmartObjectData?ValidSmO" includeDependencies="true" />
</incs>
- n - the name of the item
- ns - the namespace of the item
- includeDependencies – by specifying either "true" or "false", dependencies of that line item are included or excluded when removing the item from packaging
Examples of type names and basenamespaces
- n=“SmartObject” ns=“urn:SourceCode/SmartObjects/SmartObject”
- n=“View” ns=“urn:SourceCode/SmartForms/View”
- n=“Form” ns=“urn:SourceCode/SmartForms/Form”
- n=“Workflow” ns=“urn:SourceCode/Workflows”
Example of using remove parameter
<rem>
<r n="StandaloneSmartObject" ns="urn:SourceCode/SmartObjects/SmartObject" includeDependencies="true" />
</rem>
- n - the name of the item
ns - the namespace of the item. “urn:SourceCode/ModelVariables”
desc – description (optional)
type - variable type
value - value of variable
Example of using the variable parameter
<vars>
<v n="FromAddressEmail" ns="urn:SourceCode/ModelVariables" desc="Descroption for Variable Email Add" type="String" value="k2service@denallix.com">
<vr n="FieldValue" ns="urn:SourceCode/EnvironmentSettings/Fields?From Address" />
</v>
<v n="DateTimeVar" ns="urn:SourceCode/ModelVariables" desc="" type="DateTime" value="1/1/0001 12:00:00 AM">
<vr n="DateTimeVar" ns="urn:SourceCode/Workflows?Vars\vars Workflow#DataField" />
</v>
<v n="IntVar" ns="urn:SourceCode/ModelVariables" desc="" type="Int32" value="2">
<vr n="IntVar" ns="urn:SourceCode/Workflows?Vars\vars Workflow#DataField" />
</v>
<v n="TextVar" ns="urn:SourceCode/ModelVariables" desc="" type="String" value="Bloop">
<vr n="TextVar" ns="urn:SourceCode/Workflows?Vars\vars Workflow#DataField" />
</vars>
Once you have created and edited the package configuration file, use the New-Package command to create the package. Customize the New-Package command with the following options:
- -FileName (Required) The full name and file extension of the package *.kspx file to be created.
- -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
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 New-Package command is as follows:
Scripts the creation of a package
New-Package C:\Powershell\MyPowerShellPackage.kspx C:\Powershell\MyPackage.xml -OutputLog true
By default, the output log file is saved to the same location as the package file you used for the creation.
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:
urn:SourceCode/SmartObjects/ServiceInstance
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:
Namespace and class structure
namespace
SourceCode.SmartObjects.Services.SQL
{
public class SqlServerService : ServiceAssemblyBase
{
More examples
Example | Output | Explanation |
---|---|---|
urn:SourceCode/Categories?AdventureWorks#Path.%2F represents a 'root' category called 'AdventureWorks' | 1. AdventureWorks | urn:SourceCode/Categories defines the namespace of the object. ?AdventureWorks defines the 'Instance name' of the object (In this case, a category called AdventureWorks (i.e. '/AdventureWorks/')). #Path defines the object path. In this instance, the object path is 'blank', as AdventureWorks is the 'root' category. %2F is the path-separator symbol, being URI code for the 'forward slash' used as a separator. |
urn:SourceCode/Categories?Production#Path.%2FAdventureWorks %2F represents a sub-category under 'AdventureWorks' called 'Production' | 1. AdventureWorks
a. Production |
The definitions are the same as for the first example. However, in this instance, Path.%2FadventureWorks%2F defines the object path (In this case, a category below 'AdventureWorks' called 'Production' (i.e. /AdventureWorks/Production/ )). |
urn:SourceCode/Categories?Forms#Path.%2FAdventureWorks%2FProduction%2F represents a sub-category under 'AdventureWorks' and 'Production' called 'Forms' | 1. AdventureWorks
a. Production i. Forms |
The definitions are the same as for the first example. However, in this instance, Forms#Path.%2FAdventureWorks%2FProduction%2F defines the object path (in this case, a sub-category below 'AdventureWorks' and 'Production', called 'Forms', i.e. /AdventureWorks/Production/Forms/). |