Reference

This page contains reference for the script parameters and cmdlets included with powerdelivery. Some cmdlets are only available in the PowerDeliveryNode module, for use on remote nodes. All cmdlets are available in the PowerDelivery module for use when authoring and executing powerdelivery targets.

Cmdlets

Cmdlets are PowerShell functions included with powerdelivery generate files and run commands within roles.

Start-Delivery

module: powerdelivery

Starts a run of a target using powerdelivery. Must be run in the parent directory of your powerdelivery project.

Parameters

-ProjectName

The required name of the project. Powerdelivery looks for a subdirectory with this name suffixed with "Delivery".

-TargetName

The name of the target to run. Must match the name of a file in the Targets subdirectory of your powerdelivery project without the file extension.

-EnvironmentName

The name of the environment to target during the run. Must match the name of a file in the Environments subdirectory of your powerdelivery project without the file extension.

-Properties

A hash of properties to pass to the target. Typically used to pass information from build servers.

-Rollback

Causes powerdelivery to run the -Down block of roles instead of -Up, performing a rollback.

Examples

Example of starting delivery of the MyApp project targeting Release to the Production environment.

Administrator: Windows PowerShell

PS C:\MyApp> Start-Delivery MyApp Release Production

New-DeliveryProject

module: powerdelivery

Generates a new powerdelivery project. Typically run at the root of a folder with source code (git, TFS, whatever).

Parameters

-ProjectName

The required name of the project. A folder with this name suffixed with "Delivery" will be created containing the project.

-Environments

An optional array of strings with the names of the environments.

Examples

Example of creating a project named MyApp with three environments.

Administrator: Windows PowerShell

PS C:\MyApp> New-DeliveryProject MyApp "Local", "Test", "Production"

New-DeliveryRole

module: powerdelivery

Generates a new powerdelivery role. Must be run in the root directory of your powerdelivery project.

Parameters

-RoleNames

A comma-separated list of one or more names of roles to create.

The role will be created at the path:

.\Roles\<RoleName>

Examples

Example of creating a role named DeployDatabase.

Administrator: Windows PowerShell

PS C:\MyApp\MyAppDelivery> New-DeliveryRole Database
Role created at ".\MyAppDelivery\Roles\Database"

New-DeliveryRoleMigration

module: powerdelivery

Generates a new powerdelivery role migration. Must be run in the root directory of your powerdelivery project.

Parameters

-RoleName

The name of the role to add the migration script to.

-MigrationName

The name of the activity being performed in the migration. Spaces will be replaced with underscores and a timestamp will be added to the prefix of the filename

Examples

Example of creating migration for a role named Load Balancer that will update a route.

Administrator: Windows PowerShell

PS C:\MyApp\MyAppDelivery> New-DeliveryRoleMigration LoadBalancer "Update Route"
Role migration created at ".\MyAppDelivery\Roles\LoadBalancer\Migrations\20151019_112811_Update_Route.ps1"

New-DeliveryKey

module: powerdelivery

Generates a key file used to encrypt secrets.

Parameters

-KeyName

The name of the key to generate.

The key will be created at the path:

<Drive>:\Users\<User>\Documents\PowerDelivery\Keys\<Project>\<KeyName>.key

Examples

Example of creating a key named MyKey for use in encrypting secrets.

Administrator: Windows PowerShell

PS C:\MyApp> New-DeliveryKey MyKey
Key written to "C:\Users\Jayme\Documents\PowerDelivery\Keys\MyApp\MyKey.key"

New-DeliveryCredential

module: powerdelivery

Encrypts a set of credentials with a key and adds them to a powerdelivery project. Must be run in the root directory of your powerdelivery project.

Parameters

-KeyName

The name of the key to use for encryption.

-UserName

The username of the account to encrypt the password for.

The credential will be created at the path:

.\Secrets\<KeyName>\Credentials\<UserName>.credential

Examples

Example of creating a credential using a key named MyKey.

Administrator: Windows PowerShell

