printvis · PropmanProphecy · Dec 5, 2025 · Dec 5, 2025
@@ -1,13 +1,103 @@
-#
-# Script for creating cloud development environment
-# Please do not modify this script as it will be auto-updated from the AL-Go Template
-# Recommended approach is to use as is or add a script (freddyk-devenv.ps1), which calls this script with the user specific parameters
-#
+<#
+.SYNOPSIS
+    Creates a cloud-based development environment for Business Central AL development using SaaS Sandbox.
+
+.DESCRIPTION
+    This script sets up a cloud-based development environment by:
+    - Creating a Business Central SaaS Sandbox environment
+    - Compiling and publishing all apps and test apps to the development scope
+    - Configuring launch.json for Visual Studio Code with Cloud Sandbox configuration
+    - Optionally applying custom settings to override repository settings
+
+    The script will prompt you interactively for authentication using device code flow.
+    For automated/unattended execution, you can configure AdminCenterApiCredentials as a GitHub secret
+    or in Azure KeyVault. See https://aka.ms/algosettings for more information about AdminCenterApiCredentials.
+
+    This is an alternative to localDevEnv.ps1 for users who cannot run Docker containers locally.
+
+    RECOMMENDED USAGE:
+    Instead of modifying this script directly (which will be overwritten during AL-Go updates),
+    create a custom script that calls this one with your preferred parameters. For example,
+    create a file named after yourself (e.g., 'john-devenv.ps1') that contains:
+
+    # My personal cloud development environment script
+    $mySettings = '{"country":"us"}'
+    . .\.AL-Go\cloudDevEnv.ps1 -environmentName "john-sandbox" -reuseExistingEnvironment $true -customSettings $mySettings
+
+    This approach allows you to:
+    - Maintain your personal preferences without losing them during updates
+    - Share your setup with team members
+    - Version control your custom development configurations
+    - Easily switch between different development scenarios
+
+.PARAMETER environmentName
+    The name of the cloud sandbox environment to create or reuse.
+    If not specified, the script will prompt for input with a default of "{username}-sandbox".
+
+.PARAMETER reuseExistingEnvironment
+    Boolean parameter indicating whether to reuse an existing environment with the same name.
+    If $true, the script will use the existing environment if it exists.
+    If $false, the script will recreate the environment (deleting the old one if it exists).
+    If not specified, the script will prompt the user to select the behavior.
+
+.PARAMETER fromVSCode
+    Switch parameter indicating the script is being run from Visual Studio Code.
+    When specified, the script will pause at the end waiting for user input before closing.
+
+.PARAMETER clean
+    Switch parameter to create a clean development environment without compiling and publishing apps.
+    Useful for setting up a fresh environment without deploying any applications.
+
+.PARAMETER customSettings
+    JSON string containing custom settings that override repository settings.
+    These settings have the highest precedence and can be used to override country,
+    or other configuration without modifying repository files.
+
+.EXAMPLE
+    .\cloudDevEnv.ps1
+    Runs the script interactively, prompting for all required parameters.
+
+.EXAMPLE
+    .\cloudDevEnv.ps1 -environmentName "my-sandbox" -reuseExistingEnvironment $true
+    Creates or reuses a cloud sandbox named "my-sandbox".
+
+.EXAMPLE
+    .\cloudDevEnv.ps1 -clean
+    Creates a clean cloud development environment without compiling and publishing apps.
+
+.EXAMPLE
+    .\cloudDevEnv.ps1 -customSettings '{"country":"dk"}'
+    Creates a cloud development environment with custom settings for Denmark country.
+
+.EXAMPLE
+    # Programmatic setup with custom settings
+    $envName = "test-sandbox"
+    $settings = '{"country": "us"}'
+
+    . ./cloudDevEnv.ps1 -environmentName $envName -reuseExistingEnvironment $true -customSettings $settings
+
+    Creates or reuses a cloud development environment with custom country setting.
+
+.NOTES
+    - Authentication is handled interactively via device code flow (https://aka.ms/devicelogin)
+    - For unattended execution, configure AdminCenterApiCredentials secret (see link below)
+    - Does not require Docker to be installed
+    - Script automatically downloads required AL-Go helper modules and actions
+    - Modifies launch.json in VS Code workspace for Cloud Sandbox configuration
+    - Custom settings parameter allows runtime override of repository settings
+    - If NewBcContainer.ps1 override exists, cloud development may not be supported
+
+.LINK
+    https://aka.ms/algosettings - AL-Go Settings Documentation
+    https://github.com/microsoft/AL-Go/blob/main/Scenarios/CreateOnlineDevEnv2.md - Online Dev Environment Setup
+#>
+
 Param(
     [string] $environmentName = "",
     [bool] $reuseExistingEnvironment,
     [switch] $fromVSCode,
-    [switch] $clean
+    [switch] $clean,
+    [string] $customSettings = ""
 )
 
 $errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0
@@ -51,12 +141,12 @@ Write-Host -ForegroundColor Yellow @'
 
 $tmpFolder = Join-Path ([System.IO.Path]::GetTempPath()) "$([Guid]::NewGuid().ToString())"
 New-Item -Path $tmpFolder -ItemType Directory -Force | Out-Null
-$GitHubHelperPath = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/Github-Helper.psm1' -folder $tmpFolder -notifyAuthenticatedAttempt
-$ReadSettingsModule = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/.Modules/ReadSettings.psm1' -folder $tmpFolder
-$debugLoggingModule = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/.Modules/DebugLogHelper.psm1' -folder $tmpFolder
-$ALGoHelperPath = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/AL-Go-Helper.ps1' -folder $tmpFolder
-DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/.Modules/settings.schema.json' -folder $tmpFolder | Out-Null
-DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/Environment.Packages.proj' -folder $tmpFolder | Out-Null
+$GitHubHelperPath = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/Github-Helper.psm1' -folder $tmpFolder -notifyAuthenticatedAttempt
+$ReadSettingsModule = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/.Modules/ReadSettings.psm1' -folder $tmpFolder
+$debugLoggingModule = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/.Modules/DebugLogHelper.psm1' -folder $tmpFolder
+$ALGoHelperPath = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/AL-Go-Helper.ps1' -folder $tmpFolder
+DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/.Modules/settings.schema.json' -folder $tmpFolder | Out-Null
+DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/Environment.Packages.proj' -folder $tmpFolder | Out-Null
 
 Import-Module $GitHubHelperPath
 Import-Module $ReadSettingsModule
@@ -103,7 +193,8 @@ CreateDevEnv `
     -reuseExistingEnvironment:$reuseExistingEnvironment `
     -baseFolder $baseFolder `
     -project $project `
-    -clean:$clean
+    -clean:$clean `
+    -customSettings $customSettings
 }
 catch {
     Write-Host -ForegroundColor Red "Error: $($_.Exception.Message)`nStacktrace: $($_.scriptStackTrace)"

@@ -1,8 +1,106 @@
-#
-# Script for creating local development environment
-# Please do not modify this script as it will be auto-updated from the AL-Go Template
-# Recommended approach is to use as is or add a script (freddyk-devenv.ps1), which calls this script with the user specific parameters
-#
+<#
+.SYNOPSIS
+    Creates a local development environment for Business Central AL development using Docker containers.
+
+.DESCRIPTION
+    This script sets up a local development environment by:
+    - Creating a Business Central container using Docker
+    - Compiling and publishing all apps and test apps to the development scope
+    - Configuring launch.json for Visual Studio Code with Local Sandbox configuration
+    - Optionally applying custom settings to override repository settings
+
+    The script requires Docker to be installed and configured to run Windows containers.
+    If Docker setup fails, users can alternatively run cloudDevEnv.ps1 for cloud-based development.
+
+    RECOMMENDED USAGE:
+    Instead of modifying this script directly (which will be overwritten during AL-Go updates),
+    create a custom script that calls this one with your preferred parameters. For example,
+    create a file named after yourself (e.g., 'john-devenv.ps1') that contains:
+
+    # My personal development environment script
+    $mySettings = '{"country":"us","artifact":"////nextminor"}'
+    . .\.AL-Go\localDevEnv.ps1 -containerName "mydevenv" -auth UserPassword -customSettings $mySettings
+
+    This approach allows you to:
+    - Maintain your personal preferences without losing them during updates
+    - Share your setup with team members
+    - Version control your custom development configurations
+    - Easily switch between different development scenarios
+
+.PARAMETER containerName
+    The name of the Docker container to create. If not specified, the script will prompt for input.
+    Default prompts for "bcserver" if not provided.
+
+.PARAMETER auth
+    Authentication mechanism for the container. Valid values are "UserPassword" or "Windows".
+    If not specified, the script will prompt the user to select the authentication method.
+
+.PARAMETER credential
+    PSCredential object containing username and password for container authentication.
+    If not provided, the script will prompt for credentials based on the selected auth method.
+
+.PARAMETER licenseFileUrl
+    Local path or secure download URL to a Business Central license file.
+    For AppSource apps targeting BC versions prior to 22, a developer license with object ID permissions is required.
+    For PTEs, this is optional but can be useful for dependent app object IDs.
+    Set to "none" to skip license file input.
+
+.PARAMETER fromVSCode
+    Switch parameter indicating the script is being run from Visual Studio Code.
+    When specified, the script will pause at the end waiting for user input before closing.
+
+.PARAMETER accept_insiderEula
+    Switch parameter to automatically accept the insider EULA when using Business Central insider builds.
+    Required when working with insider artifacts.
+
+.PARAMETER clean
+    Switch parameter to create a clean development environment without compiling and publishing apps.
+    Useful for setting up a fresh container without deploying any applications.
+
+.PARAMETER customSettings
+    JSON string containing custom settings that override repository settings.
+    These settings have the highest precedence and can be used to override artifact URLs,
+    country settings, or other configuration without modifying repository files.
+
+.EXAMPLE
+    .\localDevEnv.ps1
+    Runs the script interactively, prompting for all required parameters.
+
+.EXAMPLE
+    .\localDevEnv.ps1 -containerName "mydevenv" -auth "UserPassword"
+    Creates a container named "mydevenv" with username/password authentication, prompting for credentials and LicenseFile.
+
+.EXAMPLE
+    .\localDevEnv.ps1 -clean
+    Creates a clean development environment without compiling and publishing apps.
+
+.EXAMPLE
+    .\localDevEnv.ps1 -customSettings '{"country":"dk","artifact":"////nextminor"}'
+    Creates a development environment with custom settings for Denmark country and specific artifact.
+
+.EXAMPLE
+    # Programmatic setup with credentials and custom settings
+    $Username = "SUPER"
+    $Password = "<some password>"
+    $cred = New-Object System.Management.Automation.PSCredential ($Username, (ConvertTo-SecureString $Password -AsPlainText -Force))
+    $containerName = "bcserver"
+    $settings = '{"artifact": "////nextminor"}'
+
+    . ./localDevEnv.ps1 -containerName $containerName -auth UserPassword -credential $cred -accept_insiderEula -licenseFileUrl "none" -customSettings $settings
+
+    Creates a development environment with predefined credentials, using next minor version artifact, accepting insider EULA, and no license file.
+
+.NOTES
+    - Requires Docker Desktop to be installed and running with Windows container support
+    - For AppSource apps, may require a developer license for BC versions prior to 22
+    - Script automatically downloads required AL-Go helper modules and actions
+    - Modifies launch.json in VS Code workspace for Local Sandbox configuration
+    - Custom settings parameter allows runtime override of repository settings
+
+.LINK
+    https://aka.ms/algosettings - AL-Go Settings Documentation
+#>
+
 Param(
     [string] $containerName = "",
     [ValidateSet("UserPassword", "Windows")]
@@ -11,7 +109,8 @@ Param(
     [string] $licenseFileUrl = "",
     [switch] $fromVSCode,
     [switch] $accept_insiderEula,
-    [switch] $clean
+    [switch] $clean,
+    [string] $customSettings = ""
 )
 
 $errorActionPreference = "Stop"; $ProgressPreference = "SilentlyContinue"; Set-StrictMode -Version 2.0
@@ -55,12 +154,12 @@ Write-Host -ForegroundColor Yellow @'
 
 $tmpFolder = Join-Path ([System.IO.Path]::GetTempPath()) "$([Guid]::NewGuid().ToString())"
 New-Item -Path $tmpFolder -ItemType Directory -Force | Out-Null
-$GitHubHelperPath = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/Github-Helper.psm1' -folder $tmpFolder -notifyAuthenticatedAttempt
-$ReadSettingsModule = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/.Modules/ReadSettings.psm1' -folder $tmpFolder
-$debugLoggingModule = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/.Modules/DebugLogHelper.psm1' -folder $tmpFolder
-$ALGoHelperPath = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/AL-Go-Helper.ps1' -folder $tmpFolder
-DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/.Modules/settings.schema.json' -folder $tmpFolder | Out-Null
-DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/Environment.Packages.proj' -folder $tmpFolder | Out-Null
+$GitHubHelperPath = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/Github-Helper.psm1' -folder $tmpFolder -notifyAuthenticatedAttempt
+$ReadSettingsModule = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/.Modules/ReadSettings.psm1' -folder $tmpFolder
+$debugLoggingModule = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/.Modules/DebugLogHelper.psm1' -folder $tmpFolder
+$ALGoHelperPath = DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/AL-Go-Helper.ps1' -folder $tmpFolder
+DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/.Modules/settings.schema.json' -folder $tmpFolder | Out-Null
+DownloadHelperFile -url 'https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/Environment.Packages.proj' -folder $tmpFolder | Out-Null
 
 Import-Module $GitHubHelperPath
 Import-Module $ReadSettingsModule
@@ -160,7 +259,8 @@ CreateDevEnv `
     -credential $credential `
     -licenseFileUrl $licenseFileUrl `
     -accept_insiderEula:$accept_insiderEula `
-    -clean:$clean
+    -clean:$clean `
+    -customSettings $customSettings
 }
 catch {
     Write-Host -ForegroundColor Red "Error: $($_.Exception.Message)`nStacktrace: $($_.scriptStackTrace)"

@@ -1,5 +1,5 @@
 {
-  "$schema": "https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/.Modules/settings.schema.json",
+  "$schema": "https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/.Modules/settings.schema.json",
   "country": "us",
   "appFolders": [],
   "testFolders": [],

@@ -1,8 +1,8 @@
 {
-  "$schema": "https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.0/.Modules/settings.schema.json",
+  "$schema": "https://raw.githubusercontent.com/microsoft/AL-Go-Actions/v8.1/.Modules/settings.schema.json",
   "type": "PTE",
   "templateUrl": "https://github.com/microsoft/AL-Go-PTE@main",
-  "templateSha": "359d32d051a800d7e28c3a0f97a724b16aed403b",
+  "templateSha": "2b0291277622df06df2856bc05768be2ebb5a6b5",
   "installApps": [
     "https://printvis.blob.core.windows.net/releases/CloudApps/NovaVision%20Software%20AS_PrintVis_24.4.1.0.app?sv=2023-01-03&st=2024-09-11T08%3A53%3A22Z&se=2026-07-12T08%3A53%3A00Z&sr=b&sp=r&sig=4bLYDcdOlC1Ymx8q%2Fa2hM5ci%2B%2By2TePO5eEQ%2F4q5KjI%3D"
   ],