Built-in Operations

.net

Build MSBuild Project - Builds a project or solution using MSBuild.

Build MSBuild Project

Builds a project or solution using MSBuild.

Script usage:

MSBuild::Build-Project(
	ProjectFile: <text>,
	[Configuration: <text>],
	[Platform: <text>],
	[MSBuildProperties: <@(text)>],
	[Arguments: <text>],
	[MSBuildToolsPath: <text>],
	[To: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Project file (default)	text	ProjectFile	This argument is required.
Configuration	text	Configuration
Target platform	text	Platform
MSBuild properties	@(text)	MSBuildProperties	Additional properties to pass to MSBuild, formatted as key=value pairs.
Additional arguments	text	Arguments	Raw command line arguments to pass to MSBuild.
MSBuild tools path	text	MSBuildToolsPath	Full path of the directory containing the MSBuild tools to use. This is usually similar to C:\Program Files (x86)\MSBuild\14.0\Bin. If no value is supplied, the operation will use vswhere to determine the path to the latest installation of MSBuild
Target directory	text	To

Ensure AppSetting - Ensures a .NET application configuration file has the specified appSetting key/value pair.

Ensure AppSetting

Ensures a .NET application configuration file has the specified appSetting key/value pair.

Script usage:

DotNet::Ensure-AppSetting(
	File: <text>,
	Key: <text>,
	Value: <text>,
	[AppSettingsXPath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Config file path	text	File	The file path of the configuration file, typically web.config or app.config. This argument is required.
☆ AppSetting key	text	Key	This argument is required.
☆ AppSetting value	text	Value	This argument is required.
XPath for appSettings	text	AppSettingsXPath

Note: By default, the "appSettings" section must exist in the file under the "configuration" element in order to ensure the key/value pair is present. Use the AppSettingsXPath argument to select a different element instead.

Example:

# ensures that the application is configured to use test mode for the example third-party API
DotNet::Ensure-AppSetting(
	File: E:\Website\web.config,
	Key: Accounts.ThirdParty.PaymentApi,
	Value: https://test.example.com/api/v3
);

Write Assembly Versions - Updates AssemblyVersion, AssemblyFileVersion, and AssemblyInformationalVersion Attributes (in AssemblyInfo source files).

Write Assembly Versions

Updates AssemblyVersion, AssemblyFileVersion, and AssemblyInformationalVersion Attributes (in AssemblyInfo source files).

Script usage:

Write-AssemblyVersion(
	[Version: <text>],
	[FromDirectory: <text>],
	[Include: <@(text)>],
	[Exclude: <@(text)>]
);

This operation may be prefixed with DotNet::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Version	text	Version
From directory	text	FromDirectory
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude

Amazon

Upload Files to S3 - Transfers files to an Amazon S3 bucket.

Upload Files to S3

Transfers files to an Amazon S3 bucket.

Script usage:

AWS::Upload-Files(
	[From: <text>],
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	Bucket: <text>,
	[To: <text>],
	[ReducedRedundancy: <true/false>],
	[Public: <true/false>],
	[Encrypted: <true/false>],
	[Credentials: <text>],
	[AccessKey: <text>],
	[SecretAccessKey: <text>],
	[RegionEndpoint: <text>],
	[PartSize: <Int64>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Source directory	text	From
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
☆ Bucket	text	Bucket	This argument is required.
Target folder	text	To	The directory in the specified S3 bucket that will receive the uploaded files.
Use reduced redundancy	true/false	ReducedRedundancy
Make public	true/false	Public
Encrypted	true/false	Encrypted
Credentials	text	Credentials
Access key	text	AccessKey
Secret access key	text	SecretAccessKey
Region endpoint	text	RegionEndpoint
Part size	Int64	PartSize	The size (in bytes) of individual parts for an S3 multipart upload.

Artifacts

Create Artifact - Collects all of the files in a directory, compresses them in a zip file, and saves it to the artifact library.

Create Artifact

Collects all of the files in a directory, compresses them in a zip file, and saves it to the artifact library.

Script usage:

Create-Artifact(
	Name: <text>,
	[From: <text>],
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[Deployable: <text>],
	[Verbose: <true/false>],
	[IgnoreEmptyArtifact: <true/false>],
	[Overwrite: <true/false>],
	[UseLegacyStoragePath: <true/false>],
	[IncludeSystemFiles: <true/false>],
	[IncludeHiddenFiles: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Artifact name (default)	text	Name	This argument is required.
From directory	text	From
Include files	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude files	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
Deployable name	text	Deployable	Associates the created artifact with a deployable in the application; this defaults the current deployable in context.
Verbose logging	true/false	Verbose	Using this will log every file within the artifact along with all activity that occurs during the creation of the artifact. This is great for auditing or debug purposes, but it wiill take up additional log space
Ignore empty artifact	true/false	IgnoreEmptyArtifact	Checking this box will configure the Ignore Empty Artift setting, which, when checked, will ignore empty artifacts
Overwrite	true/false	Overwrite	This will overwrite existing artifacts. Re-running a plan execution will fail if the artifacts are found. Set this to true to bypass this default behavior
Use legacy storage path	true/false	UseLegacyStoragePath	See KB#1133 for information about legacy paths.
Include system files	true/false	IncludeSystemFiles	By default system files are excluded. Set this to true if you need to include all system files
Include hidden files	true/false	IncludeHiddenFiles	By default hidden files are excluded. Set this to true if you need to include all files or are unsure if there are hidden files that you may need

Note: When a deployable name is specified, the created artifact will be associated with that deployable; this is particularly useful when using imported deployables, or if you need to use the same artifact name or multiple deployables.

Deploy Artifact - Retrieves the specified artifact from the artifact library and deploys it to a directory.

Deploy Artifact

Retrieves the specified artifact from the artifact library and deploys it to a directory.

Script usage:

Deploy-Artifact(
	Name: <text>,
	[To: <text>],
	[Application: <text>],
	[Release: <text>],
	[Build: <text>],
	[Deployable: <text>],
	[DeployAsZipFile: <true/false>],
	[TransferAll: <true/false>],
	[DoNotClearTarget: <true/false>],
	[Verbose: <true/false>],
	[OverwriteReadOnly: <true/false>],
	[OptimizedFileTransfer: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Artifact name (default)	text	Name	This argument is required.
To directory	text	To
Application name	text	Application
Release number	text	Release
Build number	text	Build	Valid values are specific build numbers, or "furthest" or "latest".
Deployable name	text	Deployable
Deploy as zip	true/false	DeployAsZipFile
Transfer all files	true/false	TransferAll	By default, files will only be transferred if the last modified date or file size has changed. If set to true, all files will be transferred regardless if they have been modified. This value should generally be set to false, except when it would take more time to compare the files than simply transferring and overwriting them all (i.e. the artifact contains thousands of small files).
Do not clear target	true/false	DoNotClearTarget
Verbose logging	true/false	Verbose
Overwrite read-only files	true/false	OverwriteReadOnly
Use optimized file transfer	true/false	OptimizedFileTransfer	Transfers artifact files using a new implementation that increases performance. This feature is still experimental, so verify results before using in production. This option is ignored if TransferAllFiles is true.

Note: Specifying "latest" as the source package number will attempt to retrieve the artifact from the most recently created build, whereas "furthest" will use the one that has been deployed to the furthest environment in the pipeline.

Download Artifact from VSTS - Downloads an artifact from the specified Visual Studio Team Services server.

Download Artifact from VSTS

Downloads an artifact from the specified Visual Studio Team Services server.

Script usage:

TFS::Download-Artifact(
	[Credentials: <text>],
	[TeamProject: <text>],
	BuildDefinition: <text>,
	[BuildNumber: <text>],
	ArtifactName: <text>,
	[TfsBuildNumber: <text>],
	[TargetDirectory: <text>],
	[ExtractFiles: <true/false>],
	[Url: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Domain: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
Team project	text	TeamProject
☆ Build definition	text	BuildDefinition	This argument is required.
Build number	text	BuildNumber
☆ Artifact name	text	ArtifactName	This argument is required.
⇒ Set build number to variable	text	TfsBuildNumber	The TFS build number can be output into a runtime variable.
Target directory	text	TargetDirectory
Extract files	true/false	ExtractFiles
Project collection URL	text	Url
User name	text	UserName
Password / token	text	Password
Domain name	text	Domain

Import Artifact from VSTS - Downloads an artifact from the specified Visual Studio Team Services server and saves it to the artifact library.

Import Artifact from VSTS

Downloads an artifact from the specified Visual Studio Team Services server and saves it to the artifact library.

Script usage:

TFS::Import-Artifact(
	[Credentials: <text>],
	[TeamProject: <text>],
	BuildDefinition: <text>,
	[BuildNumber: <text>],
	ArtifactName: <text>,
	[TfsBuildNumber: <text>],
	[Url: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Domain: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
Team project	text	TeamProject
☆ Build definition	text	BuildDefinition	This argument is required.
Build number	text	BuildNumber
☆ Artifact name	text	ArtifactName	This argument is required.
⇒ Set build number to variable	text	TfsBuildNumber	The TFS build number can be output into a runtime variable.
Project collection URL	text	Url
User name	text	UserName
Password / token	text	Password
Domain name	text	Domain

BuildMaster

Create Build - Creates a new build in BuildMaster of an application, and optionally waits for it to complete.

Create Build

Creates a new build in BuildMaster of an application, and optionally waits for it to complete.

Script usage:

Create-Build(
	Application: <text>,
	[ReleaseNumber: <text>],
	[Variables: <%(key1: value1, ...)>],
	[ForcePromotion: <true/false>],
	[Wait: <true/false>],
	[FailIfCannotCreate: <true/false>]
);

This operation may be prefixed with BuildMaster::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ In application	text	Application	This argument is required.
For release number	text	ReleaseNumber	This may be a specific release number, "latest" or "all".
Build variables	%(key1: value1, ...)	Variables
Force past gate	true/false	ForcePromotion
Wait for execution	true/false	Wait
Fail if nothing created	true/false	FailIfCannotCreate

Note: When all releases is specified, then a build in *each* release will be created.

Note: When FailIfCannotCreate is specified, the execution will halt if there are no valid builds to create; for example, if the targeted release number doesn't exist. Otherwise, a warning will be issued.

Example:

Create-Build
(
    Application: Hdars.Packager,
    ReleaseNumber: latest,
    Variables: %(ReleaseCandidate: true, PackageType: $PackageType)
);

Create Release - Creates a release in another application.

Create Release

Creates a release in another application.

Script usage:

Create-Release(
	Application: <text>,
	[ReleaseNumber: <text>],
	Pipeline: <text>,
	[ReleaseName: <text>],
	[ReleaseTemplate: <text>],
	[Variables: <%(key1: value1, ...)>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ In application	text	Application	This argument is required.
Release number	text	ReleaseNumber
☆ Pipeline name	text	Pipeline	This argument is required.
Release name	text	ReleaseName
Release template	text	ReleaseTemplate
Variables	%(key1: value1, ...)	Variables

Example:

Create-Release
(
    Application: Hdars.Packager,
    ReleaseNumber: $ReleaseNumber,
    Pipeline: AutoCreate,
    ReleaseTemplate: TemplateName,
    Variables: %(TargetServer: Tst001, ReleaseType: $ReleaseType)
);

Create Release Note - Attaches a release note to the current release.

Create Release Note

Attaches a release note to the current release.

Script usage:

Create-ReleaseNote(
	[Note: <text>],
	[Application: <text>],
	[Release: <text>],
	[Build: <text>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage
Note text (default)	text	Note
Application name	text	Application
Release number	text	Release
Build number	text	Build

Example:

Create-ReleaseNote Build $ReleaseNumber.$BuildNumber deployed to ProGet.;

Deploy Build - Deploys a build in BuildMaster of an application, and optionally waits for it to complete.

Deploy Build

Deploys a build in BuildMaster of an application, and optionally waits for it to complete.

Script usage:

Deploy-Build(
	Application: <text>,
	[ReleaseNumber: <text>],
	[From: <text>],
	[To: <text>],
	[Force: <true/false>],
	[Wait: <true/false>],
	[FailIfCannotDeploy: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ In application	text	Application	This argument is required.
For release number	text	ReleaseNumber	This may be a specific release number, "latest" or "all".
From stage	text	From
To stage	text	To
Force past gate	true/false	Force
Wait for deployments	true/false	Wait
Fail if nothing is deployed	true/false	FailIfCannotDeploy

Note: When all releases is specified, then a build in *each* release will be created.

Note: When "from" or "to" pipeline stages are specified, only packages that come from or are going to those stages in their pipeline will be deployed.

Ensure Release - Ensures a release exists in another application.

Ensure Release

Ensures a release exists in another application.

Script usage:

Ensure-Release(
	[Application: <text>],
	[ReleaseNumber: <text>],
	[Pipeline: <text>],
	[ReleaseName: <text>],
	[Variables: <%(key1: value1, ...)>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage
In application	text	Application
Release number	text	ReleaseNumber
Pipeline name	text	Pipeline
Release name	text	ReleaseName
Variables	%(key1: value1, ...)	Variables

Example:

Ensure-Release
(
    Application: Hdars.Packager,
    ReleaseNumber: $ReleaseNumber,
    Pipeline: AutoCreate,
    Variables: %(TargetServer: Tst001, ReleaseType: $ReleaseType)
);

Invoke Module - Executes an OtterScript module stored in BuildMaster.

Invoke Module

Executes an OtterScript module stored in BuildMaster.

Script usage:

Invoke-Module(
	Module: <text>,
	[Arguments: <%(key1: value1, ...)>],
	[CaptureOutputArguments: <@(text)>]
);

This operation may be prefixed with BuildMaster::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Module (default)	text	Module	This argument is required.
Arguments	%(key1: value1, ...)	Arguments	Specify arguments to pass in to the module using a map. If any required values are not supplied, a runtime error will be raised. For example: %(arg1: value, arg2: @(list,of,items))
Capture output arguments	@(text)	CaptureOutputArguments	Specify output arguments to capture and set in the calling scope as variables using a list. For example: @(filePath,errorMessage)

Note: Runtime variables you've defined before executing an Invoke operation will not be visible to the invoked script, and variables that you set within the invoked script will not be available.

Example:

# This will call the global "MyModule" module and pass in an argument called $name with value "Steve"
Invoke-Module global::MyModule
(
    AdditionalArguments: %(name: Steve)
);

Invoke OtterScript - Executes an OtterScript plan specified as a string.

Invoke OtterScript

Executes an OtterScript plan specified as a string.

Script usage:

Invoke-OtterScript(
	Text: <text>,
	[AdditionalVariables: <%(key1: value1, ...)>],
	[CaptureOutputVariables: <@(text)>]
);

This operation may be prefixed with BuildMaster::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Script text (default)	text	Text	This argument is required.
Additional variables	%(key1: value1, ...)	AdditionalVariables	Specify variables to pass in to the script using a map. For example: %(var1: MyVariableValue, var2: @(list,of,items))
Capture output variables	@(text)	CaptureOutputVariables	Specify variables to capture and set in the calling scope using a list. For example: @(filePath,errorMessage)

Note: Runtime variables you've defined before executing an Invoke operation will not be visible to the invoked script, and variables that you set within the invoked script will not be available.

Example:

# This will output "Hello, Steve"
Invoke-OtterScript
(
  Text: >> 
    set $MyName = Steve;
    Log-Information Hello, `$MyName; 
    >>,
  CaptureOutputArguments: @(MyName)
);

# This will output "Hello, Steve"
Log-Information Hello, $MyName;

Invoke Plan - Executes an OtterScript plan stored in BuildMaster.

Invoke Plan

Executes an OtterScript plan stored in BuildMaster.

Script usage:

Invoke-Plan(
	Plan: <text>,
	[AdditionalVariables: <%(key1: value1, ...)>],
	[CaptureOutputVariables: <@(text)>]
);

This operation may be prefixed with BuildMaster::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Plan (default)	text	Plan	This argument is required.
Additional variables	%(key1: value1, ...)	AdditionalVariables	Specify variables to pass in to the plan using a map. For example: %(var1: MyVariableValue, var2: @(list,of,items))
Capture output variables	@(text)	CaptureOutputVariables	Specify variables to capture and set in the calling scope using a list. For example: @(filePath,errorMessage)

Note: Runtime variables you've defined before executing an Invoke operation will not be visible to the invoked script, and variables that you set within the invoked script will not be available.

Example:

# This will call the global "MyPlan" deployment plan and pass in a variable called $name with value "Steve"
Invoke-Plan global::MyPlan
(
    AdditionalVariables: %(name: Steve)
);

Manual Operation - Halts the execution until an individual or group completes a specified task.

Manual Operation

Halts the execution until an individual or group completes a specified task.

Script usage:

Perform-ManualOperation(
	Name: <text>,
	[Description: <text>],
	AssignedTo: <text>,
	[SendEmail: <true/false>],
	[CC: <@(text)>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Task name	text	Name	The name of the task that uniquely identifies it in the UI. This argument is required.
Task description	text	Description
☆ Assigned to	text	AssignedTo	The user or group who is responsible to complete the specified task. This argument is required.
Send email to assignees	true/false	SendEmail
CC email addresses	@(text)	CC

Set Build Number - Sets the build number of the currently executing build.

Set Build Number

Sets the build number of the currently executing build.

Script usage:

Set-BuildNumber <text>;

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ New build number (default)	text	BuildNumber	This argument is required.

Set Configuration Variable - Creates or updates a variable in BuildMaster.

Set Configuration Variable

Creates or updates a variable in BuildMaster.

Script usage:

Set-ConfigurationVariable(
	Variable: <text>,
	Value: <RuntimeValue>,
	[Application: <text>],
	[ApplicationGroup: <text>],
	[Deployable: <text>],
	[Server: <text>],
	[ServerRole: <text>],
	[Environment: <text>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Variable name (default)	text	Variable	This argument is required.
☆ Variable value	RuntimeValue	Value	This argument is required.
Application	text	Application
Application group	text	ApplicationGroup
Deployable	text	Deployable
Server	text	Server
Server role	text	ServerRole
Environment	text	Environment

Set Release Variable - Creates or updates a variable on a release or build.

Set Release Variable

Creates or updates a variable on a release or build.

Script usage:

Set-ReleaseVariable(
	Variable: <text>,
	Value: <RuntimeValue>,
	[Release: <text>],
	[Build: <text>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Variable name (default)	text	Variable	This argument is required.
☆ Variable value	RuntimeValue	Value	This argument is required.
Release number	text	Release
Build number	text	Build

Builds

Queue VSTS Build - Queues a build in Visual Studio Team Services, optionally waiting for its completion.

Queue VSTS Build

Queues a build in Visual Studio Team Services, optionally waiting for its completion.

Script usage:

TFS::Queue-Build(
	[Credentials: <text>],
	[TeamProject: <text>],
	BuildDefinition: <text>,
	[WaitForCompletion: <true/false>],
	[Validate: <true/false>],
	[TfsBuildNumber: <text>],
	[Url: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Domain: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
Team project	text	TeamProject
☆ Build definition	text	BuildDefinition	This argument is required.
Wait for completion	true/false	WaitForCompletion
Validate success	true/false	Validate
⇒ Set build number to variable	text	TfsBuildNumber	The TFS build number can be output into a runtime variable.
Project collection URL	text	Url
User name	text	UserName
Password / token	text	Password
Domain name	text	Domain

Configuration Files

Deploy Configuration File - Deploys an instance of a configuration file to disk after applying an optional template.

Deploy Configuration File

Deploys an instance of a configuration file to disk after applying an optional template.

Script usage:

Deploy-ConfigFile(
	ConfigFileName: <text>,
	Instance: <text>,
	[To: <text>],
	[OutputFileName: <text>]
);

This operation may be prefixed with ConfigFiles::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Configuration file name	text	ConfigFileName	This argument is required.
☆ Instance	text	Instance	This argument is required.
To directory	text	To
To file name	text	OutputFileName

Export Configuration File

Exports a configuration file instance or template to disk without recording a deployment or replacing variables.

Script usage:

Export-ConfigFile(
	ConfigFileName: <text>,
	Instance: <text>,
	[To: <text>],
	[OutputFileName: <text>]
);

This operation may be prefixed with ConfigFiles::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Configuration file name	text	ConfigFileName	This argument is required.
☆ Instance	text	Instance	This argument is required.
To directory	text	To
To file name	text	OutputFileName

Databases

Backup Database - Uses a Database Connection to back up a database to a file on disk.

Backup Database

Uses a Database Connection to back up a database to a file on disk.

Script usage:

DB::Backup-Database(
	Connection: <text>,
	Name: <text>,
	To: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Database connection	text	Connection	This argument is required.
☆ From database name	text	Name	This argument is required.
☆ To backup file	text	To	This argument is required.

Build Database Updater Executable - Generates an executable file that can act as a self-installing package of database change scripts.

Build Database Updater Executable

Generates an executable file that can act as a self-installing package of database change scripts.

Script usage:

Create-DatabaseUpdater(
	DatabaseType: <text>,
	[OutputFile: <text>],
	[ConnectionString: <text>],
	[AdditionalFilesPath: <text>],
	[Verbose: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Database type	text	DatabaseType	This argument is required.
Executable name	text	OutputFile
Embedded Connection string	text	ConnectionString
Embedded additional files	text	AdditionalFilesPath	Path of a directory containing addional scripts to embed.
Verbose	true/false	Verbose	When set to true, the operation will write to the logs more aggressively than normal. The default is false.

Execute Database Change Scripts - Executes change scripts associated with the current release and any change scripts from prior releases that have not been run against the database to date.

Execute Database Change Scripts

Executes change scripts associated with the current release and any change scripts from prior releases that have not been run against the database to date.

Script usage:

Execute-ChangeScripts(
	Connection: <text>,
	[InitializeDatabase: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Database connection	text	Connection	This argument is required.
Initialize database	true/false	InitializeDatabase

Note: When initialize database is true, the database will be initialized (i.e. a metadata table will be created too track change scripts) if it is required.

Execute Database Scripts on Disk - Finds files matching a search mask and executes those scripts against a database connection.

Execute Database Scripts on Disk

Finds files matching a search mask and executes those scripts against a database connection.

Script usage:

Execute-DatabaseScripts(
	Connection: <text>,
	[Directory: <text>],
	[Include: <@(text)>],
	[Exclude: <@(text)>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Database connection	text	Connection	This argument is required.
In directory	text	Directory
Include (default)	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.

Execute Database Statement - Executes a statement against a database.

Execute Database Statement

Executes a statement against a database.

Script usage:

Execute-DatabaseStatement(
	Connection: <text>,
	Statement: <text>
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Database connection	text	Connection	This argument is required.
☆ SQL Statement	text	Statement	This argument is required.

Example:

Execute-DatabaseStatement (
    Statement: >>
    print 'Executing BuildMaster statement...'

    select * from sys.databases
    where owner_sid > 1
    order by name

    print 'Execution complete.'
>>,
    Connection: SqlServerTesting
);

Restore Database - Uses a Database Connection to restore a database from a file on disk.

Restore Database

Uses a Database Connection to restore a database from a file on disk.

Script usage:

Restore-Database(
	Connection: <text>,
	From: <text>,
	Name: <text>,
	[Verbose: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Database connection	text	Connection	This argument is required.
☆ From backup file	text	From	This argument is required.
☆ To database name	text	Name	This argument is required.
Log database statements	true/false	Verbose

Email

Send Email - Sends an email message.

Send Email

Sends an email message.

Script usage:

InedoCore::Send-Email(
	To: <@(text)>,
	[Subject: <text>],
	[Text: <text>],
	[Html: <text>],
	[Attachments: <@(text)>],
	[AttachmentDirectory: <text>],
	[CC: <@(text)>],
	[Bcc: <@(text)>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ To address(es)	@(text)	To	A single email address may be used, or a list variable containing multiple email addresses. This argument is required.
Subject	text	Subject
Plain-text body	text	Text
HTML body	text	Html
Attachments	@(text)	Attachments
From directory	text	AttachmentDirectory
CC address(es)	@(text)	CC	A single email address may be used, or a list variable containing multiple email addresses.
BCC address(es)	@(text)	Bcc	A single email address may be used, or a list variable containing multiple email addresses.

Note: If the Html property is specified, then the Text property will be ignored.

Example:

Send-Email (
    To: @(someone@example.org, someone-else@example.org),
    Subject: Howdy!,
    Text: >>Hello there!

This email was sent from BuildMaster on $Date.>>
);

Executions

Set Execution Priority - Sets the priority of the current execution. Before an execution's priority is explicitly set, it effectively has a priority of negative infinity.

Set Execution Priority

Sets the priority of the current execution. Before an execution's priority is explicitly set, it effectively has a priority of negative infinity.

Script usage:

Set-Execution-Priority <integer>;

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Priority (default)	integer	Priority	This argument is required.

Wait for Higher Priority Executions - Waits for executions with a higher priority to complete. If the current execution has no explicitly set priority, the priority will be set to zero.

Wait for Higher Priority Executions

Waits for executions with a higher priority to complete. If the current execution has no explicitly set priority, the priority will be set to zero.

Script usage:

Wait-For-Higher-Priority-Executions(
	[Verbose: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Verbose logging	true/false	Verbose

Files

Concatenate Files - Concatenates files on a server.

Concatenate Files

Concatenates files on a server.

Script usage:

Concatenate-Files(
	File: <text>,
	[Directory: <text>],
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[Encoding: <text>],
	[Separator: <text>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Output file	text	File	This argument is required.
Directory	text	Directory
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
Encoding	text	Encoding
Separator	text	Separator

Example:

# concatenates all SQL files in the working directory into a 
# single file, each script separated by a GO statement
Concatenate-Files(
    File: all.sql,
    Include: *.sql,
    Separator: >>
GO
>>
);

Copy Files - Copies files on a server.

Copy Files

Copies files on a server.

Script usage:

Copy-Files(
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[From: <text>],
	To: <text>,
	[Verbose: <true/false>],
	[Overwrite: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
Source directory	text	From
☆ Target directory	text	To	This argument is required.
Verbose	true/false	Verbose
Overwrite target files	true/false	Overwrite

Example:

# copy all files and all subdirectories beneath it to the target,
# and log each individual file that is copied, and overwrite any files
Copy-Files(
    From: E:\Source,
    To: F:\Target,
    Include: **,
    Verbose: true,
    Overwrite: true
);

Create File - Creates a file on a server.

Create File

Creates a file on a server.

Script usage:

Create-File(
	Name: <text>,
	[Text: <text>],
	[Overwrite: <true/false>],
	[FileMode: <text>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ File name (default)	text	Name	The path of the file to create. This argument is required.
Text	text	Text
Overwrite	true/false	Overwrite
File mode	text	FileMode	The octal file mode for the file. This value is ignored on Windows.

Example:

# write the name of the current working directory to my desktop
Create-File(
    Name: C:\Users\atripp\Desktop\workingdir.txt,
    Text: $WorkingDirectory
);

Create Zip File - Creates a zip file on a server.

Create Zip File

Creates a zip file on a server.

Script usage:

Create-ZipFile(
	Name: <text>,
	Directory: <text>,
	[Overwrite: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Zip file name	text	Name	This argument is required.
☆ Source directory	text	Directory	This argument is required.
Overwrite	true/false	Overwrite

Example:

# zip all log files and place them in the backup directory
Create-ZipFile(
    Name: E:\backup\logs.$Date("yyyyMMdd-hhmmss").zip,
    Directory: E:\site\logs
);

Delete Files - Deletes files on a server.

Delete Files

Deletes files on a server.

Script usage:

Delete-Files(
	Include: <@(text)>,
	[Exclude: <@(text)>],
	[Directory: <text>],
	[Verbose: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Include (default)	@(text)	Include	See KB#1119 to learn more about masking syntax. This argument is required.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
Directory	text	Directory
Verbose	true/false	Verbose

Note: This operation will delete files one-by-one. To clear large directories, a PowerShell script may be more performant.

Example:

# delete all .config files in the working directory except web.config
Delete-Files(
    Include: *.config,
    Exlude: web.config
);

Ensure Directory - Ensures the existence of a directory on a server.

Ensure Directory

Ensures the existence of a directory on a server.

Script usage:

Ensure-Directory(
	Name: <text>,
	[Exists: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Name	text	Name	This argument is required.
Exists	true/false	Exists

Example:

# ensures the Logs directory for the website exists and that it's writable
Ensure-Directory(
    Name: E:\Website\Logs,
    ReadOnly: false
);

Ensure File - Ensures the existence of a file on a server.

Ensure File

Ensures the existence of a file on a server.

Script usage:

Ensure-File(
	[Text: <text>],
	[ReadOnly: <true/false>],
	Name: <text>,
	[Attributes: <integer>],
	[Exists: <true/false>],
	[Modified: <DateTime>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Text contents	text	Text	The contents of the file. A missing or empty value indicates the file should be a 0-byte file.
Read Only	true/false	ReadOnly	Indicates that the file should be marked with the read-only attribute. Note that when this value is set, it is applied after the FileAttributes value, which will override the readonly flag specified in that property.
☆ Name	text	Name	The name or path of the file or directory. This argument is required.
Attributes	integer	Attributes	The attributes for the file or directory. These may be entered as an integer flag or by name. Common values are ReadOnly=1, Hidden=2, System=4, Archive=32, and Normal=128. Integral values may be ORed together to specify any combination of attributes, except for "Normal (128)", which may only be used alone.
Exists	true/false	Exists
Last write time	DateTime	Modified	The last write time (UTC) of the file or directory.

Example:

# ensures the otter.txt file exists on the server and is marked readonly
Ensure-File(
    Name: E:\Docs\otter.txt,
    Text: >>
Otter is a common name for a carnivorous mammal in the subfamily Lutrinae. 
Help, I'm trapped in an Otter documentation factory! The 13 extant otter species are all semiaquatic, 
aquatic or marine, with diets based on fish and invertebrates.
>>,
    ReadOnly: true
);

Extract Zip File - Extracts a zip file on a server.

Extract Zip File

Extracts a zip file on a server.

Script usage:

Extract-ZipFile(
	Name: <text>,
	[Directory: <text>],
	[ClearTarget: <true/false>],
	[Overwrite: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ File name (default)	text	Name	This argument is required.
Target directory	text	Directory
Clear target directory	true/false	ClearTarget
Overwrite	true/false	Overwrite

Example:

# extracts archive.zip in ArchiveContents after deleting the directory contents
Extract-ZipFile(
    Name: archive.zip,
    Directory: E:\Services\ArchiveContents,
    ClearTarget: true
);

Generate Release Notes - Generates an HTML file containing the BuildMaster release notes and/or issues from the application's issue tracking provider.

Generate Release Notes

Generates an HTML file containing the BuildMaster release notes and/or issues from the application's issue tracking provider.

Script usage:

Generate-ReleaseNotes(
	Name: <text>,
	[IncludeReleaseNotes: <true/false>],
	[IncludeIssueSummary: <true/false>],
	[IncludeIssueDescriptions: <true/false>],
	[ClosedIssuesOnly: <true/false>],
	[CustomCss: <text>],
	[Overwrite: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ File name	text	Name	This argument is required.
Include release notes	true/false	IncludeReleaseNotes
Include issue summary	true/false	IncludeIssueSummary
Include issue descriptions	true/false	IncludeIssueDescriptions
Closed issues only	true/false	ClosedIssuesOnly
Custom CSS	text	CustomCss
Overwrite	true/false	Overwrite

Example:

# generates an HTML file containing this application's issues with descriptions along with release notes
Generate-ReleaseNotes(
    Name: notes.html
);

Rename File - Renames a file on a server.

Rename File

Renames a file on a server.

Script usage:

Rename-File(
	From: <text>,
	To: <text>,
	[Overwrite: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Source file	text	From	This argument is required.
☆ Target file	text	To	This argument is required.
Overwrite	true/false	Overwrite

Note: To rename multiple files at once, running a PowerShell script is recommended.

Example:

# renames logs.txt to include the environment name in context
Rename-File (
    From: logs.txt,
    To: logs.$EnvironmentName.txt,
    Overwrite: true
);

Search/Replace File Contents - Searches a text file for a specified string and replaces it.

Search/Replace File Contents

Searches a text file for a specified string and replaces it.

Script usage:

Replace-Text(
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[Directory: <text>],
	SearchText: <text>,
	[ReplaceWith: <text>],
	[Regex: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
Directory	text	Directory
☆ Search text	text	SearchText	This argument is required.
Replace with	text	ReplaceWith
Use regex	true/false	Regex

Set File Attributes - Sets or clears attributes on matching files.

Set File Attributes

Sets or clears attributes on matching files.

Script usage:

Set-FileAttributes(
	[Directory: <text>],
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[ReadOnly: <true/false>],
	[Hidden: <true/false>],
	[System: <true/false>],
	[Verbose: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Directory	text	Directory
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
Read only	true/false	ReadOnly
Hidden	true/false	Hidden
System	true/false	System
Verbose	true/false	Verbose

Transfer Files - Copies files from a directory on a source server to a directory on a target server.

Transfer Files

Copies files from a directory on a source server to a directory on a target server.

Script usage:

Transfer-Files(
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[FromDirectory: <text>],
	[FromServer: <text>],
	ToDirectory: <text>,
	[ToServer: <text>],
	[DeleteTarget: <true/false>],
	[SetLastModifiedDate: <true/false>],
	[BatchSize: <integer>],
	[Verbose: <true/false>]
);

This operation may be prefixed with Files::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
Source directory	text	FromDirectory
Source server	text	FromServer
☆ Target directory	text	ToDirectory	This argument is required.
Target server	text	ToServer
Delete target	true/false	DeleteTarget	When set to true, files in the target directory will be deleted if they are not present in the source directory. If false, files present in the target directory that are not present in the source directory are unmodified.
Set last modified	true/false	SetLastModifiedDate	When true, the modified date on any transferred files will be set to match their source files.
Batch size	integer	BatchSize	The number of files to transfer in each batch.
Verbose	true/false	Verbose

General

Change Package Version - Changes the version number of a universal package and adds a repackaging entry to its metadata.

Change Package Version

Changes the version number of a universal package and adds a repackaging entry to its metadata.

Script usage:

ProGet::Repack-Package(
	FileName: <text>,
	[NewVersion: <text>],
	[Reason: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Package file name	text	FileName	This argument is required.
New version	text	NewVersion
Reason	text	Reason

Download File from URL - Downloads a file from a specified URL using an HTTP GET.

Download File from URL

Downloads a file from a specified URL using an HTTP GET.

Script usage:

Download-Http(
	FileName: <text>,
	Url: <text>,
	[LogResponseBody: <true/false>],
	[ErrorStatusCodes: <text>],
	[ResponseBody: <text>],
	[RequestHeaders: <%(key1: value1, ...)>],
	[MaxResponseLength: <integer>],
	[ProxyRequest: <true/false>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <text>]
);

This operation may be prefixed with HTTP::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ File name	text	FileName	The destination path for the downloaded file. This argument is required.
☆ URL (default)	text	Url	This argument is required.
Log response body	true/false	LogResponseBody
Error status codes	text	ErrorStatusCodes	Comma-separated status codes (or ranges in the form of start:end) that should indicate this action has failed. For example, a value of "401,500:599" will fail on all server errors and also when "HTTP Unauthorized" is returned. The default is 400:599.
⇒ Store response as	text	ResponseBody
Request headers	%(key1: value1, ...)	RequestHeaders
Max response length	integer	MaxResponseLength
Use server in context	true/false	ProxyRequest	When selected, this will proxy the HTTP calls through the server is in context instead of using the server Otter or BuildMaster is installed on. If the server in context is SSH-based, then an error will be raised.
Credentials	text	Credentials
User name	text	UserName
Password	text	Password

Example:

# downloads a file from example.org service endpoint
Download-Http http://example.org/upload-service/v3/hdars (
    To: ReleaseNotes.xml
);

Execute Process - Executes a process, logs its output, and waits until it exits.

Execute Process

Executes a process, logs its output, and waits until it exits.

Script usage:

InedoCore::Exec(
	[FileName: <text>],
	[Arguments: <text>],
	[WorkingDirectory: <text>],
	[OutputLogLevel: <integer>],
	[ErrorOutputLogLevel: <integer>],
	[SuccessExitCode: <text>],
	[ImportVariables: <true/false>],
	[WarnRegex: <text>],
	[LogArguments: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
File name	text	FileName
Arguments	text	Arguments
Working directory	text	WorkingDirectory
Output log level	integer	OutputLogLevel
Error log level	integer	ErrorOutputLogLevel
Success exit code	text	SuccessExitCode	Integer exit code which indicates no error. The default is 0. This can also be an integer prefixed with an inequality operator.
Import variables	true/false	ImportVariables	When set to true, all scalar execution variables currently accessible will be exported as environment variables to the process.
Warning regex	text	WarnRegex	When set to a valid regular expression string, output messages which are matched will be logged as warnings. To log only part of the message, use a group with name "m".
Log arguments	true/false	LogArguments

Example:

# execute 7zip and only succeed if the executable returns a non-negative exit code
Exec c:\tools\7za.exe (
    Arguments: i *.*,
    SuccessExitCode: >= 0
);

Execute Shell Script - Executes a specified shell script.

Execute Shell Script

Executes a specified shell script.

Script usage:

SHExec(
	Text: <text>,
	[Verbose: <true/false>],
	[OutputLogLevel: <integer>],
	[ErrorOutputLogLevel: <integer>]
);

This operation may be prefixed with Linux::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Text (default)	text	Text	The shell script text. This argument is required.
Verbose	true/false	Verbose	When true, additional information about staging the script is written to the debug log.
Output log level	integer	OutputLogLevel
Error log level	integer	ErrorOutputLogLevel

Execute VSTest Tests - Runs VSTest unit tests on a specified test project, recommended for tests in VS 2012 and later.

Execute VSTest Tests

Runs VSTest unit tests on a specified test project, recommended for tests in VS 2012 and later.

Script usage:

WindowsSdk::Execute-VSTest(
	TestContainer: <text>,
	[Group: <text>],
	[Arguments: <text>],
	[ClearExistingTestResults: <true/false>],
	[VsTestPath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Test container	text	TestContainer	This argument is required.
Test group	text	Group
Additional arguments	text	Arguments
Clear existing results	true/false	ClearExistingTestResults	When true, the test results directory will be cleared before the tests are run.
VSTest Path	text	VsTestPath	The path to vstest.console.exe, typically: %VSINSTALLDIR%\Common7\IDE\CommonExtensions\Microsoft\TestWindow\vstest.console.exe Leave this value blank to auto-detect the latest vstest.console.exe using vswhere.exe

Invoke Operation - Invokes a specified operation by its script alias.

Invoke Operation

Invokes a specified operation by its script alias.

Script usage:

Invoke-Operation(
	Name: <text>,
	[Arguments: <%(key1: value1, ...)>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Operation name (default)	text	Name	This argument is required.
Arguments	%(key1: value1, ...)	Arguments

Note: This operation should only be used when the specific operation type is unknown until runtime. If the operation's script alias is already known when writing the plan, that operation should be used directly.

Example:

Invoke-Operation
(
  Name: Send-Email,
  Arguments: %(To: $ToEmail, Subject: Important BuildMaster Email $AdditionalSubject, Text: This email was sent via the Invoke-Operation operation.)
);

SHCall - Calls a shell script that is stored as an asset.

SHCall

Calls a shell script that is stored as an asset.

Script usage:

SHCall(
	Name: <text>,
	[Arguments: <text>],
	[Verbose: <true/false>],
	[ExitCode: <integer>],
	[OutputLogLevel: <integer>],
	[ErrorOutputLogLevel: <integer>]
);

This operation may be prefixed with Linux::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Name (default)	text	Name	The name of the script asset. This argument is required.
Arguments	text	Arguments	Arguments to pass to the script.
Verbose	true/false	Verbose	When true, additional information about staging the script is written to the debug log.
⇒ Exit code	integer	ExitCode
Output log level	integer	OutputLogLevel
Error log level	integer	ErrorOutputLogLevel

SHEnsure - Uses two shell scripts to Collect, and then Ensure a configuration about a server.

SHEnsure

Uses two shell scripts to Collect, and then Ensure a configuration about a server.

Script usage:

SHEnsure(
	Key: <text>,
	Value: <text>,
	[Collect: <text>],
	[Configure: <text>],
	[CollectScript: <text>],
	[ConfigureScript: <text>],
	[UseExitCode: <true/false>],
	[Verbose: <true/false>],
	[CollectScriptArgs: <text>],
	[ConfigureScriptArgs: <text>]
);

This operation may be prefixed with Linux::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Configuration key	text	Key	This argument is required.
☆ Expected value	text	Value	This argument is required.
Collection script	text	Collect	The output of this shell script will be used to collect the current configuration of the server.
Configure script	text	Configure	This shell script is executed if the configuration gathered using the collection script does not match the stored configuration.
Collection script asset	text	CollectScript	The name of a shell script asset to use for collection. The output of this script will be used to collect the current configuration of the server.
Configuration script asset	text	ConfigureScript	The name of a shell script asset to use for configuration. This script is executed if the configuration gathered using the collection script does not match the stored configuration.
Use exit code	true/false	UseExitCode	When set, the exit/return code of the script will be used instead of the output stream for collection.
Verbose	true/false	Verbose	When true, additional information about staging the script is written to the debug log.
Collection script arguments	text	CollectScriptArgs	Arguments to pass to the collect script.
Configure script arguments	text	ConfigureScriptArgs	Arguments to pass to the configure script.

Note: The Key is a unique string per server, and having multiple operations attempt to use the same key will yield in unpredictable behavior.

Sleep - Halts the execution of operations for the specified number of seconds.

Sleep

Halts the execution of operations for the specified number of seconds.

Script usage:

InedoCore::Sleep <integer>;

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Seconds (default)	integer	Seconds	This argument is required.

Upload File to URL - Uploads a file to a specified URL using an HTTP POST or PUT.

Upload File to URL

Uploads a file to a specified URL using an HTTP POST or PUT.

Script usage:

Upload-Http(
	[Method: <integer>],
	FileName: <text>,
	Url: <text>,
	[LogResponseBody: <true/false>],
	[ErrorStatusCodes: <text>],
	[ResponseBody: <text>],
	[RequestHeaders: <%(key1: value1, ...)>],
	[MaxResponseLength: <integer>],
	[ProxyRequest: <true/false>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <text>]
);

This operation may be prefixed with HTTP::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Method	integer	Method
☆ File name (default)	text	FileName	The path of the file to upload. This argument is required.
☆ URL	text	Url	This argument is required.
Log response body	true/false	LogResponseBody
Error status codes	text	ErrorStatusCodes	Comma-separated status codes (or ranges in the form of start:end) that should indicate this action has failed. For example, a value of "401,500:599" will fail on all server errors and also when "HTTP Unauthorized" is returned. The default is 400:599.
⇒ Store response as	text	ResponseBody
Request headers	%(key1: value1, ...)	RequestHeaders
Max response length	integer	MaxResponseLength
Use server in context	true/false	ProxyRequest	When selected, this will proxy the HTTP calls through the server is in context instead of using the server Otter or BuildMaster is installed on. If the server in context is SSH-based, then an error will be raised.
Credentials	text	Credentials
User name	text	UserName
Password	text	Password

Example:

# uploads a file to example.org service endpoint
Upload-Http ReleaseNotes.xml (
    To: http://example.org/upload-service/v3/hdars
);

HTTP

HTTP GET Request - Executes an HTTP GET, DELETE, or HEAD request against a URL, typically used for RESTful operations.

HTTP GET Request

Executes an HTTP GET, DELETE, or HEAD request against a URL, typically used for RESTful operations.

Script usage:

Get-Http(
	[Method: <integer>],
	Url: <text>,
	[LogResponseBody: <true/false>],
	[ErrorStatusCodes: <text>],
	[ResponseBody: <text>],
	[RequestHeaders: <%(key1: value1, ...)>],
	[MaxResponseLength: <integer>],
	[ProxyRequest: <true/false>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <text>]
);

This operation may be prefixed with HTTP::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Method	integer	Method
☆ URL (default)	text	Url	This argument is required.
Log response body	true/false	LogResponseBody
Error status codes	text	ErrorStatusCodes	Comma-separated status codes (or ranges in the form of start:end) that should indicate this action has failed. For example, a value of "401,500:599" will fail on all server errors and also when "HTTP Unauthorized" is returned. The default is 400:599.
⇒ Store response as	text	ResponseBody
Request headers	%(key1: value1, ...)	RequestHeaders
Max response length	integer	MaxResponseLength
Use server in context	true/false	ProxyRequest	When selected, this will proxy the HTTP calls through the server is in context instead of using the server Otter or BuildMaster is installed on. If the server in context is SSH-based, then an error will be raised.
Credentials	text	Credentials
User name	text	UserName
Password	text	Password

Example:

# downloads the http://httpbin.org/get page and stores its contents in the 
# $ResponseBody variable, failing only on 500 errors
Get-Http http://httpbin.org/get
(
    ErrorStatusCodes: 500:599,
    ResponseBody => $ResponseBody
);

HTTP POST to URL - Executes an HTTP POST/PUT/PATCH request to a URL, typically used for RESTful operations.

HTTP POST to URL

Executes an HTTP POST/PUT/PATCH request to a URL, typically used for RESTful operations.

Script usage:

Post-Http(
	[Method: <integer>],
	[ContentType: <text>],
	[TextData: <text>],
	[FormData: <%(key1: value1, ...)>],
	[LogRequestData: <true/false>],
	Url: <text>,
	[LogResponseBody: <true/false>],
	[ErrorStatusCodes: <text>],
	[ResponseBody: <text>],
	[RequestHeaders: <%(key1: value1, ...)>],
	[MaxResponseLength: <integer>],
	[ProxyRequest: <true/false>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <text>]
);

This operation may be prefixed with HTTP::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Method	integer	Method
Content type	text	ContentType
Request text content	text	TextData	Direct text input that will be written to the request content body. This will override any form data if both are supplied.
Form data	%(key1: value1, ...)	FormData	A map of form data key/value pairs to send. If TextData is supplied, this value is ignored.
Log request data	true/false	LogRequestData
☆ URL (default)	text	Url	This argument is required.
Log response body	true/false	LogResponseBody
Error status codes	text	ErrorStatusCodes	Comma-separated status codes (or ranges in the form of start:end) that should indicate this action has failed. For example, a value of "401,500:599" will fail on all server errors and also when "HTTP Unauthorized" is returned. The default is 400:599.
⇒ Store response as	text	ResponseBody
Request headers	%(key1: value1, ...)	RequestHeaders
Max response length	integer	MaxResponseLength
Use server in context	true/false	ProxyRequest	When selected, this will proxy the HTTP calls through the server is in context instead of using the server Otter or BuildMaster is installed on. If the server in context is SSH-based, then an error will be raised.
Credentials	text	Credentials
User name	text	UserName
Password	text	Password

Example:

# posts some key-value pairs to a test service and writes the response body to the BuildMaster execution log
Post-Http http://httpbin.org/post
(
    FormData: %(
        Var1: "value1",
        Var2: "value2"
    ),
    LogResponseBody: true
);

Iis

Ensure App Pool - Ensures the existence of an application pool on a server.

Ensure App Pool

Ensures the existence of an application pool on a server.

Script usage:

IIS::Ensure-AppPool(
	Name: <text>,
	[Runtime: <text>],
	[Enable32BitAppOnWin64: <true/false>],
	[Pipeline: <integer>],
	[AutoStart: <true/false>],
	[QueueLength: <Int64>],
	[State: <integer>],
	[IdentityType: <integer>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <text>],
	[CpuLimit: <Int64>],
	[CpuAction: <integer>],
	[CpuResetInterval: <TimeSpan>],
	[CpuSmpAffinitized: <true/false>],
	[CpuSmpProcessorAffinityMask: <Int64>],
	[CpuSmpProcessorAffinityMask2: <Int64>],
	[IdleTimeout: <TimeSpan>],
	[LoadUserProfile: <true/false>],
	[MaxProcesses: <Int64>],
	[PingingEnabled: <true/false>],
	[PingResponseTime: <TimeSpan>],
	[PingInterval: <TimeSpan>],
	[ShutdownTimeLimit: <TimeSpan>],
	[StartupTimeLimit: <TimeSpan>],
	[OrphanWorkerProcess: <true/false>],
	[OrphanActionExe: <text>],
	[OrphanActionParams: <text>],
	[LoadBalancerCapabilities: <integer>],
	[RapidFailProtection: <true/false>],
	[RapidFailProtectionInterval: <TimeSpan>],
	[RapidFailProtectionMaxCrashes: <Int64>],
	[AutoShutdownExe: <text>],
	[AutoShutdownParams: <text>],
	[DisallowOverlappingRotation: <true/false>],
	[DisallowRotationOnConfigChange: <true/false>],
	[PeriodicRestartPrivateMemory: <Int64>],
	[PeriodicRestartTime: <TimeSpan>],
	[PeriodicRestartRequests: <Int64>],
	[PeriodicRestartSchedule: <@(text)>],
	[PeriodicRestartMemory: <Int64>],
	[Exists: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Name	text	Name	The unique name of the IIS site or application pool. This argument is required.
.NET CLR version	text	Runtime	The .NET runtime version used by this application pool. Current valid values are "v4.0", "v2.0", or "v1.1".
Enable 32-bit applications	true/false	Enable32BitAppOnWin64	If set to True for an application pool on a 64-bit operating system, the worker process(es) serving the application pool run in WOW64 (Windows on Windows64) mode. In WOW64 mode, 32-bit processes load only 32-bit applications.
Managed pipeline mode	integer	Pipeline	Configures ASP.NET to run in classic mode as an ISAPI extension or in integrated mode where managed code is integrated into the request-processing pipeline.
Start automatically	true/false	AutoStart	If True, the application pool starts on creation or when IIS starts. Starting an application pool sets this property to True. Stopping an application sets this property to False.
Queue length	Int64	QueueLength	Maximum number of requests that Http.sys queues for the application pool. When the queue is full, new requests receive a 503 "Service Unavailable" response
State	integer	State	Sets the running state for the application pool.
Identity type	integer	IdentityType	Configures the application pool to run as a built-in account, such as Network Service (recommended), Local Service, or as a specific user identity.
Otter credentials	text	Credentials	The Otter credential name to use for the application pool's identity. If a credential name is specified, the username and password fields will be ignored.
User name	text	UserName	Configures the application pool to run as a built-in account, such as Network Service (recommended), Local Service, or as a specific user identity.
Password	text	Password
Limit (percent)	Int64	CpuLimit	Configures the maximum percentage of CPU time (in 1/1000ths of a percent) that the worker processes in an application pool are allowed to consume over a period of time as indicated by the Limit Interval setting (resetInterval property). If the limit set by Limit (limit property) is exceeded, the event is written to the event log and an optional set of events can be triggered or determined by the Limit Action setting (action property). Setting the value of Limit to 0 disables limiting the worker processes to a percentage of CPU time.
Limit action	integer	CpuAction	If set to NoAction, an event log entry is generated. If set to KillW3WP, the application pool is shut down for the duration of the reset interval and an event log entry is generated.
Limit interval (minutes)	TimeSpan	CpuResetInterval	Specifies the reset period (in minutes) for CPU monitoring and throttling limits on the application pool. When the number of minutes elapsed since the last process accounting reset equals the number specified by this property, IIS resets the CPU timers for both the logging and limit intervals. Setting the value of Limit Interval to 0 disables CPU monitoring.
Processor affinity enabled	true/false	CpuSmpAffinitized	If True, Processor Affinity Enabled forces the worker process(es) serving this application pool to run on specific CPUs. This enables sufficient use of CPU caches on multiprocessor servers.
Processor affinity mask	Int64	CpuSmpProcessorAffinityMask	Hexadecimal mask that forces the worker process(es) for this application pool to run on a specific CPU. If processor affinity is enabled, a value of 0 causes an error condition.
Processor affinity (64-bit)	Int64	CpuSmpProcessorAffinityMask2	Hexadecimal mask that forces the worker process(es) for this application pool to run on a specific CPU. If processor affinity is enabled, a value of 0 causes an error condition.
Idle time-out (minutes)	TimeSpan	IdleTimeout	Amount of time (in minutes) a worker process remains idle before it shuts down. A worker process is idle if it is not processing requests and no new requests are received.
Load user profile	true/false	LoadUserProfile	Specifies whether IIS loads the user profile for an application pool identity. When set to True, IIS loads the user profile for the application pool identity. Set to False when you require IIS 6.0 behavior.
Max worker processes	Int64	MaxProcesses	Maximum number of worker processes permitted to service requests for the application pool. If this number is greater than 1, the application pool is called a Web garden.
Ping enabled	true/false	PingingEnabled	If True, the worker process(es) serving this application pool are pinged periodically to ensure that they are still responsive. This process is called health monitoring.
Ping max response time (seconds)	TimeSpan	PingResponseTime	Maximum time (in seconds) that a worker process is given to respond to a health monitoring ping. If the worker process does not respond, it is terminated.
Ping period (seconds)	TimeSpan	PingInterval	Period of time (in seconds) between health monitoring pings sent to the worker process(es) serving this application pool.
Shutdown time limit (seconds)	TimeSpan	ShutdownTimeLimit	Period of time (in seconds) a worker process is given to finish processing requests and shut down. If the worker process exceeds the shutdown time limit, it is terminated.
Startup time limit (seconds)	TimeSpan	StartupTimeLimit	Period of time (in seconds) a worker process is given to start up and initialize. If the worker process initialization exceeds the startup time limit, it is terminated.
Process orphaning enabled	true/false	OrphanWorkerProcess	If True, an unresponsive worker process is abandoned (orphaned) instead of terminated. This feature can be used to debug a worker process failure.
Process orphaning executable	text	OrphanActionExe	Executable to run when a worker process is abandoned (orphaned). For example, C:\dbgtools tsd.exe would invoke NTSD to debug a worker process failure.
Executable parameters	text	OrphanActionParams	Parameters for the executable that is run when a worker process is abandoned (orphaned). For example, -g –p %1% is appropriate if the NTSD is the executable invoked for debugging worker process failures.
Service unavailable response type	integer	LoadBalancerCapabilities	If set to HttpLevel and the application pool is stopped, Http.sys returns an HTTP 503 error. If set to TcpLevel, Http.sys resets the connection. This is useful if the load balancer recognizes one of the response types and subsequently redirects it.
Rapid fail protection enabled	true/false	RapidFailProtection	If True, the application pool is shut down if there are a specified number of worker process failures (Maximum Failures) within a specified period (Failure Interval). By default, an application pool is shut down if there are five failures in a five minute period.
Failure interval (minutes)	TimeSpan	RapidFailProtectionInterval	The time interval (in minutes) during which the specified number of worker process failures (Maximum Failures) must occur before the application pool is shut down by Rapid Fail Protection.
Maximum failures	Int64	RapidFailProtectionMaxCrashes	Maximum number of worker process failures permitted before the application pool is shut down by Rapid Fail Protection.
Shutdown executable	text	AutoShutdownExe	Executable to run when an application pool is shut down by Rapid Fail Protection.This can be used to configure a load balancer to redirect traffic for this application to another server.
Shutdown executable parameters	text	AutoShutdownParams	Parameters for the executable to run when an application pool is shut down by Rapid Fail Protection.
Disable overlapped recycle	true/false	DisallowOverlappingRotation	If True, when the application pool recycles, the existing worker process exits before another worker process is created. Set to True if the worker process loads an application that does not support multiple instances.
Disable for config changes	true/false	DisallowRotationOnConfigChange	If True, the application pool does not recycle when its configuration is changed.
Private memory limit (KB)	Int64	PeriodicRestartPrivateMemory	Maximum amount of private memory (in KB) a worker process can consume before causing the application pool to recycle. A value of 0 means there is no limit.
Regular time interval (minutes)	TimeSpan	PeriodicRestartTime	Period of time (in minutes) after which an application pool recycles. A value of 0 means the application pool does not recycle at a regular interval.
Request Limit	Int64	PeriodicRestartRequests	Maximum number of requests an application pool can process before it is recycled. A value of 0 means the application pool can process an unlimited number of requests.
Schedule	@(text)	PeriodicRestartSchedule	Specific times of day to recycle the application pool. For example, @(3:30:00, 10:00:00, 23:59:59)
Virtual memory limit (KB)	Int64	PeriodicRestartMemory	Maximum amount of virtual memory (in KB) a worker process can consume before causing the application pool to recycle. A value of 0 means there is no limit.
Exists	true/false	Exists

Example:

# ensures that the Otter application pool is present on the web server
IIS::Ensure-AppPool(
    Name: OtterAppPool,
    Pipeline: 1, # classic mode
    Runtime: v4.0
);

# ensures that the DefaultAppPool is removed from the web server
IIS::Ensure-AppPool(
    Name: DefaultAppPool,
    Exists: false
);

Ensure Application - Ensures the existence of an application within an IIS site.

Ensure Application

Ensures the existence of an application within an IIS site.

Script usage:

IIS::Ensure-Application(
	Site: <text>,
	Path: <text>,
	[AppPool: <text>],
	[PhysicalPath: <text>],
	[LogonMethod: <integer>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Exists: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Site name	text	Site	The name of this site where the application would exist This argument is required.
☆ Application path	text	Path	The relative URL of the path, such as /hdars This argument is required.
Application pool	text	AppPool	The name of the application pool assigned to the application.
Physical path	text	PhysicalPath	Physical path to the content for the application, such as c:\hdars.
Logon method	integer	LogonMethod	Specifies the type of the logon operation to perform when calling LogonUser to acquire the user token impersonated to access the physical path for the application.
Otter credentials	text	Credentials	The Otter credential name to be impersonated when accessing the physical path for the application. If a credential name is specified, the username and password fields will be ignored.
User name	text	UserName
Password	text	Password
Exists	true/false	Exists

Example:

# ensures that the hdars application is present on the web server
IIS::Ensure-Application(
    Site: Hdars,
    Path: /hdars,
    PhysicalPath: C:\hdars
);

Ensure Site - Ensures the existence of a site on a server.

Ensure Site

Ensures the existence of a site on a server.

Script usage:

IIS::Ensure-Site(
	Name: <text>,
	[AppPool: <text>],
	[Path: <text>],
	[Binding: <text>],
	[Bindings: <@(%(key1: value1, ...))>],
	[BindingProtocol: <text>],
	[BindingAddress: <text>],
	[BindingHostName: <text>],
	[BindingPort: <integer>],
	[BindingCertficiate: <text>],
	[BindingCertificateStoreLocation: <integer>],
	[BindingCertificateHash: <text>],
	[BindingRequireSNI: <true/false>],
	[BindingCertificateStore: <text>],
	[Exists: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Name	text	Name	The unique name of the IIS site or application pool. This argument is required.
Application pool	text	AppPool	The name of the application pool assigned to the site.
Virtual directory physical path	text	Path	The path to the web site files on disk.
Binding	text	Binding
Bindings	@(%(key1: value1, ...))	Bindings	Bindings are entered as a list of maps, e.g.: @(%(IPAddress: 192.0.2.100, Port: 80, HostName: example.com, Protocol: http), %(IPAddress: 192.0.2.101, Port: 443, HostName: secure.example.com, Protocol: https, CertificateStoreName: WebHosting, CertificateHash: 51599BF2909EA984793481F0DF946C57E4FD5DEA, ServerNameIndication: true, UseCentralizedStore: false))
BindingProtocol	text	BindingProtocol
IP address	text	BindingAddress
Host name	text	BindingHostName
BindingPort	integer	BindingPort
SSL certificate	text	BindingCertficiate
Certificate store location	integer	BindingCertificateStoreLocation
SSL certificate hash	text	BindingCertificateHash	When specified, this value will be used to identify the SSL certificate by its thumbprint, and the "Certificate" and "CertificateStoreLocation" values will be ignored.
Require SNI	true/false	BindingRequireSNI
SSL certificate store	text	BindingCertificateStore
Exists	true/false	Exists

Example:

# ensures that the Otter web site is present on the web server, and binds the site to the single IP address 192.0.2.100 on port 80 and hostname "example.com"
IIS::Ensure-Site(
    Name: Otter,
    AppPool: OtterAppPool,
    Path: E:\Websites\Otter,
    Bindings: @(%(IPAddress: 192.0.2.100, Port: 80, HostName: example.com, Protocol: http))
);

# ensures that the Default Web Site is removed from the web server
IIS::Ensure-Site(
    Name: Default Web Site,
    Exists: false
);

Ensure Site Binding - Ensures the existence of a binding on a site.

Ensure Site Binding

Ensures the existence of a binding on a site.

Script usage:

IIS::Ensure-SiteBinding(
	Site: <text>,
	[Protocol: <text>],
	[Address: <text>],
	[HostName: <text>],
	[Port: <integer>],
	[Certficiate: <text>],
	[CertificateStoreLocation: <integer>],
	[CertificateHash: <text>],
	[RequireSNI: <true/false>],
	[CertificateStore: <text>],
	[Exists: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ IIS site	text	Site	This argument is required.
Protocol	text	Protocol
IP address	text	Address
Host name	text	HostName
Port	integer	Port
SSL certificate	text	Certficiate
Certificate store location	integer	CertificateStoreLocation
SSL certificate hash	text	CertificateHash	When specified, this value will be used to identify the SSL certificate by its thumbprint, and the "Certificate" and "CertificateStoreLocation" values will be ignored.
Require SNI	true/false	RequireSNI
SSL certificate store	text	CertificateStore
Exists	true/false	Exists

Example:

# ensures that the Otter web site is present on the web server, and binds the site to the single IP address 192.0.2.100 on port 80 and hostname "example.com"
IIS::Ensure-Site(
    Name: Otter,
    AppPool: OtterAppPool,
    Path: E:\Websites\Otter
);

IIS::Ensure-SiteBinding(
    Site: Otter,
    Protocol: http,
    Address: 192.0.2.100,
    Port: 80,
    HostName: example.com
);

Ensure Virtual Directory - Ensures the existence of a virtual directory within an IIS site.

Ensure Virtual Directory

Ensures the existence of a virtual directory within an IIS site.

Script usage:

IIS::Ensure-VirtualDirectory(
	Site: <text>,
	[ApplicationPath: <text>],
	Path: <text>,
	[PhysicalPath: <text>],
	[LogonMethod: <integer>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Exists: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Site name	text	Site	The name of this site where the virtual directory would exist This argument is required.
Application path	text	ApplicationPath	The relative URL of the application containing the virtual directory, such as /
☆ Virtual path	text	Path	The relative URL of the path, such as /hdars This argument is required.
Physical path	text	PhysicalPath	Physical path to the content for the virtual directory, such as c:\hdars.
Logon method	integer	LogonMethod	Specifies the type of the logon operation to perform when calling LogonUser to acquire the user token impersonated to access the physical path for the virtual directory.
Otter credentials	text	Credentials	The Otter credential name to be impersonated when accessing the physical path for the virtual directory. If a credential name is specified, the username and password fields will be ignored.
User name	text	UserName
Password	text	Password
Exists	true/false	Exists

Example:

# ensures that the hdars virtual directory pool is present on the web server
IIS::Ensure-VirtualDirectory(
    Site: Hdars,
    Path: /hdars,
    PhysicalPath: C:\hdars
);

Recycle App Pool - Recycles an application pool.

Recycle App Pool

Recycles an application pool.

Script usage:

IIS::Recycle-AppPool(
	[WaitForStartedStatus: <true/false>],
	Name: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
Wait for started status	true/false	WaitForStartedStatus
☆ App pool (default)	text	Name	The name of the application pool to operate on. This argument is required.

Example:

# stops the BuildMaster application pool 
IIS::Stop-AppPool BuildMasterAppPool;

# starts the BuildMaster application pool 
IIS::Start-AppPool BuildMasterAppPool;

# recycles the BuildMaster application pool 
IIS::Recycle-AppPool BuildMasterAppPool;

Start App Pool - Starts an IIS app pool.

Start App Pool

Starts an IIS app pool.

Script usage:

IIS::Start-AppPool(
	[WaitForStartedStatus: <true/false>],
	Name: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
Wait for started status	true/false	WaitForStartedStatus
☆ App pool (default)	text	Name	The name of the application pool to operate on. This argument is required.

Example:

# stops the BuildMaster application pool 
IIS::Stop-AppPool BuildMasterAppPool;

# starts the BuildMaster application pool 
IIS::Start-AppPool BuildMasterAppPool;

# recycles the BuildMaster application pool 
IIS::Recycle-AppPool BuildMasterAppPool;

Start Site - Starts an IIS Site.

Start Site

Starts an IIS Site.

Script usage:

IIS::Start-Site(
	[WaitForStartedStatus: <true/false>],
	Name: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
Wait for started status	true/false	WaitForStartedStatus
☆ Site (default)	text	Name	The name of the IIS site to operate on. This argument is required.

Example:

# stops the BuildMaster web site 
IIS::Stop-Site BuildMaster;

# starts the BuildMaster web site
IIS::Start-Site BuildMaster;

Stop App Pool - Stops an IIS app pool.

Stop App Pool

Stops an IIS app pool.

Script usage:

IIS::Stop-AppPool(
	[WaitForStoppedStatus: <true/false>],
	Name: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
Wait for stopped status	true/false	WaitForStoppedStatus
☆ App pool (default)	text	Name	The name of the application pool to operate on. This argument is required.

Example:

# stops the BuildMaster application pool 
IIS::Stop-AppPool BuildMasterAppPool;

# starts the BuildMaster application pool 
IIS::Start-AppPool BuildMasterAppPool;

# recycles the BuildMaster application pool 
IIS::Recycle-AppPool BuildMasterAppPool;

Stop Site - Stops an IIS Site.

Stop Site

Stops an IIS Site.

Script usage:

IIS::Stop-Site(
	[WaitForStoppedStatus: <true/false>],
	Name: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
Wait for stopped status	true/false	WaitForStoppedStatus
☆ Site (default)	text	Name	The name of the IIS site to operate on. This argument is required.

Example:

# stops the BuildMaster web site 
IIS::Stop-Site BuildMaster;

# starts the BuildMaster web site
IIS::Start-Site BuildMaster;

Issue Tracking

Add Comment to GitHub Issue - Adds a comment to an issue on GitHub.

Add Comment to GitHub Issue

Adds a comment to an issue on GitHub.

Script usage:

GitHub::Create-IssueComment(
	Number: <integer>,
	Body: <text>,
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Issue number	integer	Number	This argument is required.
☆ Body	text	Body	This argument is required.
Credentials	text	Credentials
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.

Add Comment to Issues - Writes a comment to all issues of the current release, optionally filtering by issue status.

Add Comment to Issues

Writes a comment to all issues of the current release, optionally filtering by issue status.

Script usage:

Add-Issue-Comment(
	Text: <text>,
	[InStatus: <text>]
);

This operation may be prefixed with Issues::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Comment text	text	Text	This argument is required.
Status filter	text	InStatus

Example:

# adds a comment containing the deployed version number to closed issues
Add-Issue-Comment(
    Text: Deployed with BuildMaster, version: $ReleaseNumber.$BuildNumber,
    Status: Closed
);

Close GitHub Issue - Closes an issue on GitHub.

Close GitHub Issue

Closes an issue on GitHub.

Script usage:

GitHub::Close-Issue(
	Number: <integer>,
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Issue number	integer	Number	This argument is required.
Credentials	text	Credentials
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.

Close Issues - Closes all open issues associated with the current release.
Close Issues

Closes all open issues associated with the current release.

Script usage:
```
Close-Issues [DefaultArgument] ();
```
This operation may be prefixed with Issues::, although this is a built-in namespace and isn't really necessary.

Example:
```
# close all open issues in the current release
Close-Issues();
```

Create GitHub Issue - Creates an issue on a GitHub repository.

Create GitHub Issue

Creates an issue on a GitHub repository.

Script usage:

GitHub::Create-Issue(
	Title: <text>,
	[Body: <text>],
	[Labels: <@(text)>],
	[Assignees: <@(text)>],
	[Milestone: <text>],
	[Number: <integer>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Title	text	Title	This argument is required.
Body	text	Body
Labels	@(text)	Labels
Assignees	@(text)	Assignees
Milestone	text	Milestone
⇒ Issue number	integer	Number
Credentials	text	Credentials
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.

Create Jira Issue - Creates an issue in Jira.

Create Jira Issue

Creates an issue in Jira.

Script usage:

Jira::Create-Issue(
	[Credentials: <text>],
	Project: <text>,
	Title: <text>,
	Type: <text>,
	[Description: <text>],
	[FixFor: <text>],
	[JiraIssueId: <text>],
	[Server: <text>],
	[UserName: <text>],
	[Password: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
☆ Project name	text	Project	This argument is required.
☆ Title	text	Title	This argument is required.
☆ Type	text	Type	This argument is required.
Description	text	Description
Fix for version	text	FixFor
⇒ Set issue ID to a variable	text	JiraIssueId	The JIRA issue ID can be output into a runtime variable.
Server	text	Server
UserName	text	UserName
Password	SecureString	Password

Example:

# create issue for the HDARS project notifying QA that testing is required
Create-Issue(
    Credentials: Jira7Local,
    Project: HDARS,
    Title: QA Testing Required for $ApplicationName,
    Description: This issue was created by BuildMaster on $Date,
    Type: ReadyForQA,
    JiraIssueId => $JiraIssueId
);

Log-Information "Issue '$JiraIssueId' was created in JIRA.";

Create TFS Work Item - Creates a work item in TFS.

Create TFS Work Item

Creates a work item in TFS.

Script usage:

TFS::Create-WorkItem(
	[Credentials: <text>],
	TeamProject: <text>,
	Type: <text>,
	Title: <text>,
	[Description: <text>],
	[IterationPath: <text>],
	[TfsIssueId: <text>],
	[Url: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Domain: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
☆ Team project	text	TeamProject	This argument is required.
☆ Work item type	text	Type	This argument is required.
☆ Title	text	Title	This argument is required.
Description	text	Description
Iteration path	text	IterationPath
⇒ Set issue ID to a variable	text	TfsIssueId	The TFS issue ID can be output into a runtime variable.
Project collection URL	text	Url
User name	text	UserName
Password / token	text	Password
Domain name	text	Domain

Example:

# create issue for the HDARS project
Create-WorkItem(
    Credentials: KarlVSO,
    TeamProject: HDARS,
    Type: Task,
    Title: QA Testing Required for $ApplicationName,
    Description: This issue was created by BuildMaster on $Date
);

Ensure GitHub Milestone - Ensures a GitHub milestone exists with the specified properties.

Ensure GitHub Milestone

Ensures a GitHub milestone exists with the specified properties.

Script usage:

GitHub::Ensure-Milestone(
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>],
	Title: <text>,
	[DueDate: <text>],
	[Description: <text>],
	[State: <integer>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.
☆ Title	text	Title	This argument is required.
Due date	text	DueDate
Description	text	Description
State	integer	State

Transition Jira Issues - Transitions issues in JIRA.

Transition Jira Issues

Transitions issues in JIRA.

Script usage:

Jira::Transition-Issues(
	[Credentials: <text>],
	Project: <text>,
	[From: <text>],
	To: <text>,
	[FixFor: <text>],
	[Id: <text>],
	[Server: <text>],
	[UserName: <text>],
	[Password: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
☆ Project name	text	Project	This argument is required.
From	text	From
☆ To	text	To	This argument is required.
With fix for version	text	FixFor
Specific issue ID	text	Id	If an issue ID is supplied, other filters will be ignored.
Server	text	Server
UserName	text	UserName
Password	SecureString	Password

Example:

# closes issues for the HDARS project for the current release
Transition-Issues(
    Credentials: Jira7Local,
    Project: HDARS,
    From: QA-InProgress,
    To: Closed
);

Update TFS Work Item - Updates an existing work item in TFS.

Update TFS Work Item

Updates an existing work item in TFS.

Script usage:

TFS::Update-WorkItem(
	[Credentials: <text>],
	Id: <text>,
	[Title: <text>],
	[Description: <text>],
	[IterationPath: <text>],
	[State: <text>],
	[Url: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Domain: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
☆ Id	text	Id	The ID for issues may be stored as output variables of the Create-WorkItem operation. This argument is required.
Title	text	Title
Description	text	Description
Iteration path	text	IterationPath
State	text	State
Project collection URL	text	Url
User name	text	UserName
Password / token	text	Password
Domain name	text	Domain

Example:

# Update issue stored in package variable to 'In Progress'
Create-WorkItem(
    Credentials: KarlVSO,
    TeamProject: HDARS,
    Id: $TfsIssueId,
    State: In Progress
);

Network

Ensure Hosts Entry - Ensures an entry in the hosts file on a server.

Ensure Hosts Entry

Ensures an entry in the hosts file on a server.

Script usage:

Ensure-HostsEntry(
	Host: <text>,
	IP: <text>,
	[Exists: <true/false>]
);

This operation may be prefixed with Network::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Host name	text	Host	This argument is required.
☆ IP address	text	IP	This argument is required.
Exists	true/false	Exists

Example:

# bind otter.localhost to local ip
Ensure-HostsEntry otter.localhost (IP: 127.0.0.1);

# override hdars.com to a local address
Ensure-HostsEntry (
  Host: hdars.com
  IP: 192.168.10.0);

Nuget

Create NuGet Package - Creates a package using NuGet.

Create NuGet Package

Creates a package using NuGet.

Script usage:

NuGet::Create-Package(
	SourceFile: <text>,
	[Verbose: <true/false>],
	[Version: <text>],
	[Symbols: <true/false>],
	[Build: <true/false>],
	[Properties: <@(text)>],
	[IncludeReferencedProjects: <true/false>],
	[OutputDirectory: <text>],
	[SourceDirectory: <text>],
	[NuGetExePath: <text>],
	[Arguments: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Source file (default)	text	SourceFile	The .nuspec or MSBuild project that will be passed to NuGet.exe. This argument is required.
Verbose logging	true/false	Verbose
Version	text	Version	The package version that will be passed to NuGet.exe.
Symbols	true/false	Symbols	When true, the -Symbols argument will be passed to NuGet.exe.
Build	true/false	Build	When true, the -Build argument will be passed to NuGet.exe.
Properties	@(text)	Properties	When Build is true, these values will be passed to NuGet.exe as MSBuild properties in the format PROP=VALUE.
Include ref. projects	true/false	IncludeReferencedProjects	When true, the -IncludeReferencedProjects argument will be passed to NuGet.exe.
Output directory	text	OutputDirectory	The output directory that will be passed to NuGet.exe.
Source directory	text	SourceDirectory	The working directory to use when executing NuGet.
NuGet.exe path	text	NuGetExePath	Full path to NuGet.exe on the target server. When not set, the bundled NuGet.exe will be used.
Additional arguments	text	Arguments	When specified, these arguments will be passed to NuGet.exe verbatim.

Install NuGet Packages - Installs all packages required for projects in a solution to build.

Install NuGet Packages

Installs all packages required for projects in a solution to build.

Script usage:

NuGet::Install-Packages(
	[OutputDirectory: <text>],
	[SourceDirectory: <text>],
	[Source: <text>],
	[NuGetExePath: <text>],
	[Arguments: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Output directory	text	OutputDirectory	The directory into which packages will be installed.
Source directory	text	SourceDirectory	The working directory to use when installing packages.
Source URL	text	Source
NuGet.exe path	text	NuGetExePath	Full path to NuGet.exe on the target server. When not set, the bundled NuGet.exe will be used.
Additional arguments	text	Arguments	When specified, these arguments will be passed to NuGet.exe verbatim.

Publish NuGet Package - Publishes a package to a NuGet feed.

Publish NuGet Package

Publishes a package to a NuGet feed.

Script usage:

NuGet::Publish-Package(
	Package: <text>,
	Url: <text>,
	[Credentials: <text>],
	[ApiKey: <text>],
	[UserName: <text>],
	[Password: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Package file name (default)	text	Package	The path of the .nupkg file to push to the NuGet feed. This argument is required.
☆ Source	text	Url	The NuGet feed source URL to push the package to. This argument is required.
Credentials	text	Credentials
API key	text	ApiKey	The NuGet API key required to push packages to the feed.
User name	text	UserName
Password	text	Password

Restore NuGet Packages - Restores all packages in a specified solution, project, or packages.config file.

Restore NuGet Packages

Restores all packages in a specified solution, project, or packages.config file.

Script usage:

NuGet::Restore-Packages(
	[Target: <text>],
	[PackagesDirectory: <text>],
	[Source: <text>],
	[NuGetExePath: <text>],
	[Arguments: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Target	text	Target	The target solution, project, or packages.config file used to restore packages, or directory containing a solution.
Packages directory	text	PackagesDirectory	The directory into which packages will be restored.
Source URL	text	Source
NuGet.exe path	text	NuGetExePath	Full path to NuGet.exe on the target server. When not set, the bundled NuGet.exe will be used.
Additional arguments	text	Arguments	When specified, these arguments will be passed to NuGet.exe verbatim.

Otter

Remediate Drift - Checks configuration status and if drifted, triggers a remediation job in Otter.

Remediate Drift

Checks configuration status and if drifted, triggers a remediation job in Otter.

Script usage:

Otter::Remediate-Drift(
	[Credentials: <text>],
	[Server: <text>],
	[Role: <text>],
	[WaitForCompletion: <true/false>],
	[Host: <text>],
	[ApiKey: <SecureString>]
);

Arguments:

Name	Format	Script Usage
Credentials	text	Credentials
Server name	text	Server
Role name	text	Role
Wait until remediated	true/false	WaitForCompletion
Otter server URL	text	Host
API key	SecureString	ApiKey

Note: Either a server name or role name is required, but not both. If both values are entered, role name will be ignored.

Example:

# triggers Otter to remediate drift for hdars web server roles
Otter::Remediate-Drift
(
    Credentials: ProductionOtter,
    Role: hdars-web-1k
);

Set Variable Value in Otter - Creates or assigns a configuration variable in Otter.

Set Variable Value in Otter

Creates or assigns a configuration variable in Otter.

Script usage:

Otter::Set-Variable(
	[Credentials: <text>],
	Name: <text>,
	Value: <text>,
	[Server: <text>],
	[Role: <text>],
	[Environment: <text>],
	[Sensitive: <true/false>],
	[Host: <text>],
	[ApiKey: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
☆ Variable name	text	Name	This argument is required.
☆ Value	text	Value	This argument is required.
Server name	text	Server
Role name	text	Role
Environment name	text	Environment
Sensitive	true/false	Sensitive
Otter server URL	text	Host
API key	SecureString	ApiKey

Note: If multiple entity scopes are provided, the variable will be multi-scoped. If no entity scope is provided, a global variable will be set.

Example:

# sets the variable for the hdars-web-1k-tokyo server to the name of the current application
Otter::Set-Variable
(
    Credentials: ProductionOtter,
    Server: hdars-web-1k-tokyo,
    Name: LatestDeployedApplication,
    Value: $ApplicationName,
    Sensitive: false
);

Powershell

Ensure DSC Resource - Ensures the configuration of a specified PowerShell DSC Resource.

Ensure DSC Resource

Ensures the configuration of a specified PowerShell DSC Resource.

Script usage:

Ensure-DscResource(
	[ConfigurationKey: <text>],
	Name: <text>,
	[Module: <text>],
	[Properties: <%(key1: value1, ...)>]
);

This operation may be prefixed with PowerShell::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Otter configuration key	text	ConfigurationKey	The name of the DSC property which will be used as the Otter configuration key for the server. If this is not specified, the "Name" property is used.
☆ Resource	text	Name	This argument is required.
Module	text	Module
Properties	%(key1: value1, ...)	Properties	DSC property hashtable as an OtterScript map. Example: %(DestinationPath: C:\hdars\1000.txt, Contents: test file ensured)

Note: An argument may be explicitly converted to an integral type by prefixing the value with [type::<typeName>], where <typeName> is one of: int, uint, long, ulong, double, decimal. Normally this conversion is performed automatically and this is not necessary.

Example:

# ensures the existence of a file on the server
Ensure-DscResource(
  Name: File,
  ConfigurationKey: DestinationPath,
  Properties: %(
    DestinationPath: C:\hdars\1000.txt,
    Contents: test file ensured)
);

# runs a custom resource
Ensure-DscResource(
  Name: cHdars,
  Module: cHdarsResource,
  ConfigurationKey: LocalServer,
  Properties: %(
    MaximumSessionLength: 1000,
    PortsToListen: @(3322,4431,1123),
    Enabled: true)
);

PSCall - Calls a PowerShell Script that is stored as an asset.
PSCall

Calls a PowerShell Script that is stored as an asset.

Script usage:
```
PSCall [DefaultArgument] (
	[Arg1: Arg1Value],
	[Arg2: Arg2Value],
	[OutputArgument => $CustomVariable]
);
```
This operation may be prefixed with PowerShell::, although this is a built-in namespace and isn't really necessary.

Note: An argument may be explicitly converted to an integral type by prefixing the value with [type::<typeName>], where <typeName> is one of: int, uint, long, ulong, double, decimal. Normally this conversion is performed automatically and this is not necessary.

Example:
```
# execute the hdars.ps1 script, passing Argument1 and Aaaaaarg2 as variables, and capturing the value of OutputArg as $MyVariable
pscall hdars (
  Argument1: hello,
  Aaaaaarg2: World,
  OutputArg => $MyVariable
);
```

PSDsc - Ensures the configuration of a specified PowerShell DSC Resource.

PSDsc

Ensures the configuration of a specified PowerShell DSC Resource.

Script usage:

PSDsc(
	[ConfigurationKey: <text>],
	Name: <text>,
	[Module: <text>],
	[Properties: <%(key1: value1, ...)>]
);

This operation may be prefixed with PowerShell::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Otter configuration key	text	ConfigurationKey	The name of the DSC property which will be used as the Otter configuration key for the server. If this is not specified, the "Name" property is used.
☆ Resource	text	Name	This argument is required.
Module	text	Module
Properties	%(key1: value1, ...)	Properties	DSC property hashtable as an OtterScript map. Example: %(DestinationPath: C:\hdars\1000.txt, Contents: test file ensured)

Note: This is a shorthand version of the Ensure-DscResource operation.

Default Argument: ResourceName: The default argument for this operation is the DSC Resource Name and should follow the format: "ModuleName::ResourceName". If "ModuleName::" is omitted, the PSDesiredStateConfiguration module will be used.

Configuration Key: Otter Specific: By default, Otter will use the Name property of the DSC Resource as the configuration key. If there is no Name property or you would like to override the default configuration key name, specify a property named "Otter_ConfigurationKey" with the value containing a string (or list of strings) indicating the name of the property (or properties) to be used as the unique configuration key.

Example:

# ensures the existence of a file on the server
PSDsc File (
  Otter_ConfigurationKey: DestinationPath,
  DestinationPath: C:\hdars\1000.txt,
  Contents: test file ensured
);

# runs a custom resource
PSDsc cHdarsResource::cHdars (
  Otter_ConfigurationKey: LocalServer,
  MaximumSessionLength: 1000,
  PortsToListen: @(3322,4431,1123),
  Enabled: true
);

PSEnsure - Uses two PowerShell scripts to Collect, and then Ensure a configuration about a server.

PSEnsure

Uses two PowerShell scripts to Collect, and then Ensure a configuration about a server.

Script usage:

PSEnsure(
	Key: <text>,
	Value: <text>,
	[Collect: <text>],
	[Configure: <text>],
	[CollectScript: <text>],
	[ConfigureScript: <text>],
	[UseExitCode: <true/false>],
	[Debug: <true/false>],
	[Verbose: <true/false>],
	[CollectScriptParams: <%(key1: value1, ...)>],
	[ConfigureScriptParams: <%(key1: value1, ...)>]
);

This operation may be prefixed with PowerShell::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Configuration key	text	Key	This argument is required.
☆ Expected value	text	Value	This argument is required.
Collection script	text	Collect	The output of this PowerShell script will be used to collect the current configuration of the server. Variables are not expanded within the contents of this property.
Configure script	text	Configure	This PowerShell script is executed if the configuration gathered using the collection script does not match the stored configuration. Variables are not expanded within the contents of this property.
Collection script asset	text	CollectScript	The name of a PowerShell script asset to use for collection. The output of this PowerShell script will be used to collect the current configuration of the server.
Configuration script asset	text	ConfigureScript	The name of a PowerShell script asset to use for configuration. This script is executed if the configuration gathered using the collection script does not match the stored configuration.
Use exit code	true/false	UseExitCode	When set, the exit/return code of the script will be used instead of the output stream for collection.
Debug	true/false	Debug	Captures the PowerShell Write-Debug stream into Otter's execution debug log.
Verbose	true/false	Verbose	Captures the PowerShell Write-Verbose stream into Otter's execution debug log.
Collection script parameters	%(key1: value1, ...)	CollectScriptParams	Map containing named arguments to pass to the PowerShell collect script.
Configure script parameters	%(key1: value1, ...)	ConfigureScriptParams	Map containing named arguments to pass to the PowerShell configure script.

Note: The Key is a unique string per server, and having multiple operations attempt to use the same key will yield in unpredictable behavior.

Example:

# ensures the BuildMaster Agent service exists on the remote server
PSEnsure(
    Key: BuildMasterAgentInstalled,
    # returns the count of INEDOBMAGT services installed
    Collect: @(Get-Service | Where-Object {$_.Name -eq "INEDOBMAGT"}).Count,
    # expected value is 1
    Value: 1,
    # if the returned value is 0 instead of 1, the installer will run
    Configure: & '\\filesrv1000\$e\Resources\BuildMasterAgentSetup.exe' /S /AgentType=TCP /Port=8080,
    Debug: true,
    Verbose: true
);

# ensures the BuildMaster Agent service exists on the remote server, using a
# PowerShell script asset to perform the configuration
PSEnsure(
    Key: BuildMasterAgentInstalled,
    # returns the count of INEDOBMAGT services installed
    Collect: @(Get-Service | Where-Object {$_.Name -eq "INEDOBMAGT"}).Count,
    # expected value is 1
    Value: 1,
    # use script stored in InstallBmAgent asset
    ConfigureScript: InstallBmAgent,
    ConfigureScriptParams: %(
        AgentType: TCP,
        Port: 1000),
    Debug: true,
    Verbose: true
);

PSExec - Executes a specified PowerShell script.

PSExec

Executes a specified PowerShell script.

Script usage:

Execute-PowerShell(
	Text: <text>,
	[Debug: <true/false>],
	[Verbose: <true/false>],
	[RunOnSimulation: <true/false>],
	[Isolated: <true/false>]
);

This operation may be prefixed with PowerShell::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Script contents (default)	text	Text	The PowerShell script text. Variables are not expanded within the contents of this property. This argument is required.
Capture debug	true/false	Debug	Captures the PowerShell Write-Debug stream into the Otter debug log. The default is false.
Capture verbose	true/false	Verbose	Captures the PowerShell Write-Verbose stream into the Otter debug log. The default is false.
Run on simulation	true/false	RunOnSimulation	Indicates whether the script will execute in simulation mode. The default is false.
Isolated	true/false	Isolated	When true, the script is run in a temporary AppDomain that is unloaded when the script completes. This is an experimental feature and may decrease performance, but may be useful if a script loads assemblies or other resources that would otherwise be leaked.

Note: This operation will inject PowerShell variables from the execution engine runtime that match PowerShell variable expressions. This means you won't get an error if you use an undeclared variable in your script, but some expressions that PowerShell interoplates at runtime (such as a variable inside of a string), cannot be replaced by the operation.

Note: If you are attempting to write the results of a Format-* call to the log, you may see messages similar to "Microsoft.PowerShell.Commands.Internal.Format.FormatEntryData". To convert this to text, use the Out-String commandlet at the end of your command chain.

Note: This script will execute in simulation mode; you set the RunOnSimulation parameter to false to prevent this behavior, or you can use the $IsSimulation variable function within the script.

Example:

# writes the list of services running on the computer to the Otter log
psexec >>
    Get-Service | Where-Object {$_.Status -eq "Running"} | Format-Table Name, DisplayName | Out-String
>>;

# delete all but the latest 3 logs in the log directory, and log any debug/verbose messages to the Otter log
psexec >>
    Get-ChildItem "E:\Site\Logs" | Sort-Object $.CreatedDate -descending | Select-Object -skip 3 | Remove-Item
>> (Verbose: true, Debug: true, RunOnSimulation: false);

Proget

Create Package - Creates a universal package from the specified directory.

Create Package

Creates a universal package from the specified directory.

Script usage:

ProGet::Create-Package(
	[From: <text>],
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[To: <text>],
	[Overwrite: <true/false>],
	[Group: <text>],
	Name: <text>,
	Version: <text>,
	[Metadata: <%(key1: value1, ...)>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Source directory	text	From
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
To	text	To	This may either be a file name or a directory. If the value ends with .upack, then this is treated as a file name. Otherwise, it is treated as an output directory into which the package file will be written.
Overwrite	true/false	Overwrite
Package group	text	Group
☆ Package name	text	Name	This argument is required.
☆ Package version	text	Version	This argument is required.
Additional metadata	%(key1: value1, ...)	Metadata	Additional properties may be specified using map syntax. For example: %(description: my package description)

Ensure Package - Ensures that the contents of a ProGet package are in the specified directory.

Ensure Package

Ensures that the contents of a ProGet package are in the specified directory.

Script usage:

ProGet::Ensure-Package(
	[Credentials: <text>],
	Feed: <text>,
	Name: <text>,
	[Version: <text>],
	[DeleteExtra: <true/false>],
	Directory: <text>,
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[FeedUrl: <text>],
	[UserName: <text>],
	[Password: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
☆ Feed name	text	Feed	This argument is required.
☆ Package name	text	Name	This argument is required.
Package version	text	Version
Delete files not in Package	true/false	DeleteExtra
☆ Target directory	text	Directory	The directory path on disk of the package contents. This argument is required.
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
ProGet server URL	text	FeedUrl
ProGet user name	text	UserName	The name of a user in ProGet that can access this feed.
ProGet password	text	Password	The password of a user in ProGet that can access this feed.

Get Package - Downloads the contents of a ProGet package to a specified directory.

Get Package

Downloads the contents of a ProGet package to a specified directory.

Script usage:

ProGet::Get-Package(
	[Credentials: <text>],
	Feed: <text>,
	Name: <text>,
	[Version: <text>],
	Directory: <text>,
	[DeleteExtra: <true/false>],
	[Server: <text>],
	[UserName: <text>],
	[Password: <text>],
	[RecordDeployment: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
☆ Feed name	text	Feed	This argument is required.
☆ Package name	text	Name	This argument is required.
Package version	text	Version
☆ Target directory	text	Directory	The directory path on disk of the package contents. This argument is required.
Delete files not in Package	true/false	DeleteExtra
ProGet server URL	text	Server
ProGet user name	text	UserName	The name of a user in ProGet that can access the specified feed.
ProGet password	text	Password	The password of a user in ProGet that can access the specified feed.
Record deployment in ProGet	true/false	RecordDeployment

Push Package - Uploads a universal package to a ProGet feed.

Push Package

Uploads a universal package to a ProGet feed.

Script usage:

ProGet::Push-Package(
	[Credentials: <text>],
	Feed: <text>,
	FilePath: <text>,
	[Group: <text>],
	[Name: <text>],
	[Version: <text>],
	[Description: <text>],
	[Title: <text>],
	[Icon: <text>],
	[Dependencies: <@(text)>],
	[Server: <text>],
	[UserName: <text>],
	[Password: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
☆ Feed name	text	Feed	This argument is required.
☆ Package file path	text	FilePath	This argument is required.
Group name	text	Group
Package name	text	Name
Version	text	Version
Description	text	Description	The package description supports Markdown syntax.
Title	text	Title
Icon	text	Icon	A string of an absolute url pointing to an image to be displayed in the ProGet UI (at both 64px and 128px); if package:// is used as the protocol, ProGet will search within the package and serve that image instead
Dependencies	@(text)	Dependencies	Dependencies should be supplied as a list, each consisting of a package identification string; this string is formatted as follows: «group»:«package-name» «group»:«package-name»:«version» When the version is not specified, the latest is used.
ProGet server URL	text	Server
ProGet user name	text	UserName	The name of a user in ProGet that can access the specified feed.
ProGet password	text	Password	The password of a user in ProGet that can access the specified feed.

Registry

Ensure Registry Key - Ensures that a registry key exists or does not exist.

Ensure Registry Key

Ensures that a registry key exists or does not exist.

Script usage:

Windows::Ensure-RegistryKey(
	[Exists: <true/false>],
	[DefaultValue: <text>],
	Hive: <integer>,
	Key: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
Exists	true/false	Exists
Default value	text	DefaultValue	A key's default value is the legacy unnamed value that every registry key may have. This is rarely used.
☆ Hive	integer	Hive	This argument is required.
☆ Key	text	Key	This argument is required.

Example:

Windows::Ensure-RegistryKey
(
    Hive: LocalMachine,
    Key: SOFTWARE\Inedo\BuildMaster
);

Ensure Registry Value - Ensures that a registry value exists or does not exist on a specified key.

Ensure Registry Value

Ensures that a registry value exists or does not exist on a specified key.

Script usage:

Windows::Ensure-RegistryValue(
	Name: <text>,
	[Value: <@(text)>],
	[Kind: <integer>],
	[Exists: <true/false>],
	Hive: <integer>,
	Key: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Value name	text	Name	This argument is required.
Value	@(text)	Value
Value kind	integer	Kind
Exists	true/false	Exists
☆ Hive	integer	Hive	This argument is required.
☆ Key	text	Key	This argument is required.

Example:

Windows::Ensure-RegistryValue
(
    Name: ServicePath,
    Value: C:\BuildMaster\Service,
    Hive: LocalMachine,
    Key: SOFTWARE\Inedo\BuildMaster
);

Get Registry Value - Reads a value from the Windows registry and stores it in a variable.

Get Registry Value

Reads a value from the Windows registry and stores it in a variable.

Script usage:

Windows::Get-RegistryValue(
	Hive: <integer>,
	Key: <text>,
	Name: <text>,
	[Value: <RuntimeValue>],
	[FailIfNotFound: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Hive	integer	Hive	This argument is required.
☆ Key	text	Key	This argument is required.
☆ Value name	text	Name	This argument is required.
⇒ Store to variable	RuntimeValue	Value
Fail if value not found	true/false	FailIfNotFound

Example:

Windows::Get-RegistryValue
(
    Hive: LocalMachine,
    Key: SOFTWARE\7-Zip,
    Name: Path,
    Value => $PathTo7Zip
);

Reports

Artifact Comparison Report - Compares the contents of two artifacts and generates a diff report.

Artifact Comparison Report

Compares the contents of two artifacts and generates a diff report.

Script usage:

Compare-Artifacts(
	Name: <text>,
	Scope: <integer>,
	Artifact: <text>
);

This operation may be prefixed with Reports::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Report name	text	Name	This argument is required.
☆ Scope	integer	Scope	This argument is required.
☆ Artifact name	text	Artifact	This argument is required.

Example:

# generate an artifact comparison report for a build
Compare-Artifacts (
    Name: Website Diff Report,
    Scope: Release,
    Artifact: Hdars-Web
);

Capture HTML Report from Directory - Captures all HTML files from a directory into a browsable build report.

Capture HTML Report from Directory

Captures all HTML files from a directory into a browsable build report.

Script usage:

Capture-HtmlDirectoryReport(
	[FromDirectory: <text>],
	Index: <text>,
	[Preview: <text>],
	Name: <text>
);

This operation may be prefixed with Reports::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
From directory	text	FromDirectory
☆ HTML index page	text	Index	The HTML index page is the first page that is viewed when the report is opened and should contain links to other pages captured in the report. This argument is required.
Preview page	text	Preview	The preview page is displayed on the build overview page.
☆ Report name	text	Name	This argument is required.

Note: At a minimum, the specified index file is required. The preview HTML file is optional, but may be desirable to provide a quick summary of the report contents. Links to other pages in the report should be relative from the root directory captured.

Example:

# create a report from the files in the working directory
Capture-HtmlDirectoryReport(
    Name: Files In Working Directory,
    Index: index.html,
    Preview: preview.html
);

Capture Report from File - Captures a plain text or HTML file as a build report.

Capture Report from File

Captures a plain text or HTML file as a build report.

Script usage:

Capture-FileReport(
	Path: <text>,
	[Html: <true/false>],
	Name: <text>
);

This operation may be prefixed with Reports::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ From file (default)	text	Path	This argument is required.
HTML format	true/false	Html
☆ Report name	text	Name	This argument is required.

Example:

# create a report from the files in the working directory
Capture-FileReport(
    Name: Diff Tool Output,
    Index: index.html
);

Directory Comparison Report - Compares the contents of two directories and generates a diff report.

Directory Comparison Report

Compares the contents of two directories and generates a diff report.

Script usage:

Compare-Directories(
	From: <text>,
	To: <text>,
	[IncludeUnchanged: <true/false>],
	Name: <text>
);

This operation may be prefixed with Reports::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Previous directory	text	From	The "reference" or "from" directory containing the initial state of the files and subdirectories. This argument is required.
☆ Current directory	text	To	The "to" directory containing the final state of the files and subdirectories. This argument is required.
Include unchanged	true/false	IncludeUnchanged	Whether to include unchanged files and directories in report.
☆ Report name	text	Name	This argument is required.

Servers

Acquire Server - Acquires a server from a resource pool defined by a server role. This operation is affected by execution priority.

Acquire Server

Acquires a server from a resource pool defined by a server role. This operation is affected by execution priority.

Script usage:

Acquire-Server(
	[Role: <text>],
	[ServerName: <text>],
	[Verbose: <true/false>],
	[DoNotShare: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Server role	text	Role	A server role that defines the list of servers to be used as the source of the pool.
⇒ Server name output	text	ServerName
Log verbose	true/false	Verbose
Do not share	true/false	DoNotShare	Do not share this server between multiple AcquireServerOperation uses in this execution. This means that you must call Release Server in order to acquire the same server before the execution finishes.

Example:

# acquires a server associated with the build-servers role
Acquire-Server( 
   Role: build-servers,
   ServerName => $AcquiredServerName
);

for server $AcquiredServerName
{
    Log-Information Acquired server: $ServerName;
}

Release Server - Releases a server from a resource pool if acquired previously in the execution.

Release Server

Releases a server from a resource pool if acquired previously in the execution.

Script usage:

Release-Server(
	Server: <text>,
	[Role: <text>],
	[Verbose: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Server name (default)	text	Server	This argument is required.
Server role	text	Role
Log verbose	true/false	Verbose

Example:

# releases a server acquired earlier in a plan
Acquire-Server( 
   Role: build-servers,
   ServerName => $AcquiredServerName
);

# ...

Release-Server( 
   Role: build-servers,
   Server: $AcquiredServerName
);

Restart Server - Restarts a server and waits for it to become available again.

Restart Server

Restarts a server and waits for it to become available again.

Script usage:

Restart-Server(
	[After: <integer>],
	[MinimumDelay: <integer>]
);

This operation may be prefixed with BuildMaster::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
Restart after	integer	After
Minimum reconnect wait	integer	MinimumDelay

Note: The After and MinimumDelay properties are advanced options, and determine how many seconds to wait before the operating system shutdown is initiated (default and minimum value is 5), and how many seconds to wait until attempting to reconnect to the agent (default and minimum value is 15). These generally should be kept at defaults, unless the server takes an extraordinary time to shutdown.

Note: If the server is used by another operation before this operation completes, then the results are undefined.

Example:

    # restart the current server after 10 seconds
    Restart-Server(
        After: 10
    );

Services

Ensure Service - Ensures the configuration of a Windows service on a server.

Ensure Service

Ensures the configuration of a Windows service on a server.

Script usage:

Ensure-Service(
	Name: <text>,
	[DisplayName: <text>],
	[Description: <text>],
	[Status: <integer>],
	[Exists: <true/false>],
	Path: <text>,
	[Startup: <integer>],
	[DelayedStart: <true/false>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <text>],
	[FirstFailure: <integer>],
	[SecondFailure: <integer>],
	[SubsequentFailures: <integer>],
	[RestartDelay: <integer>],
	[OnFailureProgramPath: <text>],
	[RebootMessage: <text>],
	[Dependencies: <@(text)>],
	[StatusChangeTimeout: <TimeSpan>]
);

This operation may be prefixed with Windows::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Name	text	Name	This argument is required.
Display name	text	DisplayName
Description	text	Description
Status	integer	Status
Exists	true/false	Exists
☆ Path w/ arguments	text	Path	The executable path of the service. This field may include any arguments that will be supplied to the executable. Executable paths that include spaces should be wrapped with double-quotes, e.g.: "C:\Program Files\Hdars\Hdars.Service.exe" -arg1 -arg2 This argument is required.
Startup	integer	Startup	Startup type
DelayedStart	true/false	DelayedStart	Delayed start
Credentials	text	Credentials	The Otter credential name to use as the service's Log On user. If a credential name is specified, the username and password fields will be ignored.
User name	text	UserName	The user account name to run the service as. If this value is not supplied, NT AUTHORITY\LocalSystem will be assumed.
Password	text	Password	The password for the account that runs the service. If NT AUTHORITY\LocalSystem is specified, this field must not have a value set.
First failure	integer	FirstFailure
Second failure	integer	SecondFailure
Subsequent failures	integer	SubsequentFailures
Restart delay	integer	RestartDelay
Run program	text	OnFailureProgramPath
Reboot message	text	RebootMessage
Dependencies	@(text)	Dependencies
Status change timeout	TimeSpan	StatusChangeTimeout	The number of seconds to wait for a server to change between two statuses (e.g. stopped to starting) before raising an error.

Example:

# ensures the HdarsSvc is present on the server using the HdarsSvc credentials in Otter
Windows::Ensure-Service
(
    Name: HdarsSvc,
    DisplayName: HDARS Console Log Service,
    Status: Running,
    Path: E:\Services\Hdars.Service.exe,
    Startup: Auto,
    Credentials: HdarsSvc,
    FirstFailure: Restart
);

Start Windows Service - Starts an existing Windows service.

Start Windows Service

Starts an existing Windows service.

Script usage:

Start-Service(
	Name: <text>,
	[WaitForRunningStatus: <true/false>],
	[FailIfServiceDoesNotExist: <true/false>]
);

This operation may be prefixed with Windows::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Service name (default)	text	Name	This argument is required.
Wait for running status	true/false	WaitForRunningStatus
Fail if service does not exist	true/false	FailIfServiceDoesNotExist

Example:

# starts the HDARS service on the remote server
Start-Service HDARS;

Stop Windows Service - Stops an existing Windows service.

Stop Windows Service

Stops an existing Windows service.

Script usage:

Stop-Service(
	Name: <text>,
	[WaitForStoppedStatus: <true/false>],
	[FailIfServiceDoesNotExist: <true/false>]
);

This operation may be prefixed with Windows::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Service name (default)	text	Name	This argument is required.
Wait for stopped status	true/false	WaitForStoppedStatus
Fail if service does not exist	true/false	FailIfServiceDoesNotExist

Example:

# stops the HDARS service on the remote server
Stop-Service HDARS;

Source Control

Apply Label - Applies a label to source files in the repository.

Apply Label

Applies a label to source files in the repository.

Script usage:

Apply-Label(
	Provider: <text>,
	Label: <text>,
	SourcePath: <text>
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Provider name	text	Provider	This argument is required.
☆ Label/tag	text	Label	This argument is required.
☆ Source path	text	SourcePath	The path in source control to label. This path is a provider-specific string that may include additional information like branch name, etc. See the documentation on inedo.com regarding the specific source control system in use. This argument is required.

Example:

# tags files "rel-0.1.4" under MarketingPortal from the provider named Mercurial2, using the remote URL supplied in the 
# HdarsRepo repository on the master branch 
Apply-Label(
    Provider: Mercurial2,
    Label: rel-0.1.4,
    From: HdarsRepo|master:MarketingPortal/
);

Ensure GitHub Release - Creates or updates a tagged release in a GitHub repository.

Ensure GitHub Release

Creates or updates a tagged release in a GitHub repository.

Script usage:

GitHub::Ensure-Release(
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>],
	Tag: <text>,
	[Target: <text>],
	[Title: <text>],
	[Description: <text>],
	[Draft: <true/false>],
	[Prerelease: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.
☆ Tag name	text	Tag	This argument is required.
Target commit	text	Target	May be specified as a branch name, a commit hash, or left blank for the latest commit on the default branch (usually master).
Title	text	Title	If left blank, the tag name will be used for new releases and existing releases will keep their original title.
Description	text	Description	Release notes, formatted as Markdown. Leave blank to keep the existing release notes.
Is draft	true/false	Draft
Is prerelease	true/false	Prerelease

Get Labeled - Gets the version of code from a repository with the specified label or tag.

Get Labeled

Gets the version of code from a repository with the specified label or tag.

Script usage:

Get-Labeled-Source(
	Provider: <text>,
	Label: <text>,
	[SourcePath: <text>],
	[ToDirectory: <text>],
	[ClearTarget: <true/false>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Provider name	text	Provider	This argument is required.
☆ Label/tag	text	Label	This argument is required.
Source path	text	SourcePath	The path in source control to get labeled from. This path is a provider-specific string that may include additional information like branch name, etc. See the documentation on inedo.com regarding the specific source control system in use.
To directory	text	ToDirectory
Clear target	true/false	ClearTarget	When set to true, clears the target directory before getting the files.

Example:

# get the files tagged rel-0.1.4 under MarketingPortal from the provider named Mercurial2, using the remote URL supplied in the 
# HdarsRepo repository on the master branch 
Get-Latest-Source(
    Provider: Mercurial2,
    Label: rel-0.1.4,
    From: HdarsRepo|master:MarketingPortal/
);

Get Latest - Gets the latest version of code from a repository.

Get Latest

Gets the latest version of code from a repository.

Script usage:

Get-Latest-Source(
	Provider: <text>,
	SourcePath: <text>,
	[ToDirectory: <text>],
	[ClearTarget: <true/false>]
);

This operation may be prefixed with SourceControl::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Provider name	text	Provider	This argument is required.
☆ Source path	text	SourcePath	The path in source control to get latest from. This path is a provider-specific string that may include additional information like branch name, etc. See the documentation on inedo.com regarding the specific source control system in use. This argument is required.
To directory	text	ToDirectory
Clear target	true/false	ClearTarget	When set to true, clears the target directory before getting the files.

Example:

# get the latest MarketingPortal files from the provider named Mercurial2, using the remote URL supplied in the 
# HdarsRepo repository on the featureXYZ branch 
Get-Latest-Source(
    Provider: Mercurial2,
    From: HdarsRepo|featureXYZ:MarketingPortal/
);

Get Source from Git Repository - Gets the source code from a general Git repository.

Get Source from Git Repository

Gets the source code from a general Git repository.

Script usage:

Git::Get-Source(
	[Credentials: <text>],
	[RepositoryUrl: <text>],
	[DiskPath: <text>],
	[Branch: <text>],
	[Ref: <text>],
	[CommitHash: <text>],
	[KeepInternals: <true/false>],
	[UserName: <text>],
	[Password: <SecureString>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
Repository URL	text	RepositoryUrl
Export to directory	text	DiskPath
Branch name	text	Branch
Reference	text	Ref	A reference such as a tag name or a commit hash.
⇒ Commit hash	text	CommitHash	The full SHA1 hash of the fetched commit will be stored in this variable.
Copy internal Git files	true/false	KeepInternals	When exporting the repository, also export .git* files.
User name	text	UserName
Password	SecureString	Password
Git executable path	text	GitExePath
Recurse submodules	true/false	RecurseSubmodules
Workspace disk path	text	WorkspaceDiskPath	If not set, a workspace name will be automatically generated and persisted based on the Repository URL or other host-specific information (e.g. GitHub's repository name).
Clean workspace	true/false	CleanWorkspace	If set to true, the workspace directory will be cleared before any Git-based operations are performed.

Example:

# pulls source from a remote repository and archives/exports the contents to a target directory
Git::Get-Source(
    Credentials: Hdars-Git,
    RepositoryUrl: https://github.com/Inedo/git-test.git,
    DiskPath: ~\Sources
);

Get Source from GitHub Repository - Gets the source code from a GitHub repository.

Get Source from GitHub Repository

Gets the source code from a GitHub repository.

Script usage:

GitHub::Get-Source(
	[Credentials: <text>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>],
	[DiskPath: <text>],
	[Branch: <text>],
	[Ref: <text>],
	[CommitHash: <text>],
	[KeepInternals: <true/false>],
	[UserName: <text>],
	[Password: <SecureString>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.
Export to directory	text	DiskPath
Branch name	text	Branch
Reference	text	Ref	A reference such as a tag name or a commit hash.
⇒ Commit hash	text	CommitHash	The full SHA1 hash of the fetched commit will be stored in this variable.
Copy internal Git files	true/false	KeepInternals	When exporting the repository, also export .git* files.
User name	text	UserName
Password	SecureString	Password
Git executable path	text	GitExePath
Recurse submodules	true/false	RecurseSubmodules
Workspace disk path	text	WorkspaceDiskPath	If not set, a workspace name will be automatically generated and persisted based on the Repository URL or other host-specific information (e.g. GitHub's repository name).
Clean workspace	true/false	CleanWorkspace	If set to true, the workspace directory will be cleared before any Git-based operations are performed.

Example:

# pulls source from a remote repository and archives/exports the contents to a target directory
GitHub::Get-Source(
    Credentials: Hdars-GitHub,
    Organization: Hdars,
    DiskPath: ~\Sources
);

Set GitHub Build Status - Sets a status message on a GitHub commit.

Set GitHub Build Status

Sets a status message on a GitHub commit.

Script usage:

GitHub::Set-Status(
	[AdditionalContext: <text>],
	CommitHash: <text>,
	Status: <integer>,
	[Description: <text>],
	[NormalDescription: <text>],
	[WarningDescription: <text>],
	[ErrorDescription: <text>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Additional context	text	AdditionalContext	Appears in the commit status dialog on GitHub after "ci/buildmaster". Used to differentiate between multiple BuildMaster statuses on the same commit. In most cases, it is safe to leave this blank.
☆ Git commit hash	text	CommitHash	This argument is required.
☆ Status	integer	Status	This argument is required.
Description	text	Description	Used for all statuses except 'auto'
Complete (success)	text	NormalDescription
Complete (warning)	text	WarningDescription
Complete (error)	text	ErrorDescription
Credentials	text	Credentials
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.

Example:

try
{
    GitHub::Set-Status (
        Status = pending,
        ...
    );

    ...
}
catch
{
    # make sure the status is set even if the build fails.
    error;
}

GitHub::Set-Status (
    Status = auto,
    ...
);

Tag - Copies a path in Source Control to a tag.

Tag

Copies a path in Source Control to a tag.

Script usage:

Tag-Path(
	Provider: <text>,
	SourcePath: <text>,
	To: <text>,
	[Comment: <text>]
);

This operation may be prefixed with Core::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Provider name	text	Provider	This argument is required.
☆ Source path	text	SourcePath	The path in source control to branch/tag from. This path is a provider-specific string that may include additional information like branch name, etc. See the documentation on inedo.com regarding the specific source control system in use. This argument is required.
☆ Tag/branch path	text	To	This argument is required.
Comment	text	Comment

Example:

# tags files "rel-0.1.4" under MarketingPortal from the provider named Mercurial2, using the remote URL supplied in the 
# HdarsRepo repository on the master branch 
Tag-Path(
    Provider: MySvn,
    From: /myapp/trunk,
    To: /myapp/branches/$ReleaseNumber
);

Tag Git Source - Tags the source code in a general Git repository.

Tag Git Source

Tags the source code in a general Git repository.

Script usage:

Git::Tag(
	[Credentials: <text>],
	[RepositoryUrl: <text>],
	Tag: <text>,
	[Message: <text>],
	[Branch: <text>],
	[CommitHash: <text>],
	[Force: <true/false>],
	[UserName: <text>],
	[Password: <SecureString>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
Repository URL	text	RepositoryUrl
☆ Tag name	text	Tag	This argument is required.
Tag message	text	Message	When this is not specified, a lightweight tag is created.
Branch name	text	Branch
Commit hash	text	CommitHash	The tag will refer to this commit if specified; otherwise it will refer to the current head.
Force	true/false	Force	Overwrite another tag that has the same name; otherwise using an existing tag name is an error.
User name	text	UserName
Password	SecureString	Password
Git executable path	text	GitExePath
Recurse submodules	true/false	RecurseSubmodules
Workspace disk path	text	WorkspaceDiskPath	If not set, a workspace name will be automatically generated and persisted based on the Repository URL or other host-specific information (e.g. GitHub's repository name).
Clean workspace	true/false	CleanWorkspace	If set to true, the workspace directory will be cleared before any Git-based operations are performed.

Example:

# tags the current source tree with the current release name and package number
Git::Tag(
    Credentials: Hdars-Git,
    RepositoryUrl: https://github.com/Inedo/git-test.git,
    Tag: $ReleaseName.$PackageNumber
);

Tag GitHub Source - Tags the source code in a GitHub repository.

Tag GitHub Source

Tags the source code in a GitHub repository.

Script usage:

GitHub::Tag(
	[Credentials: <text>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>],
	Tag: <text>,
	[Message: <text>],
	[Branch: <text>],
	[CommitHash: <text>],
	[Force: <true/false>],
	[UserName: <text>],
	[Password: <SecureString>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.
☆ Tag name	text	Tag	This argument is required.
Tag message	text	Message	When this is not specified, a lightweight tag is created.
Branch name	text	Branch
Commit hash	text	CommitHash	The tag will refer to this commit if specified; otherwise it will refer to the current head.
Force	true/false	Force	Overwrite another tag that has the same name; otherwise using an existing tag name is an error.
User name	text	UserName
Password	SecureString	Password
Git executable path	text	GitExePath
Recurse submodules	true/false	RecurseSubmodules
Workspace disk path	text	WorkspaceDiskPath	If not set, a workspace name will be automatically generated and persisted based on the Repository URL or other host-specific information (e.g. GitHub's repository name).
Clean workspace	true/false	CleanWorkspace	If set to true, the workspace directory will be cleared before any Git-based operations are performed.

Example:

# tags the current source tree with the current release name and package number
GitHub::Tag(
    Credentials: Hdars-GitHub,
    Organization: Hdars,
    Tag: $ReleaseName.$PackageNumber
);

TFS Get Source - Gets the source code from a TFS repository.

TFS Get Source

Gets the source code from a TFS repository.

Script usage:

TFS::Tfs-GetSource(
	[Credentials: <text>],
	[SourcePath: <text>],
	[DiskPath: <text>],
	[Label: <text>],
	[WorkspaceName: <text>],
	[WorkspaceDiskPath: <text>],
	[Url: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Domain: <text>]
);

Arguments:

Name	Format	Script Usage
Credentials	text	Credentials
Source path	text	SourcePath
Export to directory	text	DiskPath
Label	text	Label
Workspace name	text	WorkspaceName
Workspace disk path	text	WorkspaceDiskPath
Project collection URL	text	Url
User name	text	UserName
Password / token	text	Password
Domain name	text	Domain

Example:

# checkout a remote repository locally
Tfs-GetSource(
    Credentials: Hdars-Tfs,
    SourcePath: `$/HdarsApp,
    DiskPath: ~\Sources
);

TFS Label - Labels a specified source path in TFS.

TFS Label

Labels a specified source path in TFS.

Script usage:

TFS::Tfs-Label(
	[Credentials: <text>],
	[SourcePath: <text>],
	Label: <text>,
	[Comment: <text>],
	[Url: <text>],
	[UserName: <text>],
	[Password: <text>],
	[Domain: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Credentials	text	Credentials
Source path	text	SourcePath
☆ Label	text	Label	This argument is required.
Comment	text	Comment
Project collection URL	text	Url
User name	text	UserName
Password / token	text	Password
Domain name	text	Domain

Example:

# labels the current application's path with the current package number
Tfs-ApplyLabel(
    Credentials: Hdars-Tfs,
    SourcePath: `$/$ApplicationName,
    Label: BM-$ReleaseName-$PackageNumber
);

Upload GitHub Release Assets - Uploads files as attachments to a GitHub release.

Upload GitHub Release Assets

Uploads files as attachments to a GitHub release.

Script usage:

GitHub::Upload-ReleaseAssets(
	Tag: <text>,
	Include: <@(text)>,
	[Exclude: <@(text)>],
	[Directory: <text>],
	[ContentType: <text>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Tag	text	Tag	The tag associated with the release. The release must already exist. This argument is required.
☆ Include	@(text)	Include	See KB#1119 to learn more about masking syntax. This argument is required.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
Directory	text	Directory
Content type	text	ContentType	The content type of the assets. For a list of acceptable types, see the IANA list of media types.
Credentials	text	Credentials
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Leave this value blank to connect to github.com. For local installations of GitHub enterprise, an API URL must be specified.

Upack

Query Package - Tests whether a universal package exists and optionally extracts its metadata.

Query Package

Tests whether a universal package exists and optionally extracts its metadata.

Script usage:

UPack::Query-Package(
	[PackageFile: <text>],
	[FeedUrl: <text>],
	[Credentials: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Name: <text>],
	[Version: <text>],
	[Exists: <true/false>],
	[Metadata: <%(key1: value1, ...)>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Package file	text	PackageFile	When specified, FeedUrl, UserName, Password, PackageName, and PackageVersion are ignored.
ProGet server URL	text	FeedUrl
Credentials	text	Credentials
User name	text	UserName
Password	SecureString	Password
Package name	text	Name
Package version	text	Version
⇒ Package exists	true/false	Exists	When specified, this string variable will be set to "true" if the package exists or "false" if it does not.
⇒ Package metadata	%(key1: value1, ...)	Metadata	When specified, this map variable will be assigned containing all of the package's metadata. If the package does not exist this value is not defined.

Example:

# test whether a package exists in a feed and capture its metadata
Query-Package
(
    Credentials: MyExternalFeed,
    PackageName: Group/Package,
    Exists => $exists,
    Metadata => %packageData
);

if $exists
{
    Log-Debug 'Package $(%packageData.name) exists. Latest version is $(%packageData.version).';
}

Variables

Apply Template - Applies full template transformation on a literal, a file, or a template asset.

Apply Template

Applies full template transformation on a literal, a file, or a template asset.

Script usage:

InedoCore::Apply-Template(
	[Asset: <text>],
	[OutputVariable: <text>],
	[OutputFile: <text>],
	[Literal: <text>],
	[InputFile: <text>],
	[AdditionalVariables: <%(key1: value1, ...)>],
	[NewLines: <integer>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Asset (default)	text	Asset
⇒ Store to variable	text	OutputVariable
Output file	text	OutputFile
Literal	text	Literal	Variables are not expanded within the contents of this property.
Input file	text	InputFile
Additional variables	%(key1: value1, ...)	AdditionalVariables
New lines	integer	NewLines

Note: When reading from or writing to a file, there must be a valid server context.

Example:

# applies the a literal template and stores the result in $text
Apply-Template
(
    Literal: >>Hello from $ServerName!
<% if $IsSimulation { %> This is a simulation run. <% } else { %> This is not a simulation run. <% } %>
Thanks,
$MyName
>>,
    OutputVariable => $text,
    AdditionalVariables: %(MyName: Steve)
);

Windows

Sign Binary - Signs .exe or .dll files using an installed code signing certificate.

Sign Binary

Signs .exe or .dll files using an installed code signing certificate.

Script usage:

Sign-Exe(
	SubjectName: <text>,
	[TimestampServer: <text>],
	[ContentDescription: <text>],
	[ContentUrl: <text>],
	Include: <@(text)>,
	[Exclude: <@(text)>],
	[SignToolPath: <text>],
	[SourceDirectory: <text>]
);

This operation may be prefixed with Windows::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Subject	text	SubjectName	The subject name of the certificate. This is used to identify the certificate. This argument is required.
Timestamp server	text	TimestampServer	This server will be used to add a timestamp to the signature.
Description	text	ContentDescription	The content description that will be included with the signature.
URL	text	ContentUrl	The content URL that will be included with the signature.
☆ Include (default)	@(text)	Include	See KB#1119 to learn more about masking syntax. This argument is required.
Exclude	@(text)	Exclude	See KB#1119 to learn more about masking syntax.
signtool.exe path	text	SignToolPath	The full path of signtool.exe.
Directory	text	SourceDirectory

XDT Transform - Performs an XDT transform on a configuration file.

XDT Transform

Performs an XDT transform on a configuration file.

Script usage:

XDT-Transform(
	SourceFile: <text>,
	TransformFile: <text>,
	[DestinationFile: <text>],
	[PreserveWhitespace: <true/false>],
	[Verbose: <true/false>]
);

This operation may be prefixed with Windows::, although this is a built-in namespace and isn't really necessary.

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Source file	text	SourceFile	The source file the transform is applied to. This argument is required.
☆ Transform file	text	TransformFile	The XDT file used to transform the configuration file. This argument is required.
Destination file	text	DestinationFile	The file path for the result of the transform. If not specified, the source file will be used.
Preserve whitespace	true/false	PreserveWhitespace	Indicates whether whitespace should be preserved in the destination file.
Verbose logging	true/false	Verbose