Added utilities wiki entry

docs/wiki/Home.md

@@ -25,6 +25,7 @@ If you're unfamiliar with Infrastructure as Code, or wonder how you can use the
   - [Register Azure DevOps pipelines script](./UtilitiesRegisterAzureDevOpsPipeline)
   - [Set Module ReadMe script](./UtilitiesSetModuleReadMe)
   - [Get formatted RBAC roles script](./UtilitiesGetFormattedRBACRoleList)
+  - [GitHub readMe module table update script](./UtilitiesSetGitHubReadMeModuleTable.md)
 - [Pipelines](./Pipelines)
   - [Design](./PipelinesDesign)
     - [Parameter File Tokens](./ParameterFileTokens)

docs/wiki/UtilitiesConvertToARMTemplate.md

@@ -11,7 +11,6 @@ This page documents the conversion utility and how to use it.
 - [Location](#location)
 - [How it works](#what-it-does)
 - [How to use it](#how-to-use-it)
-  - [Examples](#examples)
 
 ---
 # Location

docs/wiki/UtilitiesGetFormattedRBACRoleList.md

@@ -9,7 +9,6 @@ Use this script to format a given raw 'Roles' table from Azure to the format req
 - [Location](#location)
 - [How it works](#what-it-does)
 - [How to use it](#how-to-use-it)
-  - [Examples](#examples)
 
 ---
 # Location

docs/wiki/UtilitiesRegisterAzureDevOpsPipeline.md

@@ -9,7 +9,6 @@ Use this script to automatically register all specified Azure DevOps pipelines i
 - [Location](#location)
 - [How it works](#what-it-does)
 - [How to use it](#how-to-use-it)
-  - [Examples](#examples)
 
 ---
 # Location

docs/wiki/UtilitiesSetGitHubReadMeModuleTable.md

@@ -0,0 +1,29 @@
+# GitHub ReadMe Module Table Update Script
+
+Use this script to update a given ReadMe's module table in its 'Available Resource Modules' section.
+In the platform's pipeline `platform.updateReadMe.yml`, this script is invoked each time anything in the `arm` path changes to keep the table in sync. It updates both the root ReadMe (`/readme.md`) and `arm` folder ReadMe (`/arm/readme.md`) with a different set of required columns
+
+---
+
+### _Navigation_
+
+- [Location](#location)
+- [How it works](#what-it-does)
+- [How to use it](#how-to-use-it)
+
+---
+# Location
+
+You can find the script under `/utilities/tools/Set-GitHubReadMeModuleTable.ps1`
+
+# How it works
+
+1. The script loads the current content of the given readMe file (the one provided via the parameter `FilePath`)
+1. It then generates a new table based on an either specified or default set of intended columns (for example a `name` column, and or `status` column)
+1. It replaces the original content in section `Available Resource Modules` with the new table
+1. If not invoked with a `-WhatIf` the script will eventually overwrite the original file with the new content
+
+# How to use it
+
+For details on how to use the function please refer to the script's local documentation.
+> **Note:** The script must be loaded before the function can be invoked

docs/wiki/UtilitiesSetModuleReadMe.md

@@ -12,7 +12,6 @@ For further information about the parameter usage blocks, please refer to the [s
 - [How it works](#what-it-does)
   - [Special case: 'Parameter Usage' section](#special-case-parameter-usage-section)
 - [How to use it](#how-to-use-it)
-  - [Examples](#examples)
 
 ---
 # Location

docs/wiki/UtilitiesTestModuleLocally.md

@@ -0,0 +1,37 @@
+# Test Module locally Script
+
+Use this script to test a module locally. You can use it to run only the pester tests, a deployment validation (dryRun) or run a the actual deployment. For the later cases this is important as the script will handles any placeholder tokens in the used parameter file for you.
+
+---
+
+### _Navigation_
+
+- [Location](#location)
+- [How it works](#what-it-does)
+- [How to use it](#how-to-use-it)
+
+---
+# Location
+
+You can find the script under `/utilities/tools/Test-ModuleLocally.ps1`
+
+# How it works
+
+If the switch for pester tests (`-PesterTest`) was provided the script will
+1. Invoke the global module test for the provided template file path and run all tests for it
+
+If the switch for either the validation test (`-ValidationTest`) or deployment test (`-DeploymentTest`) was provided alongside a hashtable for the token replacement (`-ValidateOrDeployParameters`), the script will
+1. Search all parameter files for the given module template
+1. Craft a dictionary to replace all tokens in these parameter files with actual values. This dictionary will consist
+   - of the subscriptionID & managementGroupID of the provided `ValidateOrDeployParameters` object,
+   - add all key-value pairs of the `-AdditionalTokens` object to it,
+   - and optionally also add all key-value pairs specified in the `settings.json`'s `parameterFileTokens` object if the `-SkipParameterFileTokens` parameter was not set
+1. It replaces all tokens in the parameter files as per the object created in the previous step
+1. If the `-ValidationTest` parameter was set, it runs a deployment validation using the `Test-TemplateWithParameterFile` script
+1. If the `-DeploymentTest` parameter was set, it runs a deployment using the `New-ModuleDeployment` script (with no retries). By default it uses the standard `parameters.json` parameter file. However, if the switch `-DeployAllModuleParameterFiles` was set, it runs the deployment for all parameter files in the module's `.parameters` folder
+1. As a final step it rolls the parameter files back to their original state if either the `-ValidationTest` or `-DeploymentTest` parameters were provided.
+
+# How to use it
+
+For details on how to use the function please refer to the script's local documentation.
+> **Note:** The script must be loaded before the function can be invoked

utilities/tools/Test-ModuleLocally.ps1

@@ -25,8 +25,8 @@ Optional. A Switch Parameter that triggers the Validation of the Module Only wit
 .PARAMETER DeployAllModuleParameterFiles
 Optional. A Boolean Parameter that enables directory based search for parameter files and deploys all of them. If not true, it will only deploy the 'parameters.json' file. Default is false.
 
-.PARAMETER GetParameterFileTokens
-Optional. A Boolean Parameter that enables the search for local custom parameter file tokens. Default is true.
+.PARAMETER SkipParameterFileTokens
+Optional. A Switch Parameter that enables you to skip the search for local custom parameter file tokens.
 
 .PARAMETER AdditionalTokens
 Optional. A Hashtable Parameter that contains custom tokens to be replaced in the paramter files for deployment
@@ -102,7 +102,7 @@ function Test-ModuleLocally {
         [bool]$DeployAllModuleParameterFiles = $false,
 
         [parameter(Mandatory = $false)]
-        [bool]$GetParameterFileTokens = $true,
+        [switch]$SkipParameterFileTokens,
 
         [parameter(Mandatory = $false)]
         [psobject]$AdditionalTokens
@@ -122,7 +122,6 @@ function Test-ModuleLocally {
         if ($PesterTest) {
             Write-Verbose "Pester Testing Module: $ModuleName"
             try {
-                Import-Module Pester
                 Invoke-Pester -Configuration @{
                     Run        = @{
                         Container = New-PesterContainer -Path (Join-Path $PSScriptRoot '../..' 'arm/.global/global.module.tests.ps1') -Data @{
@@ -156,7 +155,7 @@ function Test-ModuleLocally {
             ) | ForEach-Object { [PSCustomObject]$PSItem }
 
             # Look for Local Custom Parameter File Tokens (Source Control)
-            if ($GetParameterFileTokens) {
+            if (-not $SkipParameterFileTokens) {
                 # Get Settings JSON File
                 $Settings = Get-Content -Path (Join-Path $PSScriptRoot '../..' 'settings.json') | ConvertFrom-Json
                 # Get Custom Parameter File Tokens (Local)