Built-in Operations

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.

BuildMaster

Backup Application - Exports an application to a package source.

Backup Application

Exports an application to a package source.

Script usage:

System::Backup-Application(
	[Application: <text>],
	PackageSource: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
Application name	text	Application
☆ Package source	text	PackageSource	This argument is required.

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>],
	[Pipeline: <text>],
	[Variables: <%(key1: value1, ...)>],
	[ForcePromotion: <true/false>],
	[Wait: <true/false>],
	[FailIfCannotCreate: <true/false>],
	[DeployToFirstStage: <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".
With pipeline	text	Pipeline	This is used if ReleaseNumber is empty.
Build variables	%(key1: value1, ...)	Variables
Force past gate	true/false	ForcePromotion
Wait for execution	true/false	Wait
Fail if nothing created	true/false	FailIfCannotCreate
Deploy to first stage	true/false	DeployToFirstStage

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>],
	[BuildNumber: <text>],
	[Variables: <%(key1: value1, ...)>],
	[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".
Build number	text	BuildNumber	Select a specific build number. This may also be left blank to select all active builds.
Deployment variables	%(key1: value1, ...)	Variables
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 OtterScript specified as a string.

Invoke OtterScript

Executes OtterScript 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 Script - Executes an OtterScript-based Script stored in BuildMaster.

Invoke Script

Executes an OtterScript-based Script stored in BuildMaster.

Script usage:

Invoke-Script(
	Script: <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 (default)	text	Script	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 call the global "MyDeploy" script and pass in a variable called $name with value "Steve"
Invoke-Plan global::MyDeploy
(
    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

Reject Build - Rejects a BuildMaster build.

Reject Build

Rejects a BuildMaster build.

Script usage:

Reject-Build(
	[Application: <text>],
	[ReleaseNumber: <text>],
	BuildNumber: <text>,
	[FailIfAlreadyRejected: <true/false>],
	[RejectionNotes: <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
In application	text	Application
With release	text	ReleaseNumber
☆ Build number (default)	text	BuildNumber	This argument is required.
Fail if build is already rejected	true/false	FailIfAlreadyRejected
Rejection notes	text	RejectionNotes

Example:

Reject-Build $BuildToReject;

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

Set Build Number

Sets (changes) 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.

Build Number in Context: This operation will do two things: change the BuildNumber in the database and create a runtime variable named $BuildNumber with the new build number. However, it will *not* update the execution context with the new BuildNumber; this means that, for some operations that rely on the BuildNumber in context (instead of looking up the BuildNumber based on the BuildId), this will likely result in a "build not found" or such error. To resolve this, explicitly pass in $BuildNumber as an argument. For example, if you create an artifact after setting the BuildNumber, explicitly pass in the BuildNumber.

Example:

# The build.xml file contains a project version we wish to show users in the build number
PSCall GLOBAL::ExtractProjectVersion
(
    buildFilePath: $WorkingDirectory\build.xml,
    OutputArg => $ProjectVersionTemp
);

# This will update the build number
Set-BuildNumber $ExtractProjectVersion.$BuildNumber;

Set Build Variable - Creates or updates a variable on a build.

Set Build Variable

Creates or updates a variable on a build.

Script usage:

Set-BuildVariable(
	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

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

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:

SqlServer::Bundle-SqlScripts(
	[Directory: <text>],
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	OutputFile: <text>
);

Arguments:

Name	Format	Script Usage	Usage Notes
From 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.
☆ Output file	text	OutputFile	This argument is required.

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>],
	[Group: <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.
Initialize database	true/false	InitializeDatabase
Group	text	Group

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>,
	[LogStatement: <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.
☆ SQL Statement	text	Statement	This argument is required.
Log statement to execute	true/false	LogStatement

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

Docker

Assemble Docker Image - A simplified version of Build Docker Image for when the full power of a Dockerfile is not required.

Assemble Docker Image

A simplified version of Build Docker Image for when the full power of a Dockerfile is not required.

Script usage:

Docker::Assemble-Image(
	Source: <text>,
	RepositoryName: <text>,
	[Tag: <text>],
	BaseSource: <text>,
	BaseRepositoryName: <text>,
	BaseTag: <text>,
	[From: <text>],
	[To: <text>],
	[Cmd: <text>],
	[Env: <%(key1: value1, ...)>],
	[Volumes: <@(text)>],
	[AdditionalArguments: <text>],
	[AttachToBuild: <true/false>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Container Source	text	Source	This argument is required.
☆ Repository name	text	RepositoryName	This argument is required.
Tag	text	Tag
☆ Container Source	text	BaseSource	This argument is required.
☆ Repository name	text	BaseRepositoryName	This argument is required.
☆ Tag	text	BaseTag	This argument is required.
External path	text	From
Internal path	text	To
Command	text	Cmd
Environment variables	%(key1: value1, ...)	Env
Data paths	@(text)	Volumes
Addtional arguments	text	AdditionalArguments	Additional arguments for the docker CLI build command, such as --build-arg=ARG_NAME=value
Attach to build	true/false	AttachToBuild
Docker client path	text	DockerExePath

Build Docker Image - Builds a Docker image using a text template and pushes it to a specified container source.

Build Docker Image

Builds a Docker image using a text template and pushes it to a specified container source.

Script usage:

Docker::Build-Image(
	DockerfileAsset: <text>,
	[TemplateArguments: <%(key1: value1, ...)>],
	Source: <text>,
	[From: <text>],
	RepositoryName: <text>,
	Tag: <text>,
	[AdditionalArguments: <text>],
	[AttachToBuild: <true/false>],
	[RemoveAfterPush: <true/false>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Dockerfile text template	text	DockerfileAsset	This argument is required.
Addtional template arguments	%(key1: value1, ...)	TemplateArguments
☆ Container registry source	text	Source	This argument is required.
From	text	From
☆ Repository name	text	RepositoryName	This argument is required.
☆ Tag	text	Tag	This argument is required.
Addtional arguments	text	AdditionalArguments	Additional arguments for the docker CLI build command, such as --build-arg=ARG_NAME=value
Attach to build	true/false	AttachToBuild
Remove after pushing	true/false	RemoveAfterPush
Docker client path	text	DockerExePath

Docker exec in Container - Attaches and runs a command in an already running container

Docker exec in Container

Attaches and runs a command in an already running container

Script usage:

Docker::Docker-Exec(
	ContainerName: <text>,
	Command: <text>,
	[WorkDir: <text>],
	[Interactive: <true/false>],
	[RunInBackground: <true/false>],
	[AdditionalArguments: <text>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Container name	text	ContainerName	This argument is required.
☆ Command	text	Command	This argument is required.
Working directory in container	text	WorkDir
Log output (interactive)	true/false	Interactive	Keep STDIN open even if not attached
Run in background (detach)	true/false	RunInBackground	Detached mode: run command in the background
Addtional arguments	text	AdditionalArguments	Additional arguments for the docker CLI exec command, such as --env key=value
Docker client path	text	DockerExePath

Run Docker Container - Runs a Docker container on a container host server using a container configuration file.

Run Docker Container

Runs a Docker container on a container host server using a container configuration file.

Script usage:

Docker::Run-Container(
	Source: <text>,
	RepositoryName: <text>,
	Tag: <text>,
	ConfigFileName: <text>,
	ConfigFileInstanceName: <text>,
	[ContainerName: <text>],
	[RunInBackground: <true/false>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Container source	text	Source	This argument is required.
☆ Repository name	text	RepositoryName	This argument is required.
☆ Tag	text	Tag	This argument is required.
☆ Container Configuration	text	ConfigFileName	This argument is required.
☆ Container Runtime	text	ConfigFileInstanceName	This argument is required.
Container name	text	ContainerName
Run in background	true/false	RunInBackground
Docker client path	text	DockerExePath

Stop or Delete Docker Container - Stops a running Docker Container on a container host server.

Stop or Delete Docker Container

Stops a running Docker Container on a container host server.

Script usage:

Docker::Stop-Container(
	ContainerName: <text>,
	[Remove: <true/false>],
	[FailIfContainerDoesNotExist: <true/false>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Container name	text	ContainerName	This argument is required.
Remove after stop	true/false	Remove
Fail if container does not exist	true/false	FailIfContainerDoesNotExist
Docker client path	text	DockerExePath

Tag Docker Image - Applies a new tag to a Docker image in the specified container source.

Tag Docker Image

Applies a new tag to a Docker image in the specified container source.

Script usage:

Docker::Tag-Image(
	RepositoryName: <text>,
	OriginalTag: <text>,
	Source: <text>,
	[DeactivateOriginalTag: <true/false>],
	[NewRepositoryName: <text>],
	NewTag: <text>,
	[NewSource: <text>],
	[AttachToBuild: <true/false>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Repository name	text	RepositoryName	This argument is required.
☆ Original tag	text	OriginalTag	This argument is required.
☆ Container source	text	Source	This argument is required.
Remove from build	true/false	DeactivateOriginalTag
Repository name	text	NewRepositoryName
☆ New tag	text	NewTag	This argument is required.
New container source	text	NewSource
Attach to build	true/false	AttachToBuild
Docker client path	text	DockerExePath

Docker Compose

Remove containers with Docker Compose - Stops containers and removes containers, networks, volumes, and images created by Docker::Compose-Up.

Remove containers with Docker Compose

Stops containers and removes containers, networks, volumes, and images created by Docker::Compose-Up.

Script usage:

Docker::Compose-Down(
	[Timeout: <integer>],
	ProjectName: <text>,
	[ComposeYaml: <text>],
	[WorkingDirectory: <text>],
	[Verbose: <true/false>],
	[AddArgs: <@(text)>],
	[Source: <text>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Timeout (seconds)	integer	Timeout
☆ Project name (default)	text	ProjectName	This argument is required.
Compose file (YAML)	text	ComposeYaml	You can specify the path to the "docker-compose.yaml" or this can be the compose file contents, eg. $FileContents(docker-compose.yml) or $ConfigurationFileText(Integration, docker-compose.yaml)
Working directory	text	WorkingDirectory
Verbose	true/false	Verbose
Additional docker-compose arguments	@(text)	AddArgs
Container source	text	Source
Docker client path	text	DockerExePath

Run command in Docker Compose - Runs an arbitrary docker-compose command.

Run command in Docker Compose

Runs an arbitrary docker-compose command.

Script usage:

Docker::Compose-Command(
	[Args: <@(text)>],
	ProjectName: <text>,
	[ComposeYaml: <text>],
	[WorkingDirectory: <text>],
	[Verbose: <true/false>],
	[Source: <text>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Command arguments	@(text)	Args
☆ Project name (default)	text	ProjectName	This argument is required.
Compose file (YAML)	text	ComposeYaml	You can specify the path to the "docker-compose.yaml" or this can be the compose file contents, eg. $FileContents(docker-compose.yml) or $ConfigurationFileText(Integration, docker-compose.yaml)
Working directory	text	WorkingDirectory
Verbose	true/false	Verbose
Container source	text	Source
Docker client path	text	DockerExePath

Set container status with Docker Compose - Starts, restarts, stops, pauses, or resumes existing containers for a service.

Set container status with Docker Compose

Starts, restarts, stops, pauses, or resumes existing containers for a service.

Script usage:

Docker::Compose-SetStatus(
	Action: <integer>,
	[Timeout: <integer>],
	[Signal: <text>],
	[Services: <@(text)>],
	ProjectName: <text>,
	[ComposeYaml: <text>],
	[WorkingDirectory: <text>],
	[Verbose: <true/false>],
	[AddArgs: <@(text)>],
	[Source: <text>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Action	integer	Action	This argument is required.
Timeout	integer	Timeout	Used for the Restart and Stop actions.
Signal	text	Signal	Used for the ForceStop action.
Services	@(text)	Services
☆ Project name (default)	text	ProjectName	This argument is required.
Compose file (YAML)	text	ComposeYaml	You can specify the path to the "docker-compose.yaml" or this can be the compose file contents, eg. $FileContents(docker-compose.yml) or $ConfigurationFileText(Integration, docker-compose.yaml)
Working directory	text	WorkingDirectory
Verbose	true/false	Verbose
Additional docker-compose arguments	@(text)	AddArgs
Container source	text	Source
Docker client path	text	DockerExePath

Update containers with Docker Compose - Builds, (re)creates, and optionally starts containers for a Docker Compose project.

Update containers with Docker Compose

Builds, (re)creates, and optionally starts containers for a Docker Compose project.

Script usage:

Docker::Compose-Up(
	[Recreate: <integer>],
	[Build: <integer>],
	[Timeout: <integer>],
	[StartContainers: <true/false>],
	[Services: <@(text)>],
	ProjectName: <text>,
	[ComposeYaml: <text>],
	[WorkingDirectory: <text>],
	[Verbose: <true/false>],
	[AddArgs: <@(text)>],
	[Source: <text>],
	[DockerExePath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Re-create containers	integer	Recreate
Build images	integer	Build
Timeout (seconds)	integer	Timeout
Start containers	true/false	StartContainers
Services	@(text)	Services
☆ Project name (default)	text	ProjectName	This argument is required.
Compose file (YAML)	text	ComposeYaml	You can specify the path to the "docker-compose.yaml" or this can be the compose file contents, eg. $FileContents(docker-compose.yml) or $ConfigurationFileText(Integration, docker-compose.yaml)
Working directory	text	WorkingDirectory
Verbose	true/false	Verbose
Additional docker-compose arguments	@(text)	AddArgs
Container source	text	Source
Docker client path	text	DockerExePath

DotNet

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

dotnet build - Builds a .NET Core/Framework/Standard project using dotnet build.

dotnet build

Builds a .NET Core/Framework/Standard project using dotnet build.

Script usage:

DotNet::Build(
	Project: <text>,
	[Configuration: <text>],
	[PackageSource: <text>],
	[Framework: <text>],
	[Runtime: <text>],
	[Output: <text>],
	[ForceDependencyResolution: <true/false>],
	[Verbosity: <integer>],
	[AdditionalArguments: <text>],
	[DotNetPath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Project path (default)	text	Project	This must be the path to either a project file, solution file, or a directory containing a project or solution file. This argument is required.
Configuration	text	Configuration
Package source	text	PackageSource	If specified, this NuGet package source will be used to restore packages when building.
Framework	text	Framework	For building multiple target frameworks at once, leave this field blank and also leave "Output" blank.
Runtime	text	Runtime
Output	text	Output	Specifies an output directory for the build. This is only valid if "Framework" is also specified.
Force dependency resolution	true/false	ForceDependencyResolution
Verbosity	integer	Verbosity
Additional arguments	text	AdditionalArguments
dotnet path	text	DotNetPath	Full path of dotnet.exe (or dotnet on Linux). This is usually C:\Program Files\dotnet\dotnet.exe on Windows. If no value is supplied, the operation will default to %PROGRAMFILES%\dotnet\dotnet.exe for Windows and dotnet (from the path) on Linux.

Example:

# Build ~\src\MyProject.csproj with Release configuration, restoring NuGet packages from the InternalNuGet source
DotNet::Build ~\src\MyProject.csproj
(
    Configuration: Release,
    PackageSource: InternalNuGet
);

dotnet publish - Publishes a .NET Core/Framework/Standard project using dotnet publish.

dotnet publish

Publishes a .NET Core/Framework/Standard project using dotnet publish.

Script usage:

DotNet::Publish(
	[SelfContained: <true/false>],
	Project: <text>,
	[Configuration: <text>],
	[PackageSource: <text>],
	[Framework: <text>],
	[Runtime: <text>],
	[Output: <text>],
	[ForceDependencyResolution: <true/false>],
	[Verbosity: <integer>],
	[AdditionalArguments: <text>],
	[DotNetPath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Self-contained	true/false	SelfContained
☆ Project path (default)	text	Project	This must be the path to either a project file, solution file, or a directory containing a project or solution file. This argument is required.
Configuration	text	Configuration
Package source	text	PackageSource	If specified, this NuGet package source will be used to restore packages when building.
Framework	text	Framework	For building multiple target frameworks at once, leave this field blank and also leave "Output" blank.
Runtime	text	Runtime
Output	text	Output	Specifies an output directory for the build. This is only valid if "Framework" is also specified.
Force dependency resolution	true/false	ForceDependencyResolution
Verbosity	integer	Verbosity
Additional arguments	text	AdditionalArguments
dotnet path	text	DotNetPath	Full path of dotnet.exe (or dotnet on Linux). This is usually C:\Program Files\dotnet\dotnet.exe on Windows. If no value is supplied, the operation will default to %PROGRAMFILES%\dotnet\dotnet.exe for Windows and dotnet (from the path) on Linux.

Example:

# Publish ~\src\MyProject.csproj with Release configuration for .net core 3.1, restoring NuGet packages from the InternalNuGet source
DotNet::Publish ~\src\MyProject.csproj
(
    Configuration: Release,
    Framework: netcoreapp3.1,
    Runtime: win-x64,
    PackageSource: InternalNuGet
);

dotnet test - Runs unit tests on a specified test project using the dotnet test command.

dotnet test

Runs unit tests on a specified test project using the dotnet test command.

Script usage:

DotNet::Test(
	Project: <text>,
	[Configuration: <text>],
	[PackageSource: <text>],
	[Group: <text>],
	[Framework: <text>],
	[AdditionalArguments: <text>],
	[DotNetPath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Project path	text	Project	This must be the path to either a project file, solution file, or a directory containing a project or solution file. This argument is required.
Configuration	text	Configuration
Package source	text	PackageSource	If specified, this NuGet package source will be used to restore packages when building.
Test group	text	Group
Framework	text	Framework
Additional arguments	text	AdditionalArguments
dotnet path	text	DotNetPath	Full path of dotnet.exe (or dotnet on Linux). This is usually C:\Program Files\dotnet\dotnet.exe on Windows. If no value is supplied, the operation will default to %PROGRAMFILES%\dotnet\dotnet.exe for Windows and dotnet (from the path) on Linux.

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
);

Get NuGet Dependencies - Inspects a .NET build project/packages.config to return the required versions of NuGet package dependencies.

Get NuGet Dependencies

Inspects a .NET build project/packages.config to return the required versions of NuGet package dependencies.

Script usage:

DotNet::Get-Dependencies(
	[ProjectPath: <text>],
	[PackageId: <text>],
	[Dependencies: <RuntimeValue>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Project path	text	ProjectPath
Package ID	text	PackageId
⇒ Dependencies	RuntimeValue	Dependencies	If PackageId is specified, the name of a text variable to receive the package version. If PackageId is not specified, the name of a map variable to received all dependency information.

Example:

# Store project dependencies in %depends map
DotNet::Get-Dependencies
(
    ProjectPath: ~\Src\MyProject,
    Dependencies => %depends
);

Run dotnet Tool - Runs a dotnet tool, optionally ensuring that it is installed.

Run dotnet Tool

Runs a dotnet tool, optionally ensuring that it is installed.

Script usage:

DotNet::Tool(
	Command: <text>,
	[Arguments: <text>],
	[Global: <true/false>],
	[PackageId: <text>],
	[Version: <text>],
	[PackageSource: <text>],
	[AdditionalArguments: <text>],
	[DotNetPath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Command (default)	text	Command	This argument is required.
Arguments	text	Arguments
Global tool	true/false	Global
Package ID	text	PackageId
Version	text	Version
Package source	text	PackageSource
Additional arguments	text	AdditionalArguments
dotnet path	text	DotNetPath	Full path of dotnet.exe (or dotnet on Linux). This is usually C:\Program Files\dotnet\dotnet.exe on Windows. If no value is supplied, the operation will default to %PROGRAMFILES%\dotnet\dotnet.exe for Windows and dotnet (from the path) on Linux.

Example:

# Install and run the latest version of dotnetsay locally
DotNet::Tool dotnetsay
(
    Arguments: Hello World!,
    PackageId: dotnetsay
);

Set Project Version - Sets the version elements in .NET project files to a specified value.

Set Project Version

Sets the version elements in .NET project files to a specified value.

Script usage:

DotNet::Set-ProjectVersion(
	[FromDirectory: <text>],
	Version: <text>,
	[Include: <@(text)>],
	[Exclude: <@(text)>],
	[AssemblyVersion: <text>],
	[FileVersion: <text>],
	[PackageVersion: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From directory	text	FromDirectory
☆ Version	text	Version	This argument is required.
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude
Assembly version	text	AssemblyVersion
File version	text	FileVersion
Package version	text	PackageVersion

Note: This operation is intended to be used when generating assembly info properties from a .NET project file. To set attributes in AssemblyInfo.cs, use DotNet::WriteAssemblyVersion.

Example:

# Build ~\src\MyProject.csproj with Release configuration, restoring NuGet packages from the InternalNuGet source
DotNet::SetProjectVersion
(
    Version: $ReleaseNumber,
    AssemblyVersion: $ReleaseNumber.0
    FileVersion: $ReleaseNumber.$BuildNumber
);

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:

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

Arguments:

Name	Format	Script Usage	Usage Notes
Assembly version	text	AssemblyVersion
File version	text	FileVersion
Informational version	text	InformationalVersion
From directory	text	FromDirectory
Include	@(text)	Include	See KB#1119 to learn more about masking syntax.
Exclude	@(text)	Exclude

Note: This operation is intended to be used when assembly version attributes are stored directly in AssemblyInfo.cs. To set these values in the project file instead, use DotNet::SetProjectVersion.

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>],
	[RenameFrom: <text>],
	[RenameTo: <text>],
	[RenameRegex: <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
Rename from	text	RenameFrom
Rename to	text	RenameTo
Use regular expression	true/false	RenameRegex

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	The text that replaces all occurrences of the search string found in matching files. If the Regex property is true, this property can replace matched group numbers as well, e.g. Example line: Version: 0.0.0-b05f2ad SearchText: Version: (\d+\.\d+\.\d+)(?<commitId>-\w+)? ReplaceWith: Version: $ReleaseNumber`${commitId} (was `$1) Example result: Version: 1.2.3-b05f2ad (was 0.0.0) Note the backtick characters (`) used to escape the $ in the replacement text, which otherwise would be interpreted as OtterScript variables.
Use regex	true/false	Regex	Determines whether the search text should be interpreted as .NET Regular Expression syntax.

Example:

# Replaces the product version in an example vdproj file with the BuildMaster release number
Create-File example.vdproj
(
	Text: >>"Product"
		{
			"ProductVersion" = "8:1.0.0"
		}>>
);

Replace-Text
(
	Include: **.vdproj,
	SearchText: '"ProductVersion" = "(?<1>[0-9]+)\:[0-9]+\.[0-9]+\.[0-9]+"',
	ReplaceWith: '"ProductVersion" = "`$1:$ReleaseNumber"',
	Regex: true
);

Log-Information `$FileContents = $FileContents(example.vdproj);  # "ProductVersion" = "8:1.2.3"

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

Firewall

Ensure Firewall Rule - Ensures the existence of a firewall rule on a Windows server.

Ensure Firewall Rule

Ensures the existence of a firewall rule on a Windows server.

Script usage:

Firewall::Ensure-NetFirewallRule(
	Name: <text>,
	Profiles: <text>,
	Port: <text>,
	Protocol: <text>,
	Inbound: <true/false>,
	Allow: <true/false>,
	[Exists: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Name	text	Name	This argument is required.
☆ Profiles	text	Profiles	Specify a comma separated list of profiles: "Public", "Private", and/or "Domain". (ex: "Public, Private") This argument is required.
☆ Port or Port Range	text	Port	Specify the port(s) affected by the firewall rule. Ports can be a comma separated list or a port range specified as "start-end" ex: 80-81,443 This argument is required.
☆ Protocol	text	Protocol	Specify if the protocol is "UDP" or "TCP" This argument is required.
☆ Inbound	true/false	Inbound	Specify if the connection is Inbound or Outbound. (Default = true) This argument is required.
☆ Allow	true/false	Allow	Select if you want to Allow or Block a connection. (Default = true) This argument is required.
Exists	true/false	Exists

Example:

# ensures that TCP ports 80 and 443 are allowed on "Domain" and Private profiles in Window's Firewall
Firewall::Ensure-NetFirewallRule(
    Name: OtterHttpTCP80443,
    Profiles: "Domain, Private",
    Port: "80,443",
    Protocol: TCP,
    Inbound: true,
    Allow: true
);


# ensures that UDP ports 5000 through 5004 and 5008 are allowed on the "Domain" profile Window's Firewall
Firewall::Ensure-NetFirewallRule(
    Name: OtterHttpUdpTest,
    Profiles: "Domain",
    Port: "5000-5004,5008",
    Protocol: UDP,
    Inbound: true,
    Allow: true
);

# ensures that the "OtterHttpTCP80443" Window's Firewall rule is removed
IIS::Ensure-Site(
    Name: OtterHttpTCP80443,
    Exists: false
);

General

Attach Package - Attaches a package to a build.

Attach Package

Attaches a package to a build.

Script usage:

Packages::Attach-Package(
	Name: <text>,
	[Version: <text>],
	[Source: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Package name	text	Name	This argument is required.
Version	text	Version
Package source	text	Source

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>],
	[IgnoreSslErrors: <true/false>]
);

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
Ignore SSL Errors	true/false	IgnoreSslErrors

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>],
	[ReportProgressRegex: <text>],
	[OutputFilterRegex: <text>]
);

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
Report progress regex	text	ReportProgressRegex	When set to a valid regular expression string, attempts to parse every output message for real-time progress updates. To capature a status message, use a group with name "m". To capture a percent complete as a number from 0 to 100, use a group with name "p".
Output filter regex	text	OutputFilterRegex	When set to a valid regular expression string, only output messages which match this expression will be logged.

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>],
	[SuccessExitCode: <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
☆ 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
Success exit code	text	SuccessExitCode	Integer exit code which indicates no error. When not specified, the exit code is ignored. This can also be an integer prefixed with an inequality operator.

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 script, 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>],
	[IgnoreSslErrors: <true/false>]
);

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
Ignore SSL Errors	true/false	IgnoreSslErrors

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>],
	[IgnoreSslErrors: <true/false>]
);

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
Ignore SSL Errors	true/false	IgnoreSslErrors

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>],
	[IgnoreSslErrors: <true/false>]
);

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
Ignore SSL Errors	true/false	IgnoreSslErrors

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>],
	[BindingProtocol: <text>],
	[BindingAddress: <text>],
	[BindingHostName: <text>],
	[BindingPort: <integer>],
	[BindingCertficiate: <text>],
	[BindingCertificateStoreLocation: <integer>],
	[BindingCertificateHash: <text>],
	[BindingRequireSNI: <true/false>],
	[BindingCertificateStore: <text>],
	[Binding: <text>],
	[Bindings: <@(%(key1: value1, ...))>],
	[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.
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
Binding	text	Binding
Multiple bindings (Legacy)	@(%(key1: value1, ...))	Bindings	This setting is no longer recommended; instead, use a separate operation to set multiple bindings. To enter multiple bindings, use 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))
Exists	true/false	Exists

Note: When creating a site, you must specify binding information.

Example:

# ensures that the FooBar web site is present on the web server, and binds the site to the single IP address 192.0.2.100  and hostname "foorbar.corp"
IIS::Ensure-Site(
    Name: FooBar,
    AppPool: FooBarAppPool,
    Path: E:\Websites\FooBar,
    BindingProtocol: http,
    BindingAddress: 192.0.2.100,
    BindingHostName: foobar.corp
);

# 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>,
	[From: <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.
From GitHub resource	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Use URL from Github resource.

Add Note to GitLab Issue - Adds a note to an issue on GitLab.

Add Note to GitLab Issue

Adds a note to an issue on GitLab.

Script usage:

GitLab::Create-IssueNote(
	IssueId: <integer>,
	Body: <text>,
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Namespace: <text>],
	[Project: <text>],
	[ApiUrl: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Issue ID	integer	IssueId	This argument is required.
☆ Body	text	Body	This argument is required.
From GitLab resource	text	From
User name	text	UserName
Password	SecureString	Password
Namespace	text	Namespace
Project name	text	Project
API URL	text	ApiUrl

Close GitHub Issue - Closes an issue on GitHub.

Close GitHub Issue

Closes an issue on GitHub.

Script usage:

GitHub::Close-Issue(
	Number: <integer>,
	[From: <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.
From GitHub resource	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Use URL from Github resource.

Close GitLab Issue - Closes an issue on GitLab.

Close GitLab Issue

Closes an issue on GitLab.

Script usage:

GitLab::Close-Issue(
	IssueId: <integer>,
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Namespace: <text>],
	[Project: <text>],
	[ApiUrl: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Issue ID	integer	IssueId	This argument is required.
From GitLab resource	text	From
User name	text	UserName
Password	SecureString	Password
Namespace	text	Namespace
Project name	text	Project
API URL	text	ApiUrl

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>],
	[From: <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
From GitHub resource	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Use URL from Github resource.

Create GitLab Issue - Creates an issue on a GitLab project.

Create GitLab Issue

Creates an issue on a GitLab project.

Script usage:

GitLab::Create-Issue(
	Title: <text>,
	[Description: <text>],
	[Labels: <@(text)>],
	[Assignees: <@(text)>],
	[Milestone: <text>],
	[AdditionalProperties: <%(key1: value1, ...)>],
	[IssueId: <integer>],
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Namespace: <text>],
	[Project: <text>],
	[ApiUrl: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Title	text	Title	This argument is required.
Description	text	Description
Labels	@(text)	Labels
Assignees	@(text)	Assignees
Milestone	text	Milestone
Additional properties	%(key1: value1, ...)	AdditionalProperties
⇒ Issue ID	integer	IssueId
From GitLab resource	text	From
User name	text	UserName
Password	SecureString	Password
Namespace	text	Namespace
Project name	text	Project
API URL	text	ApiUrl

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.";

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(
	[From: <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
From GitHub resource	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl
☆ Title	text	Title	This argument is required.
Due date	text	DueDate
Description	text	Description
State	integer	State

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

Ensure GitLab Milestone

Ensures a GitLab milestone exists with the specified properties.

Script usage:

GitLab::Ensure-Milestone(
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Namespace: <text>],
	[Project: <text>],
	[ApiUrl: <text>],
	Title: <text>,
	[StartDate: <text>],
	[DueDate: <text>],
	[Description: <text>],
	[State: <integer>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From GitLab resource	text	From
User name	text	UserName
Password	SecureString	Password
Namespace	text	Namespace
Project name	text	Project
API URL	text	ApiUrl
☆ Title	text	Title	This argument is required.
Start date	text	StartDate
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
);

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 NuGet package from a project or .nuspec file (requires Windows).

Create NuGet Package

Creates a NuGet package from a project or .nuspec file (requires Windows).

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 included nuget.exe will be used. This will only be used if dotnet is not available on a Windows server or PreferNuGetExe is set to true.
Additional arguments	text	Arguments	When specified, these arguments will be passed to NuGet.exe verbatim.

dotnet pack

Creates a NuGet package from a .net project using the dotnet pack command.

Script usage:

DotNet::Pack(
	Project: <text>,
	[Output: <text>],
	[Configuration: <text>],
	[IncludeSymbols: <true/false>],
	[IncludeSource: <true/false>],
	[ForceDependencyResolution: <true/false>],
	[Verbosity: <integer>],
	[AdditionalArguments: <text>],
	[DotNetPath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Project path	text	Project	This must be the path to either a project file, solution file, or a directory containing a project or solution file. This argument is required.
Output	text	Output	Specifies an output directory for the build. This is only valid if "Framework" is also specified.
Configuration	text	Configuration
Include symbols	true/false	IncludeSymbols
Include source	true/false	IncludeSource
Force dependency resolution	true/false	ForceDependencyResolution
Verbosity	integer	Verbosity
Additional arguments	text	AdditionalArguments
dotnet path	text	DotNetPath	Full path of dotnet.exe (or dotnet on Linux). This is usually C:\Program Files\dotnet\dotnet.exe on Windows. If no value is supplied, the operation will default to %PROGRAMFILES%\dotnet\dotnet.exe for Windows and dotnet (from the path) on Linux.

Note: This operation work on Windows and Linux as long as dotnet is installed.

Push NuGet Package

Publishes a NuGet package file to a NuGet package source.

Script usage:

NuGet::Push-Package(
	FilePath: <text>,
	[To: <text>],
	[FeedUrl: <text>],
	[UserName: <text>],
	[Password: <text>],
	[ApiKey: <text>],
	[NuGetExePath: <text>],
	[PreferNuGetExe: <true/false>],
	[AdditionalArguments: <text>],
	[DotNetPath: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Path to .nupkg package file name (default)	text	FilePath	This argument is required.
Package source	text	To
NuGet server URL	text	FeedUrl
User name	text	UserName
Password	text	Password
NuGet API Key	text	ApiKey
NuGet.exe path	text	NuGetExePath	Full path to NuGet.exe on the target server. When not set, the included nuget.exe will be used. This will only be used if dotnet is not available on a Windows server or PreferNuGetExe is set to true.
Prefer NuGet.exe	true/false	PreferNuGetExe	When true, NuGet.exe will be used when run on Windows if it is available, even if dotnet is also available.
Additional arguments	text	AdditionalArguments
dotnet path	text	DotNetPath	Full path of dotnet.exe (or dotnet on Linux). This is usually C:\Program Files\dotnet\dotnet.exe on Windows. If no value is supplied, the operation will default to %PROGRAMFILES%\dotnet\dotnet.exe for Windows and dotnet (from the path) on Linux.

Note: When Username/Password are specified, it will be passed as "Username:Password" via the API Key.

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>],
	[SourceName: <text>],
	[NuGetExePath: <text>],
	[PreferNuGetExe: <true/false>],
	[AdditionalArguments: <text>],
	[DotNetPath: <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
Source URL	text	Source
Package source	text	SourceName
NuGet.exe path	text	NuGetExePath	Full path to NuGet.exe on the target server. When not set, the included nuget.exe will be used. This will only be used if dotnet is not available on a Windows server or PreferNuGetExe is set to true.
Prefer NuGet.exe	true/false	PreferNuGetExe	When true, NuGet.exe will be used when run on Windows if it is available, even if dotnet is also available.
Additional arguments	text	AdditionalArguments
dotnet path	text	DotNetPath	Full path of dotnet.exe (or dotnet on Linux). This is usually C:\Program Files\dotnet\dotnet.exe on Windows. If no value is supplied, the operation will default to %PROGRAMFILES%\dotnet\dotnet.exe for Windows and dotnet (from the path) on Linux.

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)
);

Ensure PowerShell Module - Ensures that the specified PowerShell module is installed.

Ensure PowerShell Module

Ensures that the specified PowerShell module is installed.

Script usage:

Ensure-PsModule(
	Module: <text>,
	[Version: <text>],
	[MinimumVersion: <text>],
	[Force: <true/false>],
	[Repository: <text>],
	[Scope: <text>],
	[Exists: <true/false>],
	[AllowClobber: <true/false>],
	[AllowPrerelease: <true/false>],
	[AcceptLicense: <true/false>],
	[AllVersions: <true/false>],
	[Parameters: <%(key1: value1, ...)>],
	[Verbose: <true/false>],
	[DebugLogging: <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
☆ Module	text	Module	This argument is required.
Version	text	Version
Minimum Version	text	MinimumVersion
Force	true/false	Force	Use this to force installation to bypass the Untrusted Repository error or to force this version to install side-by-side with other versions that already exist.
Repository Name	text	Repository
Scope	text	Scope	Typically "Local" or "Global"
Exists	true/false	Exists
Allow Clobber	true/false	AllowClobber
Allow Prerelease	true/false	AllowPrerelease
Accept License	true/false	AcceptLicense	For PowerShell Core only!
All Versions	true/false	AllVersions
Parameters	%(key1: value1, ...)	Parameters	Additional parameters to pass to Install-Module. Example: %(DestinationPath: C:\hdars\1000.txt, Contents: test file ensured)
Verbose	true/false	Verbose
Debug Logging	true/false	DebugLogging

Example:

# ensures the existence of a module on the server
Ensure-PsModule
(
    Module: PackageManagement,
    MinimumVersion: 1.4.6,
    Repository: internal-powershell,
    Exists: true
);

# ensures the existence of a specific version of a module on the server
Ensure-PsModule
(
    Module: PackageManagement,
    Version: 1.4.6,
    Repository: internal-powershell,
    Force: true,
    Exists: true
);

Ensure PowerShell Repository - Ensures that the specified PowerShell Repository is registered.

Ensure PowerShell Repository

Ensures that the specified PowerShell Repository is registered.

Script usage:

Ensure-PsRepository(
	Name: <text>,
	SourceLocation: <text>,
	[InstallationPolicy: <text>],
	[Exists: <true/false>],
	[PackageManagementProvider: <text>],
	[Parameters: <%(key1: value1, ...)>],
	[Verbose: <true/false>],
	[DebugLogging: <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
☆ Name	text	Name	This argument is required.
☆ Source Location	text	SourceLocation	This argument is required.
Installation Policy	text	InstallationPolicy	Use "Trusted" or "Untrusted"
Exists	true/false	Exists
Package Management Provider	text	PackageManagementProvider
Parameters	%(key1: value1, ...)	Parameters	Additional parameters to pass to Install-Module. Example: %(DestinationPath: C:\hdars\1000.txt, Contents: test file ensured)
Verbose	true/false	Verbose
Debug Logging	true/false	DebugLogging

Example:

# ensures the existence of a repository on the server
Ensure-PsRepository(
  Name: internal-powershell,
  SourceLocation: https://proget/nuget/internal-powershell/,
  InstallationPolicy: Trusted
  Exists: 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 - Calls a PowerShell Ensure Script that is stored as an asset.

PSEnsure

Calls a PowerShell Ensure Script that is stored as an asset.

Script usage:

PSEnsure [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.

Example:

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

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

PSEnsure using Scripts

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

Script usage:

PSEnsureScripts(
	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>],
	[SuccessExitCode: <text>]
);

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.
Success exit code	text	SuccessExitCode	Integer exit code which indicates no error. The default is empty, treating all exit codes as success. This can also be an integer prefixed with an inequality operator.

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);

PSVerify - Uses a PowerShell script to collect configuration about a server.
PSVerify

Uses a PowerShell script to collect configuration about a server.

Script usage:
```
PSVerify [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.

ProGet

Create Universal Package - Creates a universal package from the specified directory and publishes to a feed.

Create Universal Package

Creates a universal package from the specified directory and publishes to a feed.

Script usage:

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

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Package name	text	Name	This argument is required.
☆ Package version	text	Version	This argument is required.
Source directory	text	From
To package source	text	PushTo
Package file name	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.
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.
Additional metadata	%(key1: value1, ...)	Metadata	Additional properties may be specified using map syntax. For example: %(description: my package description)
Overwrite existing package	true/false	Overwrite
Feed name	text	Feed
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.
ProGet API Key	text	ApiKey	An API Key that can access this feed.
Group	text	Group

Example:

ProGet::Create-Package
(
    Name: MyAppPackage,
    Version: 3.4.2,

    From :$WorkingDirectory,
    PushTo: MyPackageSource    
);

Ensure Universal Package Installed - Ensures that the specified universal package is installed in the specified directory.

Ensure Universal Package Installed

Ensures that the specified universal package is installed in the specified directory.

Script usage:

ProGet::Ensure-Package(
	[From: <text>],
	Name: <text>,
	[Version: <text>],
	To: <text>,
	Exists: <true/false>,
	[LocalRegistry: <integer>],
	[LocalCache: <true/false>],
	[FileCompare: <integer>],
	[Ignore: <@(text)>],
	[DirectDownload: <true/false>],
	[Feed: <text>],
	[FeedUrl: <text>],
	[UserName: <text>],
	[Password: <text>],
	[ApiKey: <text>],
	[DeleteExtra: <true/false>],
	[Include: <@(text)>],
	[Exclude: <@(text)>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Package source	text	From
☆ Package name	text	Name	This argument is required.
Package version	text	Version
☆ Target directory	text	To	The directory path on disk of the package contents. This argument is required.
☆ Exists	true/false	Exists	This argument is required.
Use Local Registry	integer	LocalRegistry
LocalCache	true/false	LocalCache	Cache Package
Compare files	integer	FileCompare
Ignore	@(text)	Ignore	See KB#1119 to learn more about masking syntax.
Direct download	true/false	DirectDownload	Set this to value to false if your remote server doesn't have direct access to the ProGet feed.
Feed name	text	Feed
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.
ProGet API Key	text	ApiKey	An API Key that can access this feed.
DeleteExtra	true/false	DeleteExtra
Include	@(text)	Include
Exclude	@(text)	Exclude

Note: To determine if a package is installed, the local package registry and package files are both checked. You can control these with LocalRegistry and FileCompare options.

Example:

#Ensure that FooBarApp is Installed
ProGet::Ensure-Package
(
    From: MyPackageSource,
    Name: FooBarApp,
    Version: $FooBarVersion,
    To: D:\WebApps\FooBar.App,
    Ignore: web.config
);

Install Universal Package - Installs a universal package to the specified location using a Package Source.

Install Universal Package

Installs a universal package to the specified location using a Package Source.

Script usage:

ProGet::Install-Package(
	[From: <text>],
	Name: <text>,
	[Version: <text>],
	[To: <text>],
	[LocalRegistry: <integer>],
	[LocalCache: <true/false>],
	[DirectDownload: <true/false>],
	[Feed: <text>],
	[FeedUrl: <text>],
	[UserName: <text>],
	[Password: <text>],
	[ApiKey: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Package source	text	From
☆ Package name	text	Name	This argument is required.
Package version	text	Version
Target directory	text	To
Use Local Registry	integer	LocalRegistry
LocalCache	true/false	LocalCache	Cache Package
Direct download	true/false	DirectDownload	Set this to value to false if your remote server doesn't have direct access to the ProGet feed.
Feed name	text	Feed
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.
ProGet API Key	text	ApiKey	An API Key that can access this feed.

Example:

ProGet::Install-Package
(
    From: MyPackageSource,
    Name: MyAppPackage,
    Version: 3.4.2,

    To: C:\MyApps\MyApp
);

Promote Package - Promotes a package from one feed to another in a ProGet instance.

Promote Package

Promotes a package from one feed to another in a ProGet instance.

Script usage:

ProGet::Promote-Package(
	[From: <text>],
	Name: <text>,
	Version: <text>,
	[ToFeed: <text>],
	[Reason: <text>],
	[To: <text>],
	[Feed: <text>],
	[FeedUrl: <text>],
	[UserName: <text>],
	[Password: <text>],
	[ApiKey: <text>],
	[Group: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Package source	text	From
☆ Package name	text	Name	This argument is required.
☆ Package version	text	Version	This argument is required.
Promote to Feed	text	ToFeed
Reason	text	Reason
To source	text	To
Feed name	text	Feed
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.
ProGet API Key	text	ApiKey	An API Key that can access this feed.
Group	text	Group

Push Universal Package File - Uploads a universal package file to a package source.

Push Universal Package File

Uploads a universal package file to a package source.

Script usage:

ProGet::Push-PackageFile(
	FilePath: <text>,
	[To: <text>],
	[Feed: <text>],
	[FeedUrl: <text>],
	[UserName: <text>],
	[Password: <text>],
	[ApiKey: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Package file path (default)	text	FilePath	This argument is required.
Package source	text	To
Feed name	text	Feed
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.
ProGet API Key	text	ApiKey	An API Key that can access this feed.

Example:

# Uploads the MyPackage.1.0.0.upack file to the InternalFeed package source
ProGet::Push-PackageFile MyPackage.1.0.0.upack
(
    PackageSource: InternalFeed
);

Repackage Package - Uses ProGet's Repackaging feature to Creates a new package with an altered version number to a ProGet feed and adds a repackaging entry to its metadata for auditing.

Repackage Package

Uses ProGet's Repackaging feature to Creates a new package with an altered version number to a ProGet feed and adds a repackaging entry to its metadata for auditing.

Script usage:

ProGet::Repack-Package(
	[From: <text>],
	Name: <text>,
	[Version: <text>],
	NewVersion: <text>,
	[Reason: <text>],
	[Feed: <text>],
	[FeedUrl: <text>],
	[UserName: <text>],
	[Password: <text>],
	[ApiKey: <text>],
	[Group: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Package source	text	From
☆ Package name	text	Name	This argument is required.
Package version	text	Version
☆ New version	text	NewVersion	This argument is required.
Reason	text	Reason
Feed name	text	Feed
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.
ProGet API Key	text	ApiKey	An API Key that can access this feed.
Group	text	Group

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
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

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(
	[From: <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
From GitHub resource	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl
☆ 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

Ensure GitLab Release - Sets the release notes for a tag in a GitLab repository.

Ensure GitLab Release

Sets the release notes for a tag in a GitLab repository.

Script usage:

GitLab::Ensure-TagReleaseNotes(
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Namespace: <text>],
	[Project: <text>],
	[ApiUrl: <text>],
	Tag: <text>,
	[Description: <text>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From GitLab resource	text	From
User name	text	UserName
Password	SecureString	Password
Namespace	text	Namespace
Project name	text	Project
API URL	text	ApiUrl
☆ Tag name	text	Tag	The tag must already exist. This argument is required.
Description	text	Description	Release notes, formatted using Markdown.

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(
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[RepositoryUrl: <text>],
	[DiskPath: <text>],
	[Branch: <text>],
	[Ref: <text>],
	[CommitHash: <text>],
	[PreserveLastModified: <true/false>],
	[KeepInternals: <true/false>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From Git resource (default)	text	From
User name	text	UserName
Password	SecureString	Password
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.
Preserve Last Modified Date	true/false	PreserveLastModified	By default, Git will not set the Last Modified date of files when checking out. Selecting this option may take additional time, depending on the number of files in the repository.
Copy internal Git files	true/false	KeepInternals	When exporting the repository, also export .git* files.
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 git resource and archives/exports the contents to the $WorkingDirectory
Git::Get-Source MyGitResource;

# pulls source from a remote repository and archives/exports the contents to a target directory
Git::Get-Source
(
    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(
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>],
	[DiskPath: <text>],
	[Branch: <text>],
	[Ref: <text>],
	[CommitHash: <text>],
	[PreserveLastModified: <true/false>],
	[KeepInternals: <true/false>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From GitHub resource (default)	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Use URL from Github resource.
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.
Preserve Last Modified Date	true/false	PreserveLastModified	By default, Git will not set the Last Modified date of files when checking out. Selecting this option may take additional time, depending on the number of files in the repository.
Copy internal Git files	true/false	KeepInternals	When exporting the repository, also export .git* files.
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 GitHub resource and archives/exports the contents to the $WorkingDirectory
GitHub::Get-Source MyGitHubResource;

# pulls source from a GitHub resource (with an overridden repository) and archives/exports the contents to a target directory
GitHub::Get-Source MyGitHubResource
(
    Repository: app-$ApplicationName,
    DiskPath: ~\Sources
);

Get Source from GitLab Repository - Gets the source code from a GitLab project.

Get Source from GitLab Repository

Gets the source code from a GitLab project.

Script usage:

GitLab::Get-Source(
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Namespace: <text>],
	[Project: <text>],
	[ApiUrl: <text>],
	[DiskPath: <text>],
	[Branch: <text>],
	[Ref: <text>],
	[CommitHash: <text>],
	[PreserveLastModified: <true/false>],
	[KeepInternals: <true/false>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From GitLab resource (default)	text	From
User name	text	UserName
Password	SecureString	Password
Namespace	text	Namespace
Project name	text	Project
API URL	text	ApiUrl
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.
Preserve Last Modified Date	true/false	PreserveLastModified	By default, Git will not set the Last Modified date of files when checking out. Selecting this option may take additional time, depending on the number of files in the repository.
Copy internal Git files	true/false	KeepInternals	When exporting the repository, also export .git* files.
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 GitLab resource and archives/exports the contents to the $WorkingDirectory
GitLab::Get-Source MyGitLabResource;

# pulls source from a GitLab resource (with an overridden project name) and archives/exports the contents to a target directory
GitLab::Get-Source MyGitLabResource
(
    Project: app-$ApplicationName,
    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>],
	[From: <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
From GitHub resource	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Use URL from Github resource.

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 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(
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[RepositoryUrl: <text>],
	Tag: <text>,
	[Message: <text>],
	[Branch: <text>],
	[CommitHash: <text>],
	[Force: <true/false>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From Git resource (default)	text	From
User name	text	UserName
Password	SecureString	Password
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.
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 build number
Git::Tag Hdars-Git 
(
    Tag: $ReleaseName.$BuildNumber
);

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(
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Organization: <text>],
	[Repository: <text>],
	[ApiUrl: <text>],
	Tag: <text>,
	[Message: <text>],
	[Branch: <text>],
	[CommitHash: <text>],
	[Force: <true/false>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From GitHub resource	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Use URL from Github resource.
☆ 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.
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
);

Tag GitLab Source - Tags the source code in a GitLab project.

Tag GitLab Source

Tags the source code in a GitLab project.

Script usage:

GitLab::Tag(
	[From: <text>],
	[UserName: <text>],
	[Password: <SecureString>],
	[Namespace: <text>],
	[Project: <text>],
	[ApiUrl: <text>],
	Tag: <text>,
	[Message: <text>],
	[Branch: <text>],
	[CommitHash: <text>],
	[Force: <true/false>],
	[GitExePath: <text>],
	[RecurseSubmodules: <true/false>],
	[WorkspaceDiskPath: <text>],
	[CleanWorkspace: <true/false>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
From GitLab resource	text	From
User name	text	UserName
Password	SecureString	Password
Namespace	text	Namespace
Project name	text	Project
API URL	text	ApiUrl
☆ 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.
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
GitLab::Tag(
    Credentials: Hdars-GitLab,
    Group: Hdars,
    Tag: $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>],
	[From: <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.
From GitHub resource	text	From
User name	text	UserName
Password	SecureString	Password
Organization name	text	Organization
Repository name	text	Repository
API URL	text	ApiUrl	Use URL from Github resource.

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(
	[From: <text>],
	Name: <text>,
	Version: <text>,
	NewVersion: <text>,
	[Reason: <text>],
	[PackageFile: <text>],
	[Feed: <text>],
	[FeedUrl: <text>],
	[UserName: <text>],
	[Password: <text>],
	[ApiKey: <text>],
	[Exists: <true/false>],
	[Metadata: <%(key1: value1, ...)>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Package source	text	From
☆ Package name	text	Name	This argument is required.
☆ Package version	text	Version	This argument is required.
☆ New version	text	NewVersion	This argument is required.
Reason	text	Reason
Package file	text	PackageFile	When specified, FeedUrl, UserName, Password, PackageName, and PackageVersion are ignored.
Feed name	text	Feed
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.
ProGet API Key	text	ApiKey	An API Key that can access this feed.
⇒ 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

Youtrack

Add Comment to YouTrack Issue - Adds a comment to a YouTrack issue.

Add Comment to YouTrack Issue

Adds a comment to a YouTrack issue.

Script usage:

YouTrack::Add-Comment(
	[Query: <text>],
	[Issues: <@(text)>],
	Comment: <text>,
	[From: <text>],
	[Server: <text>],
	[CredentialName: <text>],
	[PermanentToken: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Query	text	Query	The YouTrack issue query. For example, to get open issues for the release currently in context: `Project: {$ApplicationName} Fix version: $ReleaseNumber State: -Completed` For more information on filters, see: https://www.jetbrains.com/help/youtrack/standalone/Search-and-Command-Attributes.html
Issue IDs	@(text)	Issues	Apply to the issue IDs directly. When this value is specified, "Query" is ignored.
☆ Comment	text	Comment	This argument is required.
From resource	text	From
YouTrack server URL	text	Server
Credentials	text	CredentialName
Permanent token	SecureString	PermanentToken

Example:

# Add a comment to issues in the current release of the current project.
YouTrack::Add-Comment
(
    Query: Project: {$ApplicationName} Fix version: $ReleaseNumber,
    Comment: Comment added by BuildMaster in build $BuildNumber of release $ReleaseNumber of $ApplicationName.
);

Change YouTrack Issue States - Changes the state of YouTrack issues.

Change YouTrack Issue States

Changes the state of YouTrack issues.

Script usage:

YouTrack::Change-IssueStates(
	[Query: <text>],
	[Issues: <@(text)>],
	State: <text>,
	[Comment: <text>],
	[IssueStatusFieldName: <text>],
	[From: <text>],
	[Server: <text>],
	[CredentialName: <text>],
	[PermanentToken: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Query	text	Query	The YouTrack issue query. For example, to get open issues for the release currently in context: `Project: {$ApplicationName} Fix version: $ReleaseNumber State: -Completed` For more information on filters, see: https://www.jetbrains.com/help/youtrack/standalone/Search-and-Command-Attributes.html
Issue IDs	@(text)	Issues	Apply to the issue IDs directly. When this value is specified, "Query" is ignored.
☆ State	text	State	This argument is required.
Comment	text	Comment
Issue status custom field	text	IssueStatusFieldName
From resource	text	From
YouTrack server URL	text	Server
Credentials	text	CredentialName
Permanent token	SecureString	PermanentToken

Example:

# Change the state of all issues in the application's project with 'Fix version' = $ReleaseNumber to Completed.
YouTrack::ChangeIssueStates
(
    Query: Project: {$ApplicationName} Fix version: $ReleaseNumber,
    State: Completed
);

Create YouTrack Issue - Creates a new issue in YouTrack.

Create YouTrack Issue

Creates a new issue in YouTrack.

Script usage:

YouTrack::Create-Issue(
	Project: <text>,
	Summary: <text>,
	[Description: <text>],
	[IssueId: <text>],
	[From: <text>],
	[Server: <text>],
	[CredentialName: <text>],
	[PermanentToken: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Project	text	Project	This argument is required.
☆ Summary	text	Summary	This argument is required.
Description	text	Description
⇒ Issue ID	text	IssueId
From resource	text	From
YouTrack server URL	text	Server
Credentials	text	CredentialName
Permanent token	SecureString	PermanentToken

Example:

# Creates an example issue in the $ApplicationName YouTrack project and stores its issue ID in the $issueId variable.
YouTrack::Create-Issue
(
    Project: $ApplicationName,
    Summary: Example issue,
    Description: >>This issue was created by BuildMaster.
It is just an example.>>,
    IssueId => $issueId
);

# Write the issue ID to the execution log.
Log-Information Created issue $issueId in YouTrack.;

Ensure YouTrack Version - Ensures that a version exists for a YouTrack project and optionally updates its released and archived states.

Ensure YouTrack Version

Ensures that a version exists for a YouTrack project and optionally updates its released and archived states.

Script usage:

YouTrack::Ensure-Version(
	Project: <text>,
	Version: <text>,
	[Released: <true/false>],
	[Archived: <true/false>],
	[VersionFieldName: <text>],
	[From: <text>],
	[Server: <text>],
	[CredentialName: <text>],
	[PermanentToken: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
☆ Project	text	Project	This argument is required.
☆ Version (default)	text	Version	This argument is required.
Released	true/false	Released
Archived	true/false	Archived
Version custom field	text	VersionFieldName
From resource	text	From
YouTrack server URL	text	Server
Credentials	text	CredentialName
Permanent token	SecureString	PermanentToken

Example:

# Ensure that a version exists in YouTrack for the current release of the current application.
YouTrack::Ensure-Version
(
    Project: $ApplicationName,
    Version: $ReleaseNumber
);

Query YouTrack Issues - Queries YouTrack for issues and stores information about them in an OtterScript variable.

Query YouTrack Issues

Queries YouTrack for issues and stores information about them in an OtterScript variable.

Script usage:

YouTrack::Query-Issues(
	[Project: <text>],
	[Query: <text>],
	[Output: <RuntimeValue>],
	[IncludeDetails: <true/false>],
	[IssueStatusFieldName: <text>],
	[IssueTypeFieldName: <text>],
	[From: <text>],
	[Server: <text>],
	[CredentialName: <text>],
	[PermanentToken: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Project	text	Project
Query	text	Query	The YouTrack issue query. For example, to get open issues for the release currently in context: `Project: {$ApplicationName} Fix version: $ReleaseNumber State: -Completed` For more information on filters, see: https://www.jetbrains.com/help/youtrack/standalone/Search-and-Command-Attributes.html
⇒ Output variable	RuntimeValue	Output	The output variable should be a list variable. For example: @YouTrackIssueIDs
Include details in output	true/false	IncludeDetails	When true, the output variable is a list of maps with id, title, and description properties. When false, the output variable is a list of id strings.
Issue status custom field	text	IssueStatusFieldName
Issue type custom field	text	IssueTypeFieldName
From resource	text	From
YouTrack server URL	text	Server
Credentials	text	CredentialName
Permanent token	SecureString	PermanentToken

Example:

# Queries YouTrack for open issues with 'Fix version' = $ReleaseNumber for the $ApplicationName project and stores the issue IDs in the @issueIds variable.
YouTrack::Query-Issues
(
    Query: Project: {$ApplicationName} Fix version: $ReleaseNumber State: Open,
    Output => @issueIds
);

Run YouTrack Command - Runs a YouTrack command against one or more issues.

Run YouTrack Command

Runs a YouTrack command against one or more issues.

Script usage:

YouTrack::Run-Command(
	[Query: <text>],
	[Issues: <@(text)>],
	Command: <text>,
	[Comment: <text>],
	[From: <text>],
	[Server: <text>],
	[CredentialName: <text>],
	[PermanentToken: <SecureString>]
);

Arguments:

Name	Format	Script Usage	Usage Notes
Query	text	Query	The YouTrack issue query. For example, to get open issues for the release currently in context: `Project: {$ApplicationName} Fix version: $ReleaseNumber State: -Completed` For more information on filters, see: https://www.jetbrains.com/help/youtrack/standalone/Search-and-Command-Attributes.html
Issue IDs	@(text)	Issues	Apply to the issue IDs directly. When this value is specified, "Query" is ignored.
☆ Command	text	Command	This argument is required.
Comment	text	Comment
From resource	text	From
YouTrack server URL	text	Server
Credentials	text	CredentialName
Permanent token	SecureString	PermanentToken

Example:

# Applies the 'my-tag' tag to issues matching the specified query.
YouTrack::Run-Command
(
    Query: Project: {$ApplicationName} Fix version: $ReleaseNumber,
    Command: tag my-tag
);

Operations

Amazon

Upload Files to S3

Script usage:

Arguments:

Artifacts

Create Artifact

Script usage:

Arguments:

Deploy Artifact

Script usage:

Arguments:

BuildMaster

Backup Application

Script usage:

Arguments:

Create Build

Script usage:

Arguments:

Example:

Create Release

Script usage:

Arguments:

Example:

Create Release Note

Script usage:

Arguments:

Example:

Deploy Build

Script usage:

Arguments:

Ensure Release

Script usage:

Arguments:

Example:

Invoke Module

Script usage:

Arguments:

Example:

Invoke OtterScript

Script usage:

Arguments:

Example:

Invoke Script

Script usage:

Arguments:

Example:

Manual Operation

Script usage:

Arguments:

Reject Build

Script usage:

Arguments:

Example:

Set Build Number

Script usage:

Arguments:

Example:

Set Build Variable

Script usage:

Arguments:

Set Configuration Variable

Script usage:

Arguments:

Set Release Variable

Script usage:

Arguments:

Configuration Files

Deploy Configuration File

Script usage:

Arguments:

See also:

Export Configuration File

Script usage:

Arguments:

Databases

Backup Database

Script usage:

Arguments:

Build Database Updater Executable