AzurePowerShell@5 - Azure PowerShell v5 task

Use this task to run a PowerShell script within an Azure environment. The Azure context is authenticated with the provided Azure Resource Manager service connection.

Note

By default, Azure PowerShell v5 uses PowerShell Core for Linux agents and Windows PowerShell for Windows agents. To use the latest version of PowerShell on Windows agents, set the pwsh parameter to true. PowerShell Core will then be used instead.

Syntax

# Azure PowerShell v5
# Run a PowerShell script within an Azure environment.
- task: AzurePowerShell@5
  inputs:
    azureSubscription: # string. Alias: ConnectedServiceNameARM. Required. Azure Subscription. 
    #ScriptType: 'FilePath' # 'FilePath' | 'InlineScript'. Script Type. Default: FilePath.
    #ScriptPath: # string. Optional. Use when ScriptType = FilePath. Script Path. 
    #Inline: # string. Optional. Use when ScriptType = InlineScript. Inline Script. 
    #ScriptArguments: # string. Optional. Use when ScriptType = FilePath. Script Arguments. 
    #errorActionPreference: 'stop' # 'stop' | 'continue' | 'silentlyContinue'. ErrorActionPreference. Default: stop.
    #FailOnStandardError: false # boolean. Fail on Standard Error. Default: false.
  # Azure PowerShell version options
    #azurePowerShellVersion: 'OtherVersion' # 'LatestVersion' | 'OtherVersion'. Alias: TargetAzurePs. Azure PowerShell Version. Default: OtherVersion.
    preferredAzurePowerShellVersion: # string. Alias: CustomTargetAzurePs. Required when TargetAzurePs = OtherVersion. Preferred Azure PowerShell Version. 
  # Advanced
    #pwsh: false # boolean. Use PowerShell Core. Default: false.
    #validateScriptSignature: false # boolean. Optional. Use when ScriptType = FilePath. Validate script signature. Default: false.
    #workingDirectory: # string. Working Directory.

Inputs

azureSubscription - Azure Subscription
Input alias: ConnectedServiceNameARM. string. Required.

The Azure Resource Manager subscription to configure before running PowerShell.

ScriptType - Script Type
string. Allowed values: FilePath (Script File Path), InlineScript (Inline Script). Default value: FilePath.

The type of the script: file path or inline.

ScriptPath - Script Path
string. Optional. Use when ScriptType = FilePath.

The path of the script. This should be a fully qualified path or one relative to the default working directory.

Inline - Inline Script
string. Optional. Use when ScriptType = InlineScript. Default value: # You can write your azure powershell scripts inline here. \n# You can also pass predefined and custom variables to this script using arguments.

Specifes the script to execute. The maximum supported inline script length is 5000 characters. Use a script from a file if you want to use a longer script.

ScriptArguments - Script Arguments
string. Optional. Use when ScriptType = FilePath.

The additional parameters to pass to PowerShell. These can be either ordinal or named parameters. Not applicable for an inline script option.

errorActionPreference - ErrorActionPreference
string. Allowed values: stop, continue, silentlyContinue. Default value: stop.

Selects the value of the ErrorActionPreference variable for executing the script.

FailOnStandardError - Fail on Standard Error
boolean. Default value: false.

When this is true, this task will fail if any errors are written to the error pipeline or if any data is written to the standard error stream.

azurePowerShellVersion - Azure PowerShell Version
Input alias: TargetAzurePs. string. Allowed values: LatestVersion (Latest installed version), OtherVersion (Specify other version). Default value: OtherVersion.

In case of hosted agents, the supported Azure PowerShell Versions are 1.0.0, 1.6.0, 2.3.2, 2.6.0, and 3.1.0 (Hosted VS2017 Queue). To pick the latest version available on the agent, select LatestVersion (Latest installed version).

For private agents you can specify a preferred version of Azure PowerShell using OtherVersion (Specify other version).

preferredAzurePowerShellVersion - Preferred Azure PowerShell Version
Input alias: CustomTargetAzurePs. string. Required when TargetAzurePs = OtherVersion.

The preferred Azure PowerShell Version needs to be a proper semantic version eg. 1.2.3. Regex like 2.\*,2.3.\* is not supported. The Hosted VS2017 Pool currently supports Az module versions 1.0.0, 1.6.0, 2.3.2, 2.6.0, and 3.1.0.

pwsh - Use PowerShell Core
boolean. Default value: false.

If this is true, then tasks running on Windows agents will use pwsh.exe from your path instead of powershell.exe.

validateScriptSignature - Validate script signature
boolean. Optional. Use when ScriptType = FilePath. Default value: false.

If this is true, then the task will first check to make sure specified script is signed and valid before executing it.

workingDirectory - Working Directory
string.

The working directory where the script is run.

Task control options

All tasks have control options in addition to their task inputs. For more information, see Control options and common task properties.

Output variables

None.

Remarks

Troubleshooting

Script worked locally, but failed in the pipeline

This typically occurs when the service connection used in the pipeline has insufficient permissions to run the script. Locally, the script runs with your credentials and would succeed as you may have the required access.

To resolve this issue, ensure the service principle/ authentication credentials have the required permissions. For more information, see Use Role-Based Access Control to manage access to your Azure subscription resources.

Error: Could not find the modules: '<module name>' with Version: '<version>'. If the module was recently installed, retry after restarting the Azure Pipelines task agent

Azure PowerShell task uses Azure/AzureRM/Az PowerShell Module to interact with Azure Subscription. This issue occurs when the PowerShell module is not available on the Hosted Agent. Hence, for a particular task version, Preferred Azure PowerShell version must be specified in the Azure PowerShell version options from the list of available versions. The installed software can be found in the Software table in Microsoft-hosted agents.

Service Connection Issues

To troubleshoot issues related to service connections, see Service Connection troubleshooting.

Examples

The following example shows how to invoke a script from a file and pass script arguments to it.

- task: AzurePowerShell@5
  inputs:
    azureSubscription: my-arm-service-connection
    scriptType: filePath
    scriptPath: $(Build.SourcesDirectory)\myscript.ps1
    scriptArguments:
      -Arg1 val1 `
      -Arg2 val2 `
      -Arg3 val3
    azurePowerShellVersion: latestVersion
    pwsh: true

The following arguments shows how to invoke an inline script.

- task: AzurePowerShell@5
  inputs:
    azureSubscription: 'Azure subscription connection placeholder'
    azurePowerShellVersion: LatestVersion
    ScriptType: 'InlineScript'
    Inline: |
      # You can write your azure powershell scripts inline here. 
      # You can also pass predefined and custom variables to this script using arguments
      Write-Host 'Hello'
      Write-Host 'World!'

Requirements

Requirement	Description
Pipeline types	YAML, Classic build, Classic release
Runs on	Agent, DeploymentGroup
Demands	None
Capabilities	This task does not satisfy any demands for subsequent tasks in the job.
Command restrictions	Any
Settable variables	Any
Agent version	2.115.0 or greater
Task category	Deploy