add parameter to deploy new unified environment in early release cycle #128

.github/workflows/validate.yml

@@ -101,16 +101,17 @@ jobs:
       with:
         fetch-depth: 1
 
+    # The generated parameter tests expect the ProgressAction common parameter, which only exists in PowerShell 7.4+
     - name: Cache Powershell Modules
       id: cache-powershell-modules
       uses: actions/cache@v5
       with:
-        path: ~\Documents\WindowsPowerShell\Modules
-        key: ps-modules-${{ runner.os }}-v1
+        path: ~\Documents\PowerShell\Modules
+        key: pwsh-modules-${{ runner.os }}-v1
 
     - name: Install Prerequisites
       if: steps.cache-powershell-modules.outputs.cache-hit != 'true'
-      shell: powershell
+      shell: pwsh
       run: |
         Set-PSRepository -Name PSGallery -InstallationPolicy Trusted
         $modules = @('Pester','PSFramework','PSModuleDevelopment','PSScriptAnalyzer','ImportExcel','Az.Accounts')
@@ -120,5 +121,5 @@ jobs:
         }
 
     - name: Validate
-      shell: powershell
+      shell: pwsh
       run: build\vsts-validate-v2.ps1 -TestGeneral $false -TestFunctions $true

build/buildtools.ps1

@@ -0,0 +1,20 @@
+# Installs the modules required for the automatic text generation.
+# See also https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+
+Write-Host "Working on the machine named: $($env:computername)"
+Write-Host "The user running is: $($env:UserName)"
+
+$modules = @("PSModuleDevelopment", "platyPS")
+
+foreach ($item in $modules) {
+
+    $module = Get-InstalledModule -Name $item -ErrorAction SilentlyContinue
+
+    if ($null -eq $module) {
+        Write-Host "Installing $item" -ForegroundColor Cyan
+        Install-Module -Name $item -Force -Confirm:$false -Scope CurrentUser -AllowClobber -SkipPublisherCheck
+    }
+
+    Import-Module $item -Force
+    Get-Module -Name $item
+}

build/format-commentbasedhelp.ps1

@@ -0,0 +1,66 @@
+# Script to format the comments/documentation of the cmdlets used for the commend based help.
+# based on https://gist.github.com/Splaxi/ff7485a24f6ed9937f3e8da76b5d4840
+# See also https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+$path = "$PSScriptRoot\..\d365bap.tools"
+
+function Get-Header ($text) {
+    $start = $text.IndexOf('<#')
+    $temp = $start - 2
+    if($temp -gt 0) {
+        $text.SubString(0, $start - 2)
+    }
+    else {
+    ""
+    }
+}
+
+function Format-Help ($text) {
+    $start = $text.IndexOf('<#')
+    $end = $text.IndexOf('#>')
+    $help = $text.SubString($start + 2, $end - $start - 3)
+
+    $skipfirst = $null # to avoid trailing spaces
+    foreach ($newline in $help.Split("`n")) {
+        if (-not $skipfirst) { $skipfirst = $true; continue }
+        $trimmed = $newline.Trim()
+        foreach ($line in $trimmed) {
+            if ($line.StartsWith(".")) {
+                "    $line"
+            }
+            else {
+                "        $line"
+            }
+        }
+    }
+}
+
+function Get-Body ($text) {
+    $end = $text.IndexOf('#>')
+    $text.SubString($end, $text.Length - $end)
+}
+
+$files = New-Object System.Collections.ArrayList
+$filesPublic = Get-ChildItem -Path "$path\functions\*.ps1"
+$files.AddRange($filesPublic)
+$filesInternal = Get-ChildItem -Path "$path\internal\functions\*.ps1"
+$files.AddRange($filesInternal)
+
+# -Encoding UTF8 means "no BOM" on PowerShell 7, so write the files explicitly with a BOM instead
+$utf8Bom = New-Object System.Text.UTF8Encoding($true)
+$newLine = [System.Environment]::NewLine
+
+foreach ($file in $files) {
+    $text = ($file | Get-Content -Raw).Trim()
+
+    $builder = New-Object System.Text.StringBuilder
+    $null = $builder.Append((Get-Header $text).TrimEnd()).Append($newLine)
+    $null = $builder.Append("<#").Append($newLine)
+
+    foreach ($line in (Format-Help $text)) {
+        $null = $builder.Append($line).Append($newLine)
+    }
+
+    $null = $builder.Append((Get-Body $text).TrimEnd())
+
+    [System.IO.File]::WriteAllText($file.FullName, $builder.ToString(), $utf8Bom)
+}

