PowerShell helper scripts to be used locally and in Azure Pipelines for the Become-A-Teacher (BAT) services. It includes the following:

• A checklist for creating new scripts including "shoulds" and "should not".
• Code layout and formatting guidance.
• Writing Pester tests and using PSScriptAnalyzer to ensure best practise.

• das-platform-automation
  • Contents
• Helper Script Checklist
• Code Layout and Formatting
  • EditorConfig
    • EditorConfig Installation
    • Using EditorConfig
    • Troubleshooting EditorConfig
  • Visual Studio Code Workspace Settings
• Documentation
  • Comment Based Help
  • Naming Conventions
• Testing
  • Pester
    • Introduction
    • How it's Used
    • How to Write a Pester Unit Test
  • PSScriptAnalyzer
    • Introduction
    • How it's Used
  • Using Scripts in Azure Pipelines
• References and Further Reading

Use the following as a checklist when creating new helper scripts:

This section provides an overview of the following:

In order to maintain a consistent coding style, an EditorConfig file is used. The file .editorconfig contains the required styles. The EditorConfig file defines styles such as indentation size, indentation style, newline rules etc. The full list of supported properties in VS Code can be found here..

Tip: Ensure this is applied before committing and/or raising a pull request

EditorConfig can be installed as a Visual Studio Code extension. Search for and install EditorConfig for VS Code. The VS Code Marketplace has more information here.

For further information view the official website here.

The EditorConfig extension is activated whenever you open a new text editor, switch tabs into an existing one or focus into the editor you already have open. When activated, it uses EditorConfig to resolve the configuration for that particular file and applies any relevant editor settings.

The following styles are applied on save:

• end_of_line
• insert_final_newline
• trim_trailing_whitespace

The following styles are applied by using Format Document (Shift + Alt + F on Windows):

• indent_style
• indent_size
• tab_width

To troubleshoot EditorConfig and see what is being applied to your file, click OUTPUT in Visual Studio Code and in the drop down select Editorconfig. This will provide an output of what EditorConfig is applying. The following is an example of a final newline being inserted:

das-platform-automation/Infrastructure-Scripts/Get-AzStorageAccountConnectionString.ps1: Using EditorConfig core...
Infrastructure-Scripts/Get-AzStorageAccountConnectionString.ps1: setEndOfLine(LF)
Infrastructure-Scripts/Get-AzStorageAccountConnectionString.ps1: editor.action.trimTrailingWhitespace
Infrastructure-Scripts/Get-AzStorageAccountConnectionString.ps1: insertFinalNewline(LF)

The Visual Studio Code (VS Code) Workspace settings are located under the .vscode/settings.json. The settings are scoped to the open workspace and overrides the user scope. The settings are applied when the workspace is opened. The settings used are specific to PowerShell code formatting.

This section provides an overview of the following:

Scripts and functions should contain comment based help that is compatible with Get-Help.

The help should consist of the following elements:

• Synopsis
• Description
• A parameter description for each parameter in the Param() block
• At least one example demonstrating how the script can be executed

For further information see about_Comment_Based_Help

To ensure a consistant readable format, use the following naming conventions:

This section provides an overview of the following:

Pester is a test framework for PowerShell. It provides a language that allows you to define test cases, and the Invoke-Pester cmdlet to execute these tests and report the results. It is used to run a series of automated tests to ensure a new piece of code passes the defined criteria.

Pester is used to automate testing of the scripts under infrastructure-scripts. while working with a local branch of das-platform-automation, Pester can be invoked locally without having to commit changes to the remote repository. This is useful to ensure tests pass before running a build in Azure Pipelines with a pull request to master or a merge of the branch into master.

By default, Invoke-Pester runs all *.Tests.ps1 files. For example, to run all Pester tests in the tests folder run the following:

# Change directory into tests folder
cd ..\das-platform-automation\tests\
# Run Pester
Invoke-Pester

To run a specific test file:

# Change directory into tests folder
cd ..\das-platform-automation\tests\
# Run Pester
Invoke-Pester -Script .\UT001.Get-AzStorageAccountConnectionString.Tests.ps1

Awaiting Microsoft to fix bug with the GitHub release task: https://developercommunity.visualstudio.com/content/problem/612300/download-github-release-repository-drop-down-not-s.html microsoft/azure-pipelines-tasks#10685