PowerShell API

The PowerShell API of Bench consists of a set of global variables and functions, available in custom and hook scripts.

Variables

• $BenchConfig

Utility Functions

• Exit-OnError
• Pause
• Run-Detached

File System Functions

• Empty-Dir
• Find-File
• Find-Files
• Purge-Dir
• Safe-Dir

Bench Configuration Functions

• Get-ConfigValue
• Get-ConfigBooleanValue
• Get-ConfigListValue

App Property Functions

• Get-AppConfigValue
• Get-AppConfigBooleanValue
• Get-AppConfigListValue
• App-Typ
• App-Version
• App-Dependencies
• App-Url
• App-DownloadHeaders
• App-DownloadCookies
• App-ResourceFile
• App-ResourceArchive
• App-ResourceArchiveTyp
• App-ResourceArchivePath
• App-Force
• App-PackageName
• App-Dir
• App-Path
• App-Paths
• App-Exe
• App-Register
• App-Environment
• App-AdornedExecutables
• App-RegistryKeys
• App-Launcher
• App-LauncherExecutable
• App-LauncherArguments
• App-LauncherIcon
• App-SetupTestFile
• Check-App
• App-CustomScriptFile
• App-SetupResource

Variables

$BenchConfig

This variable in the global scope a Mastersign.Bench.BenchConfiguration object. This object holds the merged Bench configuration from all configuration files.

Hint: Access via $global:BenchConfig.

Utility Functions

Exit-OnError

• Description: Checks an process exit code and exits the current script if it is not 0.
• Parameter:
  • exitCode (optional) The exit code to check. Default value is $LastExitCode.

Pause

• Description: Prints a message and waits for an arbitrary key press before it returns.
• Parameter:
  • msg (optional) The message to print. Default value is "Press any key to exit ...".

Run-Detached

• Description: Starts a detached process without blocking.
• Parameter:
  • path The absolute path to the executable.
  • … An arbitrary number of command line arguments

File System Functions

Empty-Dir

• Description: Makes sure a path points to an empty directory.
• Parameter:
  • path The absolute path to the directory.
• Return Value: The absolute path to the directory.

If the directory exists, all of its children are deleted. If the directory does not exist, it is created.

This function is a wrapper for Mastersign.Bench.FileSystem.EmptyDir().

Find-File

• Description: Searches for the first file that matches a given pattern, in a given directory.
• Parameter:
  • dir The absolute path to a directory.
  • pattern The pattern to search for, syntax according to System.IO.Directory.GetFiles().
• Return Value: The absolute path of the found file or $null, if the given directory does not exist or no file matches.

If more than one file in the given directory matches the pattern, it is not defined which one is returned.

Find-Files

• Description: Searches for files which match a given pattern, in a given directory.
• Parameter:
  • dir The absolute path to a directory.
  • pattern The pattern to search for, syntax according to System.IO.Directory.GetFiles().
• Return Value: An array with the found files.

If the specified directory does not exist, an empty array is returned.

Purge-Dir

• Description: Deletes a directory and all of its content.
• Parameter:
  • path The absolute path to the directory.

Solves a problem with deleting directories recursively, if they contain read-only files. This function is a wrapper for Mastersign.Bench.FileSystem.PurgeDir().

Safe-Dir

• Description: Makes sure a directory exists.
• Parameter:
  • path The absolute path to the directory.
• Return Value: The absolute path to the directory.

This method is a wrapper for Mastersign.Bench.FileSystem.AsureDir().

Bench Configuration Functions

Get-ConfigValue

• Description: Returns the value of a Bench configuration property.
• Parameter:
  • name The name of the configuration property.
• Return Value: The value of the property or $null.

The data type of the property can be string, boolean, array of strings, or dictionary with string keys and values. If you want to read a boolean value use Get-ConfigBooleanValue, because strings can be interpreted as booleans. If you want to read a list value use Get-ConfigListValue, because strings can be interpreted as an array with one element.

Get-ConfigBooleanValue

• Description: Returns the boolean value of a Bench configuration property.
• Parameter:
  • name The name of the configuration property.
• Return Value: The value of the property as boolean.

If the property has no value, $false is returned.

Get-ConfigListValue

• Description: Returns the list value of a Bench configuration property.
• Parameter:
  • name The name of the configuration property.
• Return Value: The value of the property as array of strings.

If the property only contains a string, an array with one element is returned. If the property has no value, an empty array is returned.

App Property Functions

Get-AppConfigValue