PS C:\MyApp\MyAppDelivery> New-DeliveryCredential MyKey "MYDOMAIN\myuser"
Enter the password for MYDOMAIN\myuser and press ENTER:
**********
Credentials written to ".\Secrets\MyKey\Credentials\MYDOMAIN#myuser.credential"

New-DeliverySecret

module: powerdelivery

Encrypts a secret with a key and adds it to a powerdelivery project. Must be run in the root directory of your powerdelivery project.

Parameters

-KeyName

The name of the key to use for encryption.

-SecretName

The name of the secret to encrypt.

-Force

Switch that forces overwrite of any existing secret file if found.

The secret will be created at the path:

.\Secrets\<KeyName>\<SecretName>.secret

Examples

Example of creating a secret using a key named MyKey.

Administrator: Windows PowerShell

PS C:\MyApp\MyAppDelivery> New-DeliverySecret MyKey MySecret
Enter the secret value for MySecret and press ENTER:
**********
Secret written to ".\Secrets\MyKey\MySecret.secret"

Get-DeliveryFilesFromAzure

module: powerdeliverynode

Downloads files that were published by powerdelivery to Windows Azure during the current run of a target onto a node.

Parameters

-Target

The $target parameter from the role.

-Path

The path of files to download relative to the release directory (<ProjectName>/<StartedAt>) uploaded to Azure with the Publish-DeliveryFilesToAzure cmdlet.

-Destination

The directory in which to place downloaded files. The New-DeliveryReleasePath cmdlet is recommended to enable rollback via the Undo-DeliveryReleasePath cmdlet in a Down block.

-Credential

The Windows Azure account credentials to use. You must configure the computer running powerdelivery as described in using credentials in remote roles for these to travel from to the node that will download files with this cmdlet.

-SubscriptionId

A Windows Azure subscription that the account in the Credential parameter is permitted to use.

-StorageAccountName

A Windows Azure storage account that the account in the Credential parameter is permitted to access.

-StorageAccountName

A Windows Azure storage account key that matches the StorageAccountName parameter providing read access.

-StorageContainer

A container within the Windows Azure storage account referred to in the StorageAccountName parameter that contains files uploaded with the Publish-DeliveryFilesToAzure cmdlet in a prior role that ran on localhost to create a release.

Examples

Example of getting release files from Windows Azure that were uploaded during the current target run.

