Updates module to version 0.3.0

- Updates the module to version 0.3.0 and requires
 PSAppDeployToolkit 4.1.0
- Adds the ability to migrate v3 XML configuration settings to the v4 config.psd1.
- Updates Convert-ADTDeployment to handle additional $adtSession variables introduced in PSADT 4.1.
- Adds special handling of DeployMode and Show-InstallationWelcome's -CloseApps parameter migration.

Author: sintaxasn

CHANGELOG.txt

@@ -1 +1,24 @@
-
+PSAppDeployToolkit.Tools Change Log
+=====================================
+
+## [0.3.0] - 2025-07-29
+
+- Added the ability to migrate v3 XML configuration settings to the v4 config.psd1
+- Updated Convert-ADTDeployment to additional $adtSession variables introduced in PSADT 4.1:
+  - appSuccessExitCodes, appRebootExitCodes, appProcessesToClose
+  - requireAdmin, deployAppScriptFriendlyName, deployAppScriptVersion
+- Added special handling of DeployMode migration
+  - If set to Interactive, the setting is not migrated.  This is so that the migrated script adopts the default DeployMode, which is now Auto
+  - All other values are migrated to $adtSession.DeployMode
+- Added special handling of Show-InstallationWelcome's -CloseApps parameter to migrate to $adtSession.appProcessesToClose
+  - Supports both simple names ("notepad,excel") and name=description pairs ("notepad=Notepad,excel=Microsoft Excel")
+  - Converts to correct hashtable format
+- Updated module manifest to require PSAppDeployToolkit 4.1.0 (previously 4.0.5)
+- Updated ImportsFirst.ps1 to use PSAppDeployToolkit 4.1.0 requirement
+
+## [0.2.3] - 2024-12-03
+
+### Initial Features
+- Convert-ADTDeployment: Convert PSAppDeployToolkit v3 scripts and packages to v4 format
+- Test-ADTCompatibility: Test v3 scripts for compatibility issues with v4
+- Custom PSScriptAnalyzer rules for PSADT compatibility checking

README.md

@@ -1,23 +1,31 @@
 # ![PSAppDeployToolkit.Tools](https://github.com/user-attachments/assets/a275b3f9-6a45-42f0-a377-a57036d3f84d)
 