build/generate-parameterunittests.ps1

@@ -0,0 +1,24 @@
+# Script to generate the parameter unit tests.
+# based on https://gist.github.com/Splaxi/2a24fc3c5193089ae7047ac5b8f104db
+# See also https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+$path = "$PSScriptRoot\..\d365bap.tools"
+
+Import-Module $path -Force
+
+$excludeCommands = @()
+
+$commandsRaw = Get-Command -Module d365bap.tools -CommandType Function
+
+if ($excludeCommands.Count -gt 0) {
+    $commands = $commandsRaw | Select-String -Pattern $excludeCommands -SimpleMatch -NotMatch
+
+} else {
+    $commands = $commandsRaw
+}
+
+Remove-Item -Path "$path\tests\functions\*.Tests.ps1"
+foreach ( $commandName in $commands) {
+    Invoke-PSMDTemplate CommandTest -OutPath "$path\tests\functions" -Name $commandName -Force
+}
+
+Get-ChildItem -Path "$path\tests\functions" -Recurse -File | Set-PSMDEncoding

build/update-docs.ps1

@@ -0,0 +1,11 @@
+# Script to generate the comment based markdown help files.
+# based on https://gist.github.com/Splaxi/8934e13cb35918d13af6e3a21c208b0e
+# See also https://github.com/d365collaborative/d365fo.tools/wiki/Building-tools
+$path = "$PSScriptRoot\.."
+
+Import-Module "$path\d365bap.tools" -Force
+
+Remove-Item -Path "$path\docs\*.md"
+$null = New-MarkdownHelp -Module d365bap.tools -OutputFolder "$path\docs" -Force
+
+Get-ChildItem -Path "$path\docs" -Recurse -File | Set-PSMDEncoding

d365bap.tools/functions/New-UnifiedEnvironment.ps1

@@ -63,6 +63,11 @@
     .PARAMETER WaitForCompletion
         Instructs the cmdlet to wait until the final provisioning app installation is completed.
 
+    .PARAMETER EarlyRelease
+        Instructs the cmdlet to create the environment in the early release cycle.
+
+        Note that not all locations/regions support early release environments.
+
     .EXAMPLE
         PS C:\> New-UnifiedEnvironment -Type "UDE" -Name "MyUdeEnv" -Location "Europe"
 
@@ -120,8 +125,19 @@
         It will take the latest available version of Finance and Operations.
         It will restrict access to the environment to members of the specified Entra Groups security group "MySecurityGroup".
 
+    .EXAMPLE
+        PS C:\> New-UnifiedEnvironment -Type "UDE" -Name "MyUdeEnv" -Location "Europe" -EarlyRelease
+
+        This will create a new Unified Developer Environment (UDE) named "MyUdeEnv" in the "Europe" location.
+        The environment will be in the early release cycle.
+        It will include a demo database by default.
+        It will get a default/unique domain name assigned by Power Platform.
+        It will take the latest available version of Finance and Operations.
+        It will not restrict access to the environment.
+
     .NOTES
         Author: Mötz Jensen (@Splaxi)
