Unpacking a Project with PowerShell

A Pack and Go package (a .pkgx file) bundles a project's configuration and its project files so the whole project can be moved to another system. You can unpack a package into an existing project entirely from PowerShell using the Workbench module (IcoWorkbenchPowershell), which is useful for deploying a packaged project to a target server as part of a repeatable routine rather than unpacking it by hand in the Workbench. This topic walks through the unpack routine and how to restore the package's project files to disk.

The project that will receive the package must already exist on the target server before you begin. Review the entity and key model so the way commands identify items and use keys is familiar, and confirm you are connected to the correct host as described below.

To unpack a package into a project:

1. Confirm which host the commands will configure:

   Get-WbHost

   The result is the host whose configuration your commands will change. Retarget it with Set-WbHost if you need to unpack onto a different server.

2. Get the key of the existing project that will receive the package:

   $projectKey = (Get-WbAppProject 'MyProject').Key

   Get-WbAppProject returns the project by name; capturing its Key lets you pass it to the unpack command later. The project must already exist — the unpack process adds to it rather than creating it.

3. Inspect the applications contained in the package:

   $pkgxPath = 'C:\Packages\MyProject.pkgx' $packSettings = Get-PackSettings -FileName $pkgxPath $packSettings.PackItems | Select-Object Name

   Get-PackSettings reads the package without unpacking it. Its PackItems collection lists each application (provider) the package contains, such as Assets, Triggers, or Project Files.

4. Detect the project files contained in the package:

   $packageFiles = Get-PackAndGoFilesSettings -FileName $pkgxPath $packageFiles | Select-Object FileName, RelativePath, Archive

   Get-PackAndGoFilesSettings returns the project files stored in the package and where each one belongs once restored. Reading the file list before unpacking confirms which files will be written to disk and gives you the values you need to restore a subset of them.

5. Build an unpack item for each application you want to restore. Map each packed application's name to its provider type and create an unpack item for it:

   $providerByName = @{ 'Assets' = [Ico.Config.PowershellProviderType]::Assets 'Triggers' = [Ico.Config.PowershellProviderType]::Triggers 'Project Files' = [Ico.Config.PowershellProviderType]::Files 'Security' = [Ico.Config.PowershellProviderType]::Security } $unpackItems = @() foreach ($item in $packSettings.PackItems) { $provider = $providerByName[$item.Name] if (-not $provider) { continue } $unpackItems += New-UnpackItemSettings ` -DatabaseName 'IcoUnifiedConfig' ` -DataSourceName 'TARGETSERVER\SQLEXPRESS' ` -OriginalHostName 'SOURCEHOST' ` -HostName 'TARGETHOST' ` -Provider $provider ` -Key (New-WbRootKey) ` -SecurityMode 3 }
   • -DatabaseName / -DataSourceName — the configuration database and SQL Server instance on the target system.
   • -OriginalHostName — the host the package was created on. Use the actual machine name, not localhost.
   • -HostName — the target host the project is being deployed to.
   • -Provider — the application (provider) to unpack, given as an [Ico.Config.PowershellProviderType] value (for example, Assets, Triggers, or Files for Project Files).
   • -Key — the destination for the application; New-WbRootKey unpacks it at the provider root.

   The hashtable above lists a few representative applications. Extend it to cover every application reported by Get-PackSettings in step 3 that you intend to unpack — each PackItems entry maps to an [Ico.Config.PowershellProviderType] value of the same name.

6. Decide which project files to restore. To restore all the files in the package, pass an empty list:

   $files = @()

   To restore only specific files, build a PackAndGoFilesSettings object for each one, identifying it by the RelativePath reported in step 4:

   $files = @() $one = New-Object Ico.Config.Schema.PackAndGoFilesSettings $one.RelativePath = $packageFiles[0].FileName $files += $one

   The -Files parameter behaves according to what the package contains. If the package holds files and you pass an empty list, all of its files are restored; if you pass a non-empty list, only the files that also exist in the package are restored. If the package contains no files, the parameter is ignored. The -UnpackItems parameter works the same way for applications: pass the items you want, or an empty list to unpack none.

7. Unpack the package into the project:

   $task = Set-UnpackWbConfiguration -ProjectKey $projectKey -Path $pkgxPath -ImportMode CreateAndUpdate -UnpackItems $unpackItems -Files $files -FindReplaceItems @()
   • -ProjectKey—the key of the target project from step 2.
   • -Path—the path to the .pkgx package.
   • -ImportMode—the way the existing configuration is treated; CreateAndUpdate adds new items and updates matching ones.
   • -UnpackItems / -Files—the applications and project files assembled in the previous steps.

8. Confirm the result. The applications you unpacked appear under the project in the Workbench, and the restored project files are written to disk at the destinations defined in the package. The change is committed to the configuration immediately; see How Configuration Changes Synchronize for how the running system applies it.