-## Enterprise App Packaging, Extended.
+## 🚀 Enterprise App Packaging, Extended
 
 PSAppDeployToolkit.Tools is a companion module for [PSAppDeployToolkit](https://github.com/PSAppDeployToolkit/PSAppDeployToolkit) that provides tools and functions useful during the application packaging process. Having this separate allows for a separate release schedule and also reduces the file size of the module that is required to be delivered to endpoints to handle software deployments.
 
-### Features
+### ✨ Key Features
 
-- **Test-ADTCompatibility** - Test your PSAppDeployToolkit v3 scripts to get a full report on which functions and variables have changed in v4.
-- **Convert-ADTDeployment** - Convert a PSAppDeployToolkit v3 script or an entire package folder to v4 standards.
+- **Test-ADTCompatibility** - Test your PSAppDeployToolkit v3 scripts to get a full report on which functions and variables have changed in v4.1.
+- **Convert-ADTDeployment** - Convert a PSAppDeployToolkit v3 script or an entire package folder to v4.1 standards.
 
-## Getting Started
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Windows 10/11
+- PowerShell 5.1 or later
+- .NET Framework 4.7.2 or later
+
+### Installing The Module
 
 Install the module from the PowerShell Gallery:
 
 ```powershell
 Install-Module PSAppDeployToolkit.Tools -Scope CurrentUser -AllowPreRelease
 ```
 
-If this produces an error that the `-AllowPreRelease` parameter is not recognised, then first update PowerShellGet and then restart your PowerShell console:
+If this produces an error that the `-AllowPreRelease` parameter is not recognized, then first update PowerShellGet and then restart your PowerShell console:
 
 ```powershell
 Install-Module PowerShellGet -Force -Scope CurrentUser
@@ -49,22 +57,29 @@ Convert-ADTDeployment -Path .\PackageFolder
 
 This example converts PackageFolder into PackageFolder_Converted in the same folder.
 
-### PSAppDeployToolkit Links
+## 📄 License
+
+This project is licensed under the [GNU Lesser General Public License](https://github.com/PSAppDeployToolkit/PSAppDeployToolkit/blob/main/COPYING.Lesser)
+
+## Important Links
 
--> [Homepage](https://psappdeploytoolkit.com)
--> [Documentation](https://psappdeploytoolkit.com/docs)
--> [Function & Variable References](https://psappdeploytoolkit.com/docs/reference)
--> [Download Latest Release](https://github.com/PSAppDeployToolkit/PSAppDeployToolkit/releases)
--> [News](https://psappdeploytoolkit.com/blog)
+### PSAppDeployToolkit
 
-### Community Links
+- [Homepage](https://psappdeploytoolkit.com)
+- [Latest News](https://psappdeploytoolkit.com/blog)
+- [Documentation](https://psappdeploytoolkit.com/docs/introduction)
+- [Function & Variable References](https://psappdeploytoolkit.com/docs/reference)
+- [PowerShell Gallery](https://www.powershellgallery.com/packages/PSAppDeployToolkit)
+- [GitHub Releases](https://github.com/PSAppDeployToolkit/PSAppDeployToolkit/releases)
 
--> [Discourse Forum](https://discourse.psappdeploytoolkit.com/)
--> [Discord Chat](https://discord.com/channels/618712310185197588/627204361545842688)
--> [Reddit](https://reddit.com/r/psadt)
+### Community
 
-## License
+- [Discourse Forum](https://discourse.psappdeploytoolkit.com/)
+- [Discord Chat](https://discord.com/channels/618712310185197588/627204361545842688)
+- [Reddit](https://reddit.com/r/psadt)
 
-The PowerShell App Deployment Tool is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or any later version.
+### GitHub
 
-This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+- [Issues](https://github.com/PSAppDeployToolkit/PSAppDeployToolkit/issues)
+- [Security Policy](https://github.com/PSAppDeployToolkit/PSAppDeployToolkit/security)
+- [Contributor Guidelines](https://github.com/PSAppDeployToolkit/PSAppDeployToolkit/blob/main/.github/CONTRIBUTING.md)

src/PSAppDeployToolkit.Tools/ImportsFirst.ps1

@@ -6,7 +6,7 @@ PSAppDeployToolkit.Tools - companion module for PSAppDeployToolkit.
 .DESCRIPTION
 This module script contains functions to aid enterprise application packaging and the creation of PSAppDeployToolkit deployment scripts.
 
-PSAppDeployToolkit is licensed under the GNU LGPLv3 License - (C) 2024 PSAppDeployToolkit Team (Sean Lillis, Dan Cunningham, Muhammad Mashwani, Mitch Richters, Dan Gough).
+PSAppDeployToolkit is licensed under the GNU LGPLv3 License - (C) 2025 PSAppDeployToolkit Team (Sean Lillis, Dan Cunningham, Muhammad Mashwani, Mitch Richters, Dan Gough).
 
 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the
 Free Software Foundation, either version 3 of the License, or any later version. This program is distributed in the hope that it will be useful, but
@@ -28,7 +28,7 @@ https://psappdeploytoolkit.com
 $RequiredModules = [System.Collections.ObjectModel.ReadOnlyCollection[Microsoft.PowerShell.Commands.ModuleSpecification]]$(
     @{ ModuleName = 'Microsoft.PowerShell.Management'; Guid = 'eefcb906-b326-4e99-9f54-8b4bb6ef3c6d'; ModuleVersion = '1.0' }
     @{ ModuleName = 'Microsoft.PowerShell.Utility'; Guid = '1da87e53-152b-403e-98dc-74d7b4d63d59'; ModuleVersion = '1.0' }
-    @{ ModuleName = 'PSAppDeployToolkit'; Guid = '8c3c366b-8606-4576-9f2d-4051144f7ca2'; ModuleVersion = '3.93.0' }
+    @{ ModuleName = 'PSAppDeployToolkit'; Guid = '8c3c366b-8606-4576-9f2d-4051144f7ca2'; ModuleVersion = '4.1.0' }
     @{ ModuleName = 'PSScriptAnalyzer'; Guid = 'd6245802-193d-4068-a631-8863a4342a18'; ModuleVersion = '1.23.0' }
 )
 

src/PSAppDeployToolkit.Tools/PSAppDeployToolkit.Tools.psd1

@@ -1,15 +1,15 @@
 #
 # Module manifest for module 'PSAppDeployToolkit.Tools'
 #
-# Last modified: 2025-01-24
+# Last modified: 2025-07-29
 #
 
 @{
     # Script module or binary module file associated with this manifest.
     RootModule = 'PSAppDeployToolkit.Tools.psm1'
 
     # Version number of this module.
-    ModuleVersion = '0.2.3'
+    ModuleVersion = '0.3.0'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()
@@ -24,7 +24,7 @@
     CompanyName = 'PSAppDeployToolkit Team'
 
     # Copyright statement for this module
-    Copyright = 'Copyright © 2024 PSAppDeployToolkit Team. All rights reserved.'
+    Copyright = 'Copyright © 2025 PSAppDeployToolkit Team. All rights reserved.'
 
     # Description of the functionality provided by this module
     Description = 'Enterprise App Packaging, Extended.'
@@ -39,7 +39,7 @@
     PowerShellHostVersion = '5.1.14393.0'
 
     # Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
-    DotNetFrameworkVersion = '4.6.2.0'
+    DotNetFrameworkVersion = '4.7.2.0'
 
     # Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
     CLRVersion = '4.0.30319.42000'
@@ -49,7 +49,7 @@
 
     # Modules that must be imported into the global environment prior to importing this module
     RequiredModules = @(
-        @{ModuleName = 'PSAppDeployToolkit'; GUID = '8c3c366b-8606-4576-9f2d-4051144f7ca2'; ModuleVersion = '4.0.5'; }
+        @{ModuleName = 'PSAppDeployToolkit'; GUID = '8c3c366b-8606-4576-9f2d-4051144f7ca2'; ModuleVersion = '4.1.0'; }
         @{ModuleName = 'PSScriptAnalyzer'; GUID = 'd6245802-193d-4068-a631-8863a4342a18'; ModuleVersion = '1.23.0'; }
     )
 

src/PSAppDeployToolkit.Tools/PSScriptAnalyzer/Measure-ADTCompatibility.psm1

@@ -1,8 +1,8 @@
-<#
+<#
     .SYNOPSIS
-    PSSCriptAnalyzer rules to check for usage of legacy PSAppDeployToolkit v3 commands or variables.
+    PSScriptAnalyzer rules to check for usage of legacy PSAppDeployToolkit v3 commands or variables.
     .DESCRIPTION
-    Can be used directly with PSSCriptAnalyzer or via Test-ADTCompatibility and Convert-ADTDeployment functions.
+    Can be used directly with PSScriptAnalyzer or via Test-ADTCompatibility and Convert-ADTDeployment functions.
     .EXAMPLE
     Measure-ADTCompatibility -ScriptBlockAst $ScriptBlockAst
     .INPUTS
@@ -1894,6 +1894,7 @@ function Measure-ADTCompatibility
                         "-CloseProcesses $closeProcesses"
                     }
                 }
+
             }
             'Get-WindowTitle' = @{
                 'NewFunction' = 'Get-ADTWindowTitle'
@@ -2552,6 +2553,46 @@ function Measure-ADTCompatibility
             xmlUIMessages = $null
         }
 
+        $configMappings = @{
+            # XML Config variables to Get-ADTConfig equivalents
+            configBalloonTextComplete = '(Get-ADTStringTable).BalloonText.Complete'
+            configBalloonTextError = '(Get-ADTStringTable).BalloonText.Error'
+            configBalloonTextFastRetry = '(Get-ADTStringTable).BalloonText.FastRetry'
+            configBalloonTextRestartRequired = '(Get-ADTStringTable).BalloonText.RestartRequired'
+            configBalloonTextStart = '(Get-ADTStringTable).BalloonText.Start'
+            configToolkitCompressLogs = '(Get-ADTConfig).Toolkit.CompressLogs'
+            configToolkitLogMaxHistory = '(Get-ADTConfig).Toolkit.LogMaxHistory'
+            configToolkitLogMaxSize = '(Get-ADTConfig).Toolkit.LogMaxSize'
+            configToolkitLogPath = '(Get-ADTConfig).Toolkit.LogPath'
+            configToolkitLogStyle = '(Get-ADTConfig).Toolkit.LogStyle'
+            configToolkitLogWriteToHost = '(Get-ADTConfig).Toolkit.LogWriteToHost'
+            configToolkitRegPath = '(Get-ADTConfig).Toolkit.RegPath'
+            configToolkitTempPath = '(Get-ADTConfig).Toolkit.TempPath'
+            configMSIInstallParams = '(Get-ADTConfig).MSI.InstallParams'
+            configMSISilentParams = '(Get-ADTConfig).MSI.SilentParams'
+            configMSIUninstallParams = '(Get-ADTConfig).MSI.UninstallParams'
+            configMSILoggingOptions = '(Get-ADTConfig).MSI.LoggingOptions'
+            configMSILogPath = '(Get-ADTConfig).MSI.LogPath'
+            configMSIMutexWaitTime = '(Get-ADTConfig).MSI.MutexWaitTime'
+            configUIDefaultTimeout = '(Get-ADTConfig).UI.DefaultTimeout'
+            configUIBalloonNotifications = '(Get-ADTConfig).UI.BalloonNotifications'
+            configUILanguageOverride = '(Get-ADTConfig).UI.LanguageOverride'
+            configUIDialogStyle = '(Get-ADTConfig).UI.DialogStyle'
+            configUIFluentAccentColor = '(Get-ADTConfig).UI.FluentAccentColor'
+            configUIPromptToSaveTimeout = '(Get-ADTConfig).UI.PromptToSaveTimeout'
+            configUIRestartPromptPersistInterval = '(Get-ADTConfig).UI.RestartPromptPersistInterval'
+            configAssetsBanner = '(Get-ADTConfig).Assets.Banner'
+            configAssetsLogo = '(Get-ADTConfig).Assets.Logo'
+            configAssetsLogoDark = '(Get-ADTConfig).Assets.LogoDark'
+            # Legacy XML config access patterns
+            xmlConfigToolkitCompressLogs = '(Get-ADTConfig).Toolkit.CompressLogs'
+            xmlConfigToolkitLogMaxHistory = '(Get-ADTConfig).Toolkit.LogMaxHistory'
+            xmlConfigToolkitLogMaxSize = '(Get-ADTConfig).Toolkit.LogMaxSize'
+            xmlConfigToolkitLogPath = '(Get-ADTConfig).Toolkit.LogPath'
+            xmlConfigMSIOptions = '$null  # XML MSI options are now in (Get-ADTConfig).MSI'
+            xmlConfigUIOptions = '$null  # XML UI options are now in (Get-ADTConfig).UI'
+        }
+
         $spBinder = [System.Management.Automation.Language.StaticParameterBinder]
     }
 
@@ -2566,6 +2607,13 @@ function Measure-ADTCompatibility
             }
             [System.Management.Automation.Language.Ast[]]$variableAsts = $ScriptBlockAst.FindAll($variablePredicate, $true)
 
+            # Get legacy config variables
+            [ScriptBlock]$configPredicate = {
+                param ([System.Management.Automation.Language.Ast]$Ast)
+                $Ast -is [System.Management.Automation.Language.VariableExpressionAst] -and $Ast.Parent -isnot [System.Management.Automation.Language.ParameterAst] -and $Ast.VariablePath.UserPath -in $configMappings.Keys
+            }
+            [System.Management.Automation.Language.Ast[]]$configAsts = $ScriptBlockAst.FindAll($configPredicate, $true)
+
             # Get legacy functions
             [ScriptBlock]$commandPredicate = {
                 param ([System.Management.Automation.Language.Ast]$Ast)
@@ -2749,6 +2797,17 @@ function Measure-ADTCompatibility
                 $variableName = $variableAst.VariablePath.UserPath
                 $newVariable = $variableMappings[$variableName]
 
+                # Special handling for DeployMode = 'Interactive' - don't suggest migration
+                if ($variableName -eq 'DeployMode' -and $variableAst.Parent -is [System.Management.Automation.Language.AssignmentStatementAst])
+                {
+                    $assignmentValue = $variableAst.Parent.Right.Extent.Text.Trim().Trim("'", '"')
+                    if ($assignmentValue -eq 'Interactive')
+                    {
+                        # Skip suggesting migration for Interactive values
+                        continue
+                    }
+                }
+
                 if ([string]::IsNullOrWhiteSpace($newVariable))
                 {
                     $outputMessage = "The variable [`$$variableName] is deprecated and no longer available."