• Description: Returns the value of an Bench app property.
• Parameter:
  • app The ID of an app.
  • name The name of the property.
• Return Value: The value of the property as string or $null.

If the property has no value, or the app ID is not defined, $null is returned. If you want to read a boolean value use Get-AppConfigBooleanValue, because strings can be interpreted as booleans. If you want to read a list value use Get-AppConfigListValue, because strings can be interpreted as an array with one element.

Get-AppConfigBooleanValue

• Description: Returns the boolean value of an Bench app property.
• Parameter:
  • app The ID of an app.
  • name The name of the property.
• Return Value: The value of the property as boolean.

If the property has no value, $false is returned. If the app ID is not defined, $null is returned.

Get-AppConfigListValue

• Description: Returns the list value of an Bench app property.
• app The ID of an app.
• name The name of the property.
• Return Value: The value of the property as boolean.

If the property only contains a string, an array with one element is returned. If the property has no value, an empty array is returned. If the app ID is not defined, $null is returned.

App-Typ

• Description: This function returns the value of the Typ property.
• Parameter:
  • app: The app ID.
• Return Value: The string value of the property, or $null in case the app ID is not defined.

App-Version

• Description: This function returns the value of the Version property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-Dependencies

• Description: This function returns the list value of the Dependencies property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as array of strings, or $null in case the app ID is not defined.

App-Url

• Description: This function returns the value of the Url property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-DownloadHeaders

• Description: This function returns the dictionary value of the DownloadHeaders property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as dictionary, or $null in case the app ID is not defined.

App-DownloadCookies

• Description: This function returns the dictionary value of the DownloadCookies property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as dictionary, or $null in case the app ID is not defined.

App-ResourceFile

• Description: This function returns the string value of the ResourceName property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-ResourceArchive

• Description: This function returns the string value of the ArchiveName property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-ResourceArchiveTyp

• Description: This function returns the string value of the ResourceArchiveTyp property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-ResourceArchivePath

• Description: This function returns the string value of the ArchivePath property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-Force

• Description: This function returns the boolean value of the Force property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as boolean, or $null in case the app ID is not defined.

App-PackageName

• Description: This function returns the string value of the PackageName property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-Dir

• Description: This function returns the string value of the Dir property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-Path

• Description: This function returns the first element in the list value of the Path property.
• Parameter:
  • app: The app ID.
• Return Value: The first item in the array value of the property as string, or $null in case the app ID is not defined.

App-Paths

• Description: This function returns the list value of the Path property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as array of strings, or $null in case the app ID is not defined.

App-Exe

• Description: This function returns the string value of the Exe property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-Register

• Description: This function returns the boolean value of the Register property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as boolean, or $null in case the app ID is not defined.

App-Environment

• Description: This function returns the dictionary value of the Environment property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as dictionary, or $null in case the app ID is not defined.

App-AdornedExecutables

• Description: This function returns the list value of the AdornedExecutables property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as array of strings, or $null in case the app ID is not defined.

App-RegistryKeys

• Description: This function returns the list value of the RegistryKeys property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as array of strings, or $null in case the app ID is not defined.

App-Launcher

• Description: This function returns the string value of the Launcher property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-LauncherExecutable

• Description: This function returns the string value of the LauncherExecutable property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-LauncherArguments

• Description: This function returns the list value of the LauncherArguments property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as array of strings, or $null in case the app ID is not defined.

App-LauncherIcon

• Description: This function returns the string value of the LauncherIcon property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

App-SetupTestFile

• Description: This function returns the string value of the SetupTestFile property.
• Parameter:
  • app: The app ID.
• Return Value: The value of the property as string, or $null in case the app ID is not defined.

Check-App

• Description: This function returns a boolean value, indicating if this app is installed.
• Parameter:
  • app: The app ID.
• Return Value: $true if the app is installed, $false if the app is not installed, and $null if the app ID is not defined.

App-CustomScriptFile

• Description: This function retrieves a path to a custom script.
• Parameter:
  • app: The app ID.
  • type: The type of cstom script (e.g. setup or env).
• Return Value: An absolute path to the custom script or $null if this type of custom script does not exists for the specified app.

App-SetupResource

• Description: This function retrieves a path to a setup resource for an app.
• Parameter:
  • app: The app ID.
  • relativePath: A relative path or simply the filename of the resource.
• Return Value: An absolute path to the resource or $null if the resource does not exists for the specified app.

A setup resource can be a file or a directory, which is used by custom scripts. The setup resources of an app are included in the app library.