Script tasks and multi line scripting in Azure DevOps Pipelines

Introduction

There are multiple ways to write scripts in Azure Pipelines, some of which allow for cross platform development. There are also some techniques for improving the readability of script tasks through shortcut tasks the use of multi line options.

Script Tasks

There are several dedicated script tasks that can be used for different purposes, some of the tasks have shortcut tasks which require much less input and are arguably easier to read. In the examples below, I have included the required inputs needed to run the scripts but in most cases, other optional inputs are available.

CmdLine@2

Runs a script in cmd.exe on a Windows VM, or in bash on any other VM.

steps:
  - task: CmdLine@2
    inputs:
      script: echo hello world

This task has a shortcut task which is script.

Powershell@2

Runs a powershell script. By default it uses Windows Powershell on a Windows VM and Powershell Core on any other VM. You can use pwsh: true to use Powershell Core on a Windows VM.

steps:
  - task: Powershell@2
    inputs:
      targetType: inline
      script: Write-Host "hello world"

This task has two shortcut tasks, if you want to default to Windows Powershell on a Windows VM, the shortcut is powershell, if you want to default to Powershell Core the shortcut is pwsh.

ShellScript@2

Runs a shell script using bash however, the only input for this is a script path.

steps:
  - task: ShellScript@2
    inputs:
      scriptPath: '$(Build.SourcesDirectory)/hello-world.sh'

AzurePowerShell@5

Allows you to run a powershell script in an Azure environment. The task authenticates with Azure using the provided service connection meaning that you do not need to authenticate with Azure. As with the powershell task, it will use Windows Powershell by default on a Windows VM unless you include the pwsh: true input.

steps:
  - task: AzurePowerShell@5
      inputs:
        azureSubscription: <service connection name>
        ScriptType: InlineScript
        Inline: Write-Host "hello world"

Shortcut tasks

Depending on your requirements, you may find that many scripts can be written using the shortcut types. I find this more preferable because often it means there is less to write and thus it is (subjectively) easier to read.

Script

This is a shortcut to CmdLine@2 and therefore runs the script in cmd.exe on a Windows VM and bash on any other VM. The code required to run the same command is:

steps:
  - script: echo hello world

Powershell or pwsh

If you use the powershell the script will be run in Windows Powershell on a Windows VM and Powershell Core on any other VM. If you use the pwsh shortcut, it will be run in Powershell Core. The code required to run the same command using the powershell task is:

steps:
  - powershell: Write-Host "hello world"

Similarly with the pwsh task:

steps:
  - pwsh: Write-Host "hello world"

Bear in mind that if you need to authenticate with Azure, then you should use the AzurePowerShell@5 task.

Multi line options

When writing a script, it is possible to supply multi-line commands, but you can also control what happens to the resulting command once it is compiled by using a pipe | or a right bracket >. A pipe | denotes that the script is using literal style. Each new line will be treated as a new line. A right angled bracket > on the other hand, denotes you are using folded style. Every new line will be folded into a single command. You can introduce a new line in folded style simply by leaving a blank new line. This can be used to improve readability of your command.

Literal Style

Here, I am using a pipe, meaning that each new line would be presented as a new line. The text below isn’t syntactically valid, purely done to demonstrate the behaviour.

script: |
   Here is a few lines of text.
   I am are using the literal style.
   This will return a few lines of text.   

The text returned would be:

Here is a few lines of text.
I am are using the literal style.
This will return a few lines of text.

Folded Style

Here, I have used a right bracket, meaning that I want to fold the new lines into one line, each new line will be folded and a space added.

script: >
   Here is a few lines of text.
   I am using the folded style.
   This will return a single line of text.   

The text returned would be:

Here is a few lines of text. I am using the folded style. This will return a single line of text.

Conclusion

I have a preference for using the shortcut tasks because it reduces the amount of inputs I need to remember and I also think improves readability. Also being able to use different multi-line options can improve readability of code by allowing you to split up a command onto multiple lines.

References

• AzurePowerShell@5
• CmdLine@2
• PowerShell@2
• ShellScript@2
• steps.script definition
• steps.powershell definition