+        Author: Florian Hopfner (@FH-Inway)
 
 #>
 function New-UnifiedEnvironment {
@@ -155,7 +171,9 @@ function New-UnifiedEnvironment {
         [ValidateRange(1, 720)]
         [int] $ReadyStateTimeoutMinutes = 60,
 
-        [switch] $WaitForCompletion
+        [switch] $WaitForCompletion,
+
+        [switch] $EarlyRelease
     )
 
     begin {
@@ -191,7 +209,8 @@ function New-UnifiedEnvironment {
             CustomDomainName         = $CustomDomainName
             SecurityGroupId          = $SecurityGroupId
             PostProvisionDelaySeconds = $PostProvisionDelaySeconds
-            ReadyStateTimeoutMinutes = $ReadyStateTimeoutMinutes
+            ReadyStateTimeoutMinutes  = $ReadyStateTimeoutMinutes
+            EarlyRelease              = $EarlyRelease
         }
 
         $shellEnvironment = New-ShellEnvironment @shellEnvironmentParams
@@ -217,9 +236,9 @@ function New-UnifiedEnvironment {
             $provisioningParams = @{
                 Name              = $Name
                 Type              = $Type
-                NoDemoDb          = $NoDemoDb.IsPresent
+                NoDemoDb          = $NoDemoDb
                 Version           = $Version
-                WaitForCompletion = $WaitForCompletion.IsPresent
+                WaitForCompletion = $WaitForCompletion
             }
 
             $appObj = Start-PlatformProvisioning @provisioningParams
@@ -259,7 +278,9 @@ function New-ShellEnvironment {
         [int] $PostProvisionDelaySeconds,
 
         [Parameter(Mandatory = $true)]
-        [int] $ReadyStateTimeoutMinutes
+        [int] $ReadyStateTimeoutMinutes,
+
+        [switch] $EarlyRelease
     )
 
     $localUri = 'https://api.bap.microsoft.com/providers/Microsoft.BusinessAppPlatform/environments?api-version=2024-05-01'
@@ -300,6 +321,15 @@ function New-ShellEnvironment {
             -Value $SecurityGroupId
     }
 
+    if ($EarlyRelease) {
+        $config.properties | `
+            Add-Member -MemberType NoteProperty `
+                -Name cluster `
+                -Value ([PsCustomObject][ordered]@{
+                    category = "FirstRelease"
+                })
+    }
+
     $payload = $config | ConvertTo-Json -Depth 10
 
     $environmentExists = $false

d365bap.tools/tests/functions/Add-FscmEntraApplication.Tests.ps1

@@ -63,12 +63,25 @@
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
 		}
+		It 'Should have the expected parameter ProgressAction' {
+			$parameter = (Get-Command Add-FscmEntraApplication).Parameters['ProgressAction']
+			$parameter.Name | Should -Be 'ProgressAction'
+			$parameter.ParameterType.ToString() | Should -Be System.Management.Automation.ActionPreference
+			$parameter.IsDynamic | Should -Be $False
+			$parameter.ParameterSets.Keys | Should -Be '__AllParameterSets'
+			$parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets'
+			$parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].Position | Should -Be -2147483648
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
+		}
 	}
 
 	Describe "Testing parameterset __AllParameterSets" {
 		<#
 		__AllParameterSets -EnvironmentId -ClientId -MappedUser
-		__AllParameterSets -EnvironmentId -ClientId -Name -MappedUser
+		__AllParameterSets -EnvironmentId -ClientId -Name -MappedUser -ProgressAction
 		#>
 	}
 

d365bap.tools/tests/functions/Add-FscmSecurityRoleMember.Tests.ps1

@@ -50,12 +50,25 @@
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
 		}
+		It 'Should have the expected parameter ProgressAction' {
+			$parameter = (Get-Command Add-FscmSecurityRoleMember).Parameters['ProgressAction']
+			$parameter.Name | Should -Be 'ProgressAction'
+			$parameter.ParameterType.ToString() | Should -Be System.Management.Automation.ActionPreference
+			$parameter.IsDynamic | Should -Be $False
+			$parameter.ParameterSets.Keys | Should -Be '__AllParameterSets'
+			$parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets'
+			$parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].Position | Should -Be -2147483648
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
+		}
 	}
 
 	Describe "Testing parameterset __AllParameterSets" {
 		<#
 		__AllParameterSets -EnvironmentId -User -Role
-		__AllParameterSets -EnvironmentId -User -Role
+		__AllParameterSets -EnvironmentId -User -Role -ProgressAction
 		#>
 	}
 

d365bap.tools/tests/functions/Add-FscmUser.Tests.ps1

@@ -63,12 +63,25 @@
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
 		}
+		It 'Should have the expected parameter ProgressAction' {
+			$parameter = (Get-Command Add-FscmUser).Parameters['ProgressAction']
+			$parameter.Name | Should -Be 'ProgressAction'
+			$parameter.ParameterType.ToString() | Should -Be System.Management.Automation.ActionPreference
+			$parameter.IsDynamic | Should -Be $False
+			$parameter.ParameterSets.Keys | Should -Be '__AllParameterSets'
+			$parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets'
+			$parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].Position | Should -Be -2147483648
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
+		}
 	}
 
 	Describe "Testing parameterset __AllParameterSets" {
 		<#
 		__AllParameterSets -EnvironmentId -User
-		__AllParameterSets -EnvironmentId -User -Role -RemapExisting
+		__AllParameterSets -EnvironmentId -User -Role -RemapExisting -ProgressAction
 		#>
 	}
 

d365bap.tools/tests/functions/Add-FscmUserFromSecurityGroup.Tests.ps1

@@ -63,12 +63,25 @@
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
 		}
+		It 'Should have the expected parameter ProgressAction' {
+			$parameter = (Get-Command Add-FscmUserFromSecurityGroup).Parameters['ProgressAction']
+			$parameter.Name | Should -Be 'ProgressAction'
+			$parameter.ParameterType.ToString() | Should -Be System.Management.Automation.ActionPreference
+			$parameter.IsDynamic | Should -Be $False
+			$parameter.ParameterSets.Keys | Should -Be '__AllParameterSets'
+			$parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets'
+			$parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].Position | Should -Be -2147483648
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
+		}
 	}
 
 	Describe "Testing parameterset __AllParameterSets" {
 		<#
 		__AllParameterSets -EnvironmentId -SecurityGroup
-		__AllParameterSets -EnvironmentId -SecurityGroup -Role -RemapExisting
+		__AllParameterSets -EnvironmentId -SecurityGroup -Role -RemapExisting -ProgressAction
 		#>
 	}
 

d365bap.tools/tests/functions/Add-PpacAdminManagementApplication.Tests.ps1

@@ -24,12 +24,25 @@
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
 			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
 		}
+		It 'Should have the expected parameter ProgressAction' {
+			$parameter = (Get-Command Add-PpacAdminManagementApplication).Parameters['ProgressAction']
+			$parameter.Name | Should -Be 'ProgressAction'
+			$parameter.ParameterType.ToString() | Should -Be System.Management.Automation.ActionPreference
+			$parameter.IsDynamic | Should -Be $False
+			$parameter.ParameterSets.Keys | Should -Be '__AllParameterSets'
+			$parameter.ParameterSets.Keys | Should -Contain '__AllParameterSets'
+			$parameter.ParameterSets['__AllParameterSets'].IsMandatory | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].Position | Should -Be -2147483648
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipeline | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromPipelineByPropertyName | Should -Be $False
+			$parameter.ParameterSets['__AllParameterSets'].ValueFromRemainingArguments | Should -Be $False
+		}
 	}
 
 	Describe "Testing parameterset __AllParameterSets" {
 		<#
 		__AllParameterSets -
-		__AllParameterSets -ServicePrincipalId
+		__AllParameterSets -ServicePrincipalId -ProgressAction
 		#>
 	}