Upgrade PlatyPS to 1.0.1

.azure-pipelines/PipelineSteps/analyze-steps.ps1

@@ -28,7 +28,7 @@ function Assert-ExitCodeSuccess {
 
 # Install PowerShell dependencies
 Write-Host -ForegroundColor Green "-------------------- Start installing PowerShell dependencies ... --------------------"
-Install-Module "platyPS", "PSScriptAnalyzer" -Repository PSGallery -Force -Confirm:$false -Scope CurrentUser
+Install-Module "Microsoft.PowerShell.PlatyPS", "PSScriptAnalyzer" -Repository PSGallery -Force -Confirm:$false -Scope CurrentUser
 Write-Host -ForegroundColor DarkGreen "-------------------- End installing PowerShell dependencies ... --------------------`n`n`n`n`n"
 
 # Install latest Az modules

.azure-pipelines/security-tools.yml

@@ -70,10 +70,10 @@ jobs:
         & $buildStepsPath -RepoRoot "$(Build.SourcesDirectory)" -Configuration "Debug" -FilesChangedOutputPath $filesChangedOutputPath -IsSecurityCheck $true -BuildReason $(Build.Reason) -Trigger $trigger
 
   - task: PowerShell@2
-    displayName: Install platyPS
+    displayName: Install Microsoft.PowerShell.PlatyPS
     inputs:
       targetType: inline
-      script: Install-Module platyPS -Force -Confirm:$false -Scope CurrentUser
+      script: Install-Module Microsoft.PowerShell.PlatyPS -Force -Confirm:$false -Scope CurrentUser
       pwsh: true
   - task: UseDotNet@2
     displayName: 'Use .NET SDK 6.0 for CredScan'

.azure-pipelines/util/analyze-steps.yml

@@ -27,7 +27,7 @@ steps:
     packageType: sdk
     version: 8.x
 
-- pwsh: 'Install-Module "platyPS", "PSScriptAnalyzer" -Force -Confirm:$false -Scope CurrentUser'
+- pwsh: 'Install-Module "Microsoft.PowerShell.PlatyPS", "PSScriptAnalyzer" -Force -Confirm:$false -Scope CurrentUser'
   displayName: 'Install PowerShell Dependencies'
 
 - task: PowerShell@2

.github/copilot-instructions.md

@@ -25,7 +25,7 @@ First-time setup requires these exact steps:
 - **CRITICAL**: Ensure you have network connectivity to Azure DevOps package feeds. Build failures with "Name or service not known" errors indicate firewall/connectivity issues that must be resolved before building.
 - Install .NET SDK 8.0+ and .NET Framework Dev Pack 4.7.2+: `dotnet --version` should show 8.0+
 - Install PowerShell 7+: `pwsh --version` should show 7.0+
-- Install platyPS module: `pwsh -c "Install-Module -Name platyPS -Force -Scope CurrentUser"`
+- Install Microsoft.PowerShell.PlatyPS module: `pwsh -c "Install-Module -Name Microsoft.PowerShell.PlatyPS -Force -Scope CurrentUser"`
 - Install PSScriptAnalyzer: `pwsh -c "Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser"`
 - Set PowerShell execution policy: `pwsh -c "Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope CurrentUser"`
 
@@ -110,7 +110,7 @@ If build appears to hang or shows no progress:
 - Builds may pause during package downloads or complex compilation steps
 
 ### Module-Specific Issues
-- Help generation requires platyPS module to be installed and functioning
+- Help generation requires Microsoft.PowerShell.PlatyPS module to be installed and functioning
 - Static analysis requires PSScriptAnalyzer module  
 - Some projects depend on specific Azure SDK versions from Azure DevOps feeds
 - Missing ChangeLog.md updates will cause PR validation to fail

documentation/development-docs/azure-powershell-developer-guide.md

@@ -50,7 +50,7 @@ The following prerequisites should be completed before contributing to the Azure
 
 - Install [Visual Studio 2022 or above](https://www.visualstudio.com/downloads/)
 - Install the latest version of [Git](https://git-scm.com/downloads)
-- Install the [`platyPS` module](help-generation.md#Installing-platyPS)
+- Install the [`Microsoft.PowerShell.PlatyPS` module](help-generation.md#Installing-MicrosoftPowerShellPlatyPS)
 - Install [PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer#installation)
 - Install [**.NET SDK 6, and .NET Framework Dev Pack 4.7.2**](https://dotnet.microsoft.com/en-us/download/dotnet) or greater
 - Install [PowerShell 7](https://github.com/PowerShell/PowerShell/releases/latest)
@@ -89,7 +89,7 @@ git pull upstream main
 
 ### Building the Environment
 
-_Note_: to build the environment locally, you need `platyPS` install on your machine. Please see the [Prerequisites](#prerequisites) section for details on how to install this module.
+_Note_: to build the environment locally, you need `Microsoft.PowerShell.PlatyPS` install on your machine. Please see the [Prerequisites](#prerequisites) section for details on how to install this module.
 
 After cloning the repository to your local machine, you want to ensure that you can build the environment. To do so, launch `VS Developer Command Prompt` (which is installed with Visual Studio) and run the following command (from the root of the repository) to do a full build:
 
@@ -105,7 +105,7 @@ PS C:\azure-powershell> dotnet msbuild build.proj
 
 ### Generating Help
 
-We build the `dll-Help.xml` files (used to display the help content for cmdlets in PowerShell) from markdown using the `platyPS` module. Since this help generation step can take 10-15 minutes, it is a separate part of the command line build process. Run this to generate help:
+We build the `dll-Help.xml` files (used to display the help content for cmdlets in PowerShell) from markdown using the `Microsoft.PowerShell.PlatyPS` module. Since this help generation step can take 10-15 minutes, it is a separate part of the command line build process. Run this to generate help:
 
 ```
 msbuild build.proj /t:GenerateHelp
@@ -153,7 +153,7 @@ Please submit a design review here: https://github.com/Azure/azure-powershell-cm
 
 _Note_: You will need to be part of the `GitHub Azure` org to see this repository. Please go to [this link](https://aka.ms/azuregithub) to become part of the `Azure` org.
 
-We recommend using the `platyPS` module to easily generate markdown files that contains the above information and including the files in the design submission.
+We recommend using the `Microsoft.PowerShell.PlatyPS` module to easily generate markdown files that contains the above information and including the files in the design submission.
 
 ### Point of Contact
 
@@ -243,7 +243,7 @@ To import modules automatically when debug has started, follow the below steps:
 
 All cmdlets that are created must have accompanying help that is displayed when users execute the command `Get-Help <your cmdlet>`.
 
-Each cmdlet has a markdown file that contains the help content that is displayed in PowerShell; these markdown files are created (and maintained) using the platyPS module.
+Each cmdlet has a markdown file that contains the help content that is displayed in PowerShell; these markdown files are created (and maintained) using the Microsoft.PowerShell.PlatyPS module.
 
 For complete documentation, see [`help-generation.md`](help-generation.md) in the `documentation` folder.
 

documentation/development-docs/help-generation.md

@@ -2,16 +2,16 @@
 
 ## Description
 
-All MAML files containing the help content for cmdlets have been removed from the Azure PowerShell repository and replaced with markdown files, which are generated and maintained using the [`platyPS`](https://github.com/PowerShell/platyPS) module. Each module has a `help` folder (_e.g.,_ `src/Accounts/Accounts/help`) which contains a markdown file for each of the cmdlets found in that given module. When the help content for a cmdlet (or multiple cmdlets) needs to be updated, users will now only have to update the contents of the markdown file, _and not the MAML file as well_.
+All MAML files containing the help content for cmdlets have been removed from the Azure PowerShell repository and replaced with markdown files, which are generated and maintained using the [`Microsoft.PowerShell.PlatyPS`](https://github.com/PowerShell/platyPS) module (v1.0+). Each module has a `help` folder (_e.g.,_ `src/Accounts/Accounts/help`) which contains a markdown file for each of the cmdlets found in that given module. When the help content for a cmdlet (or multiple cmdlets) needs to be updated, users will now only have to update the contents of the markdown file, _and not the MAML file as well_.
 
-## Installing `platyPS`
+## Installing `Microsoft.PowerShell.PlatyPS`
 
-In order to use the cmdlets necessary to update the markdown help files (or generate MAML help locally from these markdown files), you must first install the `platyPS` module mentioned previously.  You will need to install a minimum version of 0.11.0.
+In order to use the cmdlets necessary to update the markdown help files (or generate MAML help locally from these markdown files), you must first install the `Microsoft.PowerShell.PlatyPS` module mentioned previously. You will need to install a minimum version of 1.0.0.
 
-To do so, you can follow the below steps (which are outlined in the [**Quick start**](https://github.com/PowerShell/platyPS#quick-start) section of the `platyPS` README):
+To do so, you can follow the below steps:
 
 ```powershell
-Install-Module -Name platyPS -Scope CurrentUser
+Install-Module -Name Microsoft.PowerShell.PlatyPS -Scope CurrentUser
 ```
 
 **Note:** this module will need to be installed from the [PowerShell Gallery](http://www.powershellgallery.com/). If, for some reason, this isn't a registered repository when running the `Get-PSRepository` cmdlet, then you will need to register it by running the following command:
@@ -20,11 +20,11 @@ Install-Module -Name platyPS -Scope CurrentUser
 Register-PSRepository -Default -InstallationPolicy Trusted
 ```
 
-## Using `platyPS`
+## Using `Microsoft.PowerShell.PlatyPS`
 
 ### Importing your module
 
-Before you run the `platyPS` cmdlets to update your markdown help files, you will need to first import the module containing the changes that you have made to your cmdlets into your current PowerShell session. Once you have built your project (either through Visual Studio or with `msbuild`), you can locate the module manifest that you will need to import in the `artifacts/Debug` folder of your local repository.
+Before you run the `Microsoft.PowerShell.PlatyPS` cmdlets to update your markdown help files, you will need to first import the module containing the changes that you have made to your cmdlets into your current PowerShell session. Once you have built your project (either through Visual Studio or with `msbuild`), you can locate the module manifest that you will need to import in the `artifacts/Debug` folder of your local repository.
 
 For example, if you have made changes to the `Accounts` module, you will find the corresponding module manifest in `artifacts/Debug/Az.Accounts/Az.Accounts.psd1`.
 
@@ -43,7 +43,7 @@ For new modules with no existing `help` folder containing the markdown help file
 
 ```powershell
 $PathToHelpFolder = "../../help" # Full path to help folder containing markdown files to be generated (e.g., src/Accounts/Accounts/help)
-New-MarkdownHelp -Module {{moduleName}} -OutputFolder $PathToHelpFolder -AlphabeticParamsOrder -UseFullTypeName -WithModulePage
+New-MarkdownCommandHelp -ModuleInfo (Get-Module {{moduleName}}) -OutputFolder $PathToHelpFolder -WithModulePage
 ```
 
 Once this folder has been generated, follow the steps provided in the below section to update the files with any changes made to the public interface of the cmdlets.
@@ -65,55 +65,59 @@ Whenever the public interface for a cmdlet has changed, the corresponding markdo
 
 #### Updating all markdown files in a module
 
-To update all of the markdown files for a single module, use the [`Update-MarkdownHelpModule`](https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelpModule.md) cmdlet:
+To update all of the markdown files for a single module, use the `Update-MarkdownCommandHelp` and `Update-MarkdownModuleFile` cmdlets:
 
 ```powershell
 $PathToModuleManifest = "../../<module>.psd1" # Full path to the module manifest that you have updated
 Import-Module -Name $PathToModuleManifest
 
 $PathToHelpFolder = "../../help" # Full path to help folder containing markdown files to be updated
-Update-MarkdownHelpModule -Path $PathToHelpFolder -RefreshModulePage -AlphabeticParamsOrder -UseFullTypeName
-```
 
-If you would like to update the inputs/outputs for a markdown file, please run this cmdlet with the -UpdateInputOutput parameter.  Keep in mind that this will overwrite any customized descriptions of inputs and outputs, so you will need to add these descriptions back if still relevant.
+# Update individual command help markdown files
+Update-MarkdownCommandHelp -Path "$PathToHelpFolder/*-*.md"
+
+# Refresh the module page with updated command list
+$cmdHelp = Import-MarkdownCommandHelp -Path "$PathToHelpFolder/*-*.md"
+$moduleFile = Get-ChildItem -Path $PathToHelpFolder -Filter "Az.*.md" | Where-Object { $_.Name -notlike "*-*" } | Select-Object -First 1
+if ($moduleFile) { Update-MarkdownModuleFile -Path $moduleFile.FullName -CommandHelp $cmdHelp }
+```
 
-This will update all of the markdown files with public interface changes made to corresponding cmdlets, add markdown files for any new cmdlets, remove markdown files for any deleted cmdlets, and update the module page (_e.g.,_ `Az.Accounts.md`) with any added or removed cmdlets.
+This will update all of the markdown files with public interface changes made to corresponding cmdlets and update the module page (_e.g.,_ `Az.Accounts.md`) with any added or removed cmdlets.
 
 _This seems to work better when run from within the `help` folder itself (For e.g. to generate the help files for the [`Network`](https://github.com/Azure/azure-powershell/tree/main/src/Network) module run the cmd from under [`Commands.Network/help`](https://github.com/Azure/azure-powershell/tree/main/src/Network/Network/help)). Also, you will have to import the profile module from under <Repo base path>/artifacts/Debug/Az.Accounts/Az.Accounts.psd1_
 
 #### Updating a single markdown file
 
-To update a single markdown file with the changes made to the corresponding cmdlet, use the [`Update-MarkdownHelp`](https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelp.md) cmdlet:
+To update a single markdown file with the changes made to the corresponding cmdlet, use the `Update-MarkdownCommandHelp` cmdlet:
 
 ```powershell
 $PathToModuleManifest = "../../<module>.psd1" # Full path to the module manifest that you have updated
 Import-Module -Name $PathToModuleManifest
 
 $PathToMarkdownFile = "../../<cmdlet>.md" # Full path to the markdown file to be updated
-Update-MarkdownHelp -Path $PathToMarkdownFile -AlphabeticParamsOrder -UseFullTypeName
+Update-MarkdownCommandHelp -Path $PathToMarkdownFile
 ```
 
-If you would like to update the inputs/outputs for a markdown file, please run this cmdlet with the -UpdateInputOutput parameter.  Keep in mind that this will overwrite any customized descriptions of inputs and outputs, so you will need to add these descriptions back if still relevant.
-
 #### Generating and viewing the MAML help
 
 During the build, the MAML help will be generated from the markdown files in the repository. If you would like to generate the MAML help and preview what the help content will look like for each of your cmdlets, you can do so with two more commands.
 
-To generate the MAML help based on the contents of your markdown files, use the [`New-ExternalHelp`](https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelp.md) cmdlet:
+To generate the MAML help based on the contents of your markdown files, use the `Import-MarkdownCommandHelp` and `Export-MamlCommandHelp` cmdlets:
 
 ```powershell
 $PathToHelpFolder = "../../help" # Full path to help folder containing markdown files to be updated
 $PathToOutputFolder = "../../.." # Full path to folder where you want the MAML file to be generated
-New-ExternalHelp -Path $PathToHelpFolder -OutputPath $PathToOutputFolder
+$cmdHelp = Import-MarkdownCommandHelp -Path "$PathToHelpFolder/*-*.md"
+Export-MamlCommandHelp -CommandHelp $cmdHelp -OutputFolder $PathToOutputFolder
 ```
 
-To preview the help that you just generated, use the [`Get-HelpPreview`](https://github.com/PowerShell/platyPS/blob/master/docs/Get-HelpPreview.md) cmdlet:
+To preview the help that you just generated, use the `Show-HelpPreview` cmdlet:
 
 ```powershell
 $PathToMAML = "../../<maml>.dll-Help.xml" # Full path to the MAML file that was generated
 
 # Save the help locally
-$help = Get-HelpPreview -Path $PathToMAML
+$help = Show-HelpPreview -Path $PathToMAML
 
 # Get the help for a specific cmdlet
 $help | where { $_.Name -eq "<cmdlet>" }

documentation/development-docs/sdkbased-vs-autogen.md

@@ -78,7 +78,7 @@ Generally speaking, hero scenarios are implemented through customization through
 
 ### SDK-based Module
 
-Docs are generated through playPS, please see [platyPS](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/help-generation.md#Installing-platyPS) for details. And developers should populate generated docs with examples.
+Docs are generated through Microsoft.PowerShell.PlatyPS, please see [Microsoft.PowerShell.PlatyPS](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/help-generation.md#Installing-MicrosoftPowerShellPlatyPS) for details. And developers should populate generated docs with examples.
 
 ### Auto-gen Module
 

documentation/tooling/static-analysis.md

@@ -93,7 +93,7 @@ The dependency analyzer can be found in the [`DependencyAnalyzer`](https://githu
 The help analyzer can be found in the [`HelpAnalyzer`](https://github.com/Azure/azure-powershell/tree/01a81fbb7ea6c086fff2bc137053168c0fc7728a/tools/StaticAnalysis/HelpAnalyzer) folder. In this folder, you will find the following classes:
 
 - `HelpAnalyzer`
-    - The implementation of the `IStaticAnalyzer` interface; determines which modules to analyze and checks to see which cmdlets within those modules don't have a corresponding markdown help file. It also checks the content structure of markdown help conforms to [PlatyPS Schema](https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md)
+    - The implementation of the `IStaticAnalyzer` interface; determines which modules to analyze and checks to see which cmdlets within those modules don't have a corresponding markdown help file. It also checks the content structure of markdown help conforms to [PlatyPS Schema](https://github.com/PowerShell/platyPS) using the `Microsoft.PowerShell.PlatyPS` module
 - `HelpIssues`
     - The implementation of the `IReportRecord` interface; defines what a help exception looks like when it's reported in the `HelpIssues.csv` file that is found in the build artifacts of a CI run, as well as how to compare a new record to a record found in the existing `HelpIssues.csv` file used for exception suppressions
 

src/StorageSync/Tools/storageSyncDevops.psm1

@@ -96,16 +96,19 @@ function Update-StorageSyncHelp
     $status = $null
     try 
     {
-        Write-Verbose "Re-Loading module: platyPS"
-        if (Get-Module platyPS)
+        Write-Verbose "Re-Loading module: Microsoft.PowerShell.PlatyPS"
+        if (Get-Module Microsoft.PowerShell.PlatyPS)
         {
-            Remove-Module platyPS
+            Remove-Module Microsoft.PowerShell.PlatyPS
         }
-        Import-Module platyPS
+        Import-Module Microsoft.PowerShell.PlatyPS
 
         $PathToHelpFolder = Join-Path (Get-RepositoryRootDirectory) "src\StorageSync\StorageSync\help"
         Write-Verbose "Updating help: $PathToHelpFolder"
-        $status = Update-MarkdownHelpModule -Path $PathToHelpFolder -RefreshModulePage -AlphabeticParamsOrder -UseFullTypeName
+        Update-MarkdownCommandHelp -Path "$PathToHelpFolder\*-*.md"
+        $updatedHelp = Import-MarkdownCommandHelp -Path "$PathToHelpFolder\*-*.md"
+        $moduleFile = Get-ChildItem -Path $PathToHelpFolder -Filter "Az.StorageSync.md" | Select-Object -First 1
+        if ($moduleFile) { $status = Update-MarkdownModuleFile -Path $moduleFile.FullName -CommandHelp $updatedHelp }
     }
     finally
     {

tools/Az.Tools.Installer/GenerateHelp.ps1

@@ -1,4 +1,4 @@
-#Requires -Modules platyPS
+#Requires -Modules Microsoft.PowerShell.PlatyPS
 [CmdletBinding()]
 Param(
     [Parameter()]
@@ -10,5 +10,6 @@ Param(
 $ModuleFolder = Join-Path -Path $ArtifactFolder -ChildPath $ModuleName
 $TempDocFolder = Join-Path -Path $ModuleFolder -ChildPath 'help'
 Import-Module $ModuleFolder
-New-MarkdownHelp -Module $ModuleName -OutputFolder $TempDocFolder -Force
-New-ExternalHelp –Path $TempDocFolder -OutputPath $ModuleFolder -Force
+New-MarkdownCommandHelp -ModuleInfo (Get-Module $ModuleName) -OutputFolder $TempDocFolder -Force
+$cmdHelp = Import-MarkdownCommandHelp -Path (Join-Path $TempDocFolder '*-*.md')
+Export-MamlCommandHelp -CommandHelp $cmdHelp -OutputFolder $ModuleFolder -Force