@@ -2808,7 +2867,68 @@ function Measure-ADTCompatibility
                 }
             }
 
-            # 3. Redefine legacy functions
+            # Process all legacy config variables third
+            foreach ($configAst in $configAsts)
+            {
+                $configVariableName = $configAst.VariablePath.UserPath
+                $newConfig = $configMappings[$configVariableName]
+
+                if ([string]::IsNullOrWhiteSpace($newConfig))
+                {
+                    $outputMessage = "The config variable [`$$configVariableName] is deprecated and no longer available."
+                    $suggestedCorrections = $null
+                }
+                else
+                {
+                    if ($newConfig -match 'Get-ADTConfig')
+                    {
+                        $outputMessage = "The config variable [`$$configVariableName] is now accessed via the configuration system. Use [$newConfig] instead."
+                    }
+                    elseif ($newConfig -match 'Get-ADTStringTable')
+                    {
+                        $outputMessage = "The config variable [`$$configVariableName] is now accessed via the string table. Use [$newConfig] instead."
+                    }
+                    else
+                    {
+                        $outputMessage = "The config variable [`$$configVariableName] is deprecated. Use [$newConfig] instead."
+                    }
+
+                    if ($newConfig -like '*.*' -and $configAst.Parent.StringConstantType -in [System.Management.Automation.Language.StringConstantType]'DoubleQuoted', [System.Management.Automation.Language.StringConstantType]'DoubleQuotedHereString')
+                    {
+                        # Wrap variable in $() if it contains a . and is used in a double-quoted string
+                        $newConfig = "`$($newConfig)"
+                    }
+
+                    # Create a CorrectionExtent object for the suggested correction
+                    $objParams = @{
+                        TypeName = 'Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.CorrectionExtent'
+                        ArgumentList = @(
+                            $configAst.Extent.StartLineNumber
+                            $configAst.Extent.EndLineNumber
+                            $configAst.Extent.StartColumnNumber
+                            $configAst.Extent.EndColumnNumber
+                            $newConfig
+                            $MyInvocation.MyCommand.Definition
+                            'More information: https://psappdeploytoolkit.com/docs/reference/config-settings'
+                        )
+                    }
+                    $correctionExtent = New-Object @objParams
+                    $suggestedCorrections = New-Object System.Collections.ObjectModel.Collection[$($objParams.TypeName)]
+                    $suggestedCorrections.Add($correctionExtent) | Out-Null
+                }
+
+                # Output the diagnostic record in the format expected by the ScriptAnalyzer
+                [Microsoft.Windows.PowerShell.ScriptAnalyzer.Generic.DiagnosticRecord]@{
+                    Message = $outputMessage
+                    Extent = $configAst.Extent
+                    RuleName = 'Measure-ADTCompatibility'
+                    Severity = 'Warning'
+                    RuleSuppressionID = 'ADTCompatibilitySuppression'
+                    SuggestedCorrections = $suggestedCorrections
+                }
+            }
+
+            # Redefine legacy functions last
             foreach ($commandAst in $commandAsts)
             {
                 $functionName = $commandAst.GetCommandName()