Delivery:Role {
  param($target, $config, $node)

  # You must install PowerDeliveryNode using chocolatey in a 
  # role that has run before this one on the remote node first.
  Import-Module PowerDeliveryNode

  # $releasePath will be C:\Users\<User>\AppData\Roaming\<Project>\Current 
  # pointing to a yyyyMMdd_HHmmss folder in the same directory.
  $releasePath = New-DeliveryReleasePath $target [Environment]::GetFolderPath("AppData")
  
  # Downloads files within the folder "MyApp" that were uploaded to Azure
  # into a local directory for the release on the node created above.
  Get-DeliveryFilesFromAzure -Target $target `
                             -Path "MyApp" `
                             -Destination $releasePath `
                             -Credential $target.Credentials['admin@myazuredomain.com'] `
                             -SubscriptionId $config.MyAzureSubsciptionId `
                             -StorageAccountName $config.MyAzureStorageAccountName `
                             -StorageAccountKey $config.MyAzureStorageAccountKey `
                             -StorageContainer $config.MyAzureStorageContainer
}

Get-DeliveryFilesFromS3

module: powerdeliverynode

Downloads files that were published by powerdelivery to an AWS Simple Storage Service bucket during the current run of a target onto a node.

Parameters

-Target

The $target parameter from the role.

-Path

The path of files to download relative to the release directory (<ProjectName>/<StartedAt>) uploaded to S3 with the Publish-DeliveryFilesToS3 cmdlet.

-Destination

The directory in which to place downloaded files. The New-DeliveryReleasePath cmdlet is recommended to enable rollback via the Undo-DeliveryReleasePath cmdlet in a Down block.

-ProfileName

The name of the AWS profile containing credentials to use.

-BucketName

The name of the S3 bucket that contains files uploaded with the Publish-DeliveryFilesToS3 cmdlet in a prior role that ran on localhost to create a release.

-ProfilesLocation

The location to look in for the AWS profile containing credentials.

Examples

Example of getting release files from S3 that were uploaded during the current target run.

Delivery:Role {
  param($target, $config, $node)

  # You must install PowerDeliveryNode using chocolatey in a 
  # role that has run before this one on the remote node first.
  Import-Module PowerDeliveryNode

  # $releasePath will be C:\Users\<User>\AppData\Roaming\<Project>\Current 
  # pointing to a yyyyMMdd_HHmmss folder in the same directory.
  $releasePath = New-DeliveryReleasePath $target [Environment]::GetFolderPath("AppData")
  
  # Downloads files within the folder "MyApp" that were uploaded to S3
  # into a local directory for the release on the node created above.
  Get-DeliveryFilesFromS3 -Target $target `
                          -Path "MyApp" `
                          -Destination $releasePath `
                          -ProfileName "MyProfile" `
                          -BucketName "MyAppReleases"
}

Publish-DeliveryFilesToAzure

module: powerdelivery

Uploads files for a powerdelivery release to Windows Azure for use by nodes that will host the product. All files that are uploaded are prefixed with a path that contains the name of the powerdelivery project and a timestamp of the date and time that the target started.

Parameters

-Path

The path of files to upload relative to the directory above your powerdelivery project.

-Destination

The directory in which to place uploaded files.

-Credential

The Windows Azure account credentials to use.

-SubscriptionId

A Windows Azure subscription that the account in the Credential parameter is permitted to use.

-StorageAccountName

A Windows Azure storage account that the account in the Credential parameter is permitted to access.

-StorageAccountName

A Windows Azure storage account key that matches the StorageAccountName parameter providing read and write access.

-StorageContainer

A container within the Windows Azure storage account referred to in the StorageAccountName parameter into which to upload files.

-Filter

A comma-separated list of file extensions to filter for. Others will be excluded.

-Include

A comma-separated list of paths to include. Others will be excluded.

-Exclude

A comma-separated list of paths to exclude. Others will be included.

-Recurse

Uploads files in subdirectories below the directory specified by the Path parameter.

-Keep

The number of previous releases to keep. Defaults to 5.

Examples

Example of uploading release files to Windows Azure that were compiled during the current target run.

Delivery:Role {
  param($target, $config, $node)
  
  # Recursively uploads files within the folder "MyApp\bin\Release" to a Windows Azure 
  # storage container below a <ProjectName>\<StartedAt> path.
  Publish-DeliveryFilesToAzure -Path "MyApp\bin\Debug" `
                               -Destination "MyApp" `
                               -Credential $target.Credentials['admin@myazuredomain.com'] `
                               -SubscriptionId $config.MyAzureSubsciptionId `
                               -StorageAccountName $config.MyAzureStorageAccountName `
                               -StorageAccountKey $config.MyAzureStorageAccountKey `
                               -StorageContainer $config.MyAzureStorageContainer `
                               -Recurse
}

Publish-DeliveryFilesToS3

module: powerdelivery

Uploads files for a powerdelivery release to AWS Simple Storage Service for use by nodes that will host the product. All files that are uploaded are prefixed with a path that contains the name of the powerdelivery project and a timestamp of the date and time that the target started.

Parameters

-Path

The path of files to upload relative to the directory above your powerdelivery project.

-Destination

The directory in which to place uploaded files.

-Credential

The Windows Azure account credentials to use.

-ProfileName

The name of the AWS profile containing credentials to use.

-BucketName

The name of the S3 bucket to publish the release to.

-Filter

A comma-separated list of file extensions to filter for. Others will be excluded.

-Include

A comma-separated list of paths to include. Others will be excluded.

-Exclude

A comma-separated list of paths to exclude. Others will be included.

-Recurse

Uploads files in subdirectories below the directory specified by the Path parameter.

-Keep

The number of previous releases to keep. Defaults to 5.

-ProfilesLocation

The location to look in for the AWS profile containing credentials.

Examples

Example of uploading release files to S3 that were compiled during the current target run.

Delivery:Role {
  param($target, $config, $node)
  
  # Recursively uploads files within the folder "MyApp\bin\Release" 
  # to an AWS S3 bucket below a <ProjectName>\<StartedAt> path.
  Publish-DeliveryFilesToS3 -Path "MyApp\bin\Debug" `
                            -Destination "MyApp" `
                            -ProfileName "MyProfile" `
                            -BucketName "MyAppReleases" `
                            -Recurse
}

Invoke-MSBuild

module: powerdelivery

Compiles a project using msbuild.exe.

Parameters

-ProjectFile

A relative path to the directory above your powerdelivery project that specifies an MSBuild project or solution to compile.

-Properties

Optional. A PowerShell hash containing name/value pairs to set as MSBuild properties.

-Target

Optional. The name of the MSBuild target to invoke in the project file. Defaults to the default target specified within the project file.

-ToolsetVersion

Optional. The version of MSBuild to run ("2.0", "3.5", "4.0", etc.). The default is "4.0".

-Verbosity

Optional. The verbosity of this MSBuild compilation. The default is "m".

-BuildConfiguration

Optional. The build configuration (Debug/Release typically) to compile with. Defaults to Release.

-Flavor

Optional. The platform configuration (x86, x64 etc.) of this MSBuild complation. The default is AnyCPU.

-IgnoreProjectExtensions

Optional. A semicolon-delimited list of project extensions (".smproj;.csproj" etc.) of projects in the solution to not compile.

Examples

Example of invoking msbuild.

Delivery:Role {
  param($target, $config, $node)

  Invoke-MSBuild MyProject/MyProject.csproj -Flavor x64 -properties @{MyCustomProp = SomeValue}
}

New-DeliveryReleasePath

modules: powerdeliverynode

Creates a new release directory on a remote node being deployed to with powerdelivery. A directory will be created within the path you specify and named after the ProjectName property of the $target parameter. A directory will be created within it with the timestamp of the current run (StartedAt property of $target) and symbolicly linked to “Current”.

Any releases older than the number in the Keep parameter will be deleted.

Parameters

-Target

The hash of target properties for the powerdelivery run.

-Path

The parent path into which to create the release path.

-Keep

The number of previous releases to keep. Defaults to 5.

Returns

The path to the new release directory. Copy files from your network drive, Azure storage container, S3 bucket, DropBox or whatever you use to get files to the node.

Examples

Example of creating a release path below AppData\Roaming.

Delivery:Role -Up {
  param($target, $config, $node)

  # You must install PowerDeliveryNode using chocolatey in a 
  # role that has run before this one on the remote node first.
  Import-Module PowerDeliveryNode

  # $releasePath will be C:\Users\<User>\AppData\Roaming\<Project>\Current
  # pointing to a yyyyMMdd_HHmmss folder in the same directory.
  $releasePath = New-DeliveryReleasePath $target [Environment]::GetFolderPath("AppData")
} -Down {

	# You must install PowerDeliveryNode using chocolatey in a 
  # role that has run before this one on the remote node first.
  Import-Module PowerDeliveryNode
  
  # This will rollback a previous release. If no previous 
  # release exists it will be the same path as current.
  $releasePath = Undo-DeliveryReleasePath $target [Environment]::GetFolderPath("AppData")
}

The release will be created at the path:

C:\Users\<User>\AppData\Roaming\<Project>\<StartedAt>

And symlinked to:

C:\Users\<User>\AppData\Roaming\<Project>\Current

Undo-DeliveryReleasePath

modules: powerdeliverynode

Rolls back to a previous release directory on a remote node being deployed to with powerdelivery. Modifies the symbolic link pointing to the current release path to point to the previous release and deletes the old current release directory. If no previous release exists, will leave the current release as is and return it.

Parameters

-Target

The hash of target properties for the powerdelivery run.

-Path

The parent path in which to look for releases.

Returns

The path to the previous release directory. If no previous release was found, will be the current path. Copy files from your network drive, Azure storage container, S3 bucket, DropBox or whatever you use to get files to the node.

Examples

Example of rolling back a release path below AppData\Roaming.

Delivery:Role -Up {
  param($target, $config, $node)

  # You must install PowerDeliveryNode using chocolatey in a 
  # role that has run before this one on the remote node first.
  Import-Module PowerDeliveryNode

  # $releasePath will be C:\Users\<User>\AppData\Roaming\<Project>\Current
  # pointing to a yyyyMMdd_HHmmss folder in the same directory.
  $releasePath = New-DeliveryReleasePath $target [Environment]::GetFolderPath("AppData")
} -Down {

	# You must install PowerDeliveryNode using chocolatey in a 
  # role that has run before this one on the remote node first.
  Import-Module PowerDeliveryNode
  
  # This will rollback a previous release. If no previous 
  # release exists it will be the same path as current.
  $releasePath = Undo-DeliveryReleasePath $target [Environment]::GetFolderPath("AppData")
}

The releases will be looked for in the path:

C:\Users\<User>\AppData\Roaming\<Project>

And the previous release symlinked to:

C:\Users\<User>\AppData\Roaming\<Project>\Current

Test-CommandExists

modules: powerdelivery, powerdeliverynode

Tests whether a command (PowerShell or regular command line) is available in the PATH.

Parameters

-CommandName

The name of the command to test for the presence of.

Returns

Returns $true if the command is present, or $false if not.

Examples

Example of testing for the presence of the nodejs package manager.

Delivery:Role {
  param($target, $config, $node)

  if (Test-Command npm) {
    Write-Host "Node package manager is installed!"
  }
}

Script Parameters

The scripts you work with in powerdelivery take a number of parameters that help your releases go smoothly.

$shared

A hash containing the variables from the shared variables file, allowing it to be referenced in an environment variables file.

Examples

Example of a shared configuration script defining a variable.

param($target)
@{
  SomeDirectory = "C:\Parent"
}

Example of a production environment configuration script referencing the shared variable.

param($target, $shared)
@{
  # SomeDirectoryChild would be C:\Parent\Child 
  # when targeting the Production environment
  SomeDirectoryChild = "$($shared.SomeDirectory)\Child"
}

$config

A hash containing the variables of the current run.

Examples

Example of a configuration script defining two variables.

param($target, $config)
@{
  Hello = "Hello";
  World = "World"
}

Example of a role script using the $config parameter to reference the configuration above.

Delivery:Role {
  param($target, $config, $node)

  # Prints "Hello World" to the console
  Write-Host "$($config.Hello) $($config.World)"
}

$node

The IP address, computer name, domain name, or connection URI of the node in the current environment which is currently executing a role script.

Examples

Example environment script.

param($target, $config)
@{
  Databases = @{
    Hosts = "x.x.x.1", "x.x.x.2"
  }
}

Example of a role script printing the current node to the console.

Delivery:Role {
  param($target, $config, $node)

  # Displays "x.x.x.1" or "x.x.x.2" depending on 
  # which host the role is executing on
  Write-Host $node
}

$target

References the current run of the target. The target parameter is a hash that provides a number of properties that can be used in scripts.

Properties

ProjectName

The name of the project.

TargetName

The name of the target during this run.

EnvironmentName

The name of the environment during this run.

RequestedBy

The username of the Windows account that started the run.

StartDate

A timestamp of when the run started as a DateTime object.

StartedAt

A timestamp of when the run started in the format yyyyMMdd_HHmmss.

Properties

The hash of properties passed into Start-Delivery. Typically used to get information from build servers.

Credentials

A dictionary (hash) containing the credentials that were loaded at startup. The key of the hash is the username of the credential.

Secrets

A dictionary (hash) containing the secrets that were loaded during startup. The key of the hash is the name of the secret. </dl>

Examples

Example of a role script using the $target parameter.

Delivery:Role {
  param($target, $config, $node)

  # Access run properties using $target and print them to the console
  Write-Host "I'm deploying $($target.ProjectName) started by $($target.RequestedBy)."

  # Lookup credentials using $target
  $opsCredentials = $target.Credentials["DOMAIN\opsuser"]

  # Lookup a secret using $target
  $facebookAPIKey = $target.Secrets.FacebookAPIKey
}

MyAppDelivery\Roles\TargetExample\Role.ps1

powerdelivery