From 189de05d9b0946c7efcbe1167a403f59f2bf4af7 Mon Sep 17 00:00:00 2001 From: Chris Davis Date: Thu, 18 Sep 2025 14:24:25 -0700 Subject: [PATCH] New/Update cmdlet article updates For the new version of platyPS --- repo_docs/NEW_CMDLETS.md | 300 ++++++++++++++++++++++-------------- repo_docs/UPDATE_CMDLETS.md | 122 +++++++-------- 2 files changed, 236 insertions(+), 186 deletions(-) diff --git a/repo_docs/NEW_CMDLETS.md b/repo_docs/NEW_CMDLETS.md index fbbbaaefc1..fe55aa0699 100644 --- a/repo_docs/NEW_CMDLETS.md +++ b/repo_docs/NEW_CMDLETS.md @@ -1,40 +1,64 @@ -# Create new cmdlet topics +# Create new cmdlet articles -Cmdlet reference topics follow a very strict schema that's difficult to duplicate manually (remember, the topics on the web are also used for `Get-Help` from the command line). Instead, you use the open-source [platyPS](https://github.com/PowerShell/platyPS) tool to export the cmdlet and all of its properties to a markdown (.md) file from your PowerShell connection to the server or service. +Cmdlet reference articles follow a strict schema that's difficult to duplicate manually. The articles on the web are also used for `Get-Help` from the command line. Instead, you use the open-source [platyPS](https://github.com/PowerShell/platyPS) tool to export the cmdlet and all of its properties to a markdown (.md) file from the required PowerShell module or your PowerShell connection to the server or service. -## Step 1: Install platyPS +> [!NOTE] +> +> - In August 2025, the new version of platyPS was released, which changed the cmdlet and parameter metadata requirements of cmdlet reference articles, and also dropped support for single-sourcing cmdlet reference articles (no more **Merge-MarkdownHelp** cmdlet or an equivalent). +> - If you have an older 14.x version of platyPS installed (check by running `Get-InstalledModule`), uninstall it by running the following command in an elevated PowerShell window: `Uninstall-Module platyPS -AllVersions -Force`. +> - platyPS version 14.x still works, but the markdown files it creates require more manual updates to the cmdlet and parameter metadata. In Exchange and Security & Compliance PowerShell, platyPS 14.x better supports single-sourcing cmdlet reference articles (the **Merge-MarkdownHelp** cmdlet is still available). +> - To install platyPS v14.2 on older versions of Windows, see the [Install platyPS on older versions of Windows](#install-platyps-on-older-versions-of-windows) section at the end of this article.> +> - To install platyPS v14.2 on really old versions of Windows, see the [Install platyPS on really old versions of Windows](#install-platyps-on-older-versions-of-windows) section at the end of this article. -On Windows 10, Windows Server 2016, or later, run the following command in an elevated Windows PowerShell window (a Windows PowerShell window you open by selecting **Run as administrator**): +## Step 1: Install platyPS on current versions of Windows -```powershell -Install-Module -Name platyPS -Scope CurrentUser -``` +1. In PowerShell 5.1, do the following steps in an elevated Windows PowerShell window (a Windows PowerShell window you open by selecting **Run as administrator**). If you're using PowerShell 7, you can skip this step. + + Run the command `Get-InstalledModule` to verify you have the following modules installed: + + - `Microsoft.PowerShell.PSResourceGet` + - `PowerShellGet` v2.2.5 or later (required for `Microsoft.PowerShell.PSResourceGet`). + + If necessary, run the following commands to install `Microsoft.PowerShell.PSResourceGet`: + + ```powershell + Update-Module -Name PowerShellGet + + Install-Module -Name Microsoft.PowerShell.PSResourceGet + ``` -If you need to install platyPS on old versions of Windows (Windows 8.1 or Windows 2012 R2 or earlier), you need to install Windows PowerShell 5.1 before you can install platyPS. For instructions, see the [Install platyPS on older versions of Windows](#install-platyps-on-older-versions-of-windows) section at the end of this article. +2. To install the platyPS module, run the following command: -If you need to install platyPS on really old versions of Windows (a server running a product that lacks support for WMF 5.1 or its requirements), see the [Install platyPS on really old versions of Windows](#install-platyps-on-older-versions-of-windows) section at the end of this article. + ```powershell + Install-PSResource -Name Microsoft.PowerShell.PlatyPS + ``` -You need platyPS v0.14.0 or later (released April 2019). If you have an earlier version of platyPS installed, close all open Windows PowerShell windows where the platyPS module is currently loaded and then run `Update-Module platyPS` from a new elevated Windows PowerShell window. Or, run the command `Remove-Module platyPS` and then run `Install-Module -Name platyPS -Scope CurrentUser` to get the current version. + > [!TIP] + > To prevent the prompt about the PowerShell Gallery not being trusted, run the following command: + > + > ```powershell + > Set-PSRepository -Name PSGallery -InstallationPolicy Trusted + > ``` ## Step 2: Connect to the PowerShell environment that has the cmdlet -You probably know how to do this already, but the available workloads and connection methods are: +You probably know how to connect, but the available workloads and connection methods are: - Microsoft Teams: [Install Microsoft Teams PowerShell](https://learn.microsoft.com/MicrosoftTeams/teams-powershell-install) > [!TIP] - > Use `Upgrade-Module` and also `Uninstall-Module` depending on the module version you have installed. + > Use `Upgrade-Module` and also `Uninstall-Module` depending on the module version you installed. - Exchange: - Exchange Online PowerShell: [Connect to Exchange Online PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-online-powershell) - Security & Compliance PowerShell: [Connect to Security & Compliance PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-scc-powershell) - - Exchange Online Protection PowerShell: [Connect to Exchange Online Protection PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-online-protection-powershell) + - Exchange Online Protection PowerShell for on-premises email organizations: [Connect to Exchange Online PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-online-powershell) - Exchange Server PowerShell: [Connect to Exchange servers using remote PowerShell](https://learn.microsoft.com/powershell/exchange/connect-to-exchange-servers-using-remote-powershell) > [!TIP] > You might need to connect to the service in an elevated Windows PowerShell prompt (Teams and Exchange environments don't require an elevated Windows PowerShell prompt). The connection instructions article should plainly state this and other connection requirements. > -> In Exchange and Security & Compliance PowerShell environments, the cmdlets that are available to you are controlled by role-based access control (RBAC). Most cmdlets and parameters are available to administrators by default, but some aren't (for example, the "Mailbox Search" and "Mailbox Import Export" roles. +> In Exchange and Security & Compliance PowerShell environments, role-based access control (RBAC) controls the available cmdlets. Most cmdlets and parameters are available to administrators by default, but some aren't (for example, the "Mailbox Search" and "Mailbox Import Export" roles. > > Remote PowerShell connections are deprecated in Exchange Online PowerShell and Security & Compliance PowerShell in favor of REST API connections. For more information, see the following articles: > @@ -46,7 +70,7 @@ You probably know how to do this already, but the available workloads and connec ## Step 3: Load platyPS in the PowerShell environment -After you've connected in PowerShell to the server or service (either in a regular Windows PowerShell window or from a specific PowerShell console shortcut), you likely don't need to do anything to make the platyPS cmdlets available to you in your session. However, it you're having issues, run the following command to manually load the platyPS module: +After you connect in PowerShell to the server or service (either in a regular Windows PowerShell window or from a specific PowerShell console shortcut), you likely don't need to do anything to make the platyPS cmdlets available to you in your session. However, if you have issues, run the following command to manually load the platyPS module: ```powershell Import-Module platyPS @@ -54,196 +78,224 @@ Import-Module platyPS ### Step 4: Find your module name -> [!NOTE] -> This step is required only if you're interested in creating cmdlet reference articles for **all** available cmdlets in the product (using the _Module_ parameter in `New-MarkdownHelp`). If you're going to manually specify the cmdlet names (using the _Command_ parameter in `New-MarkdownHelp`), you can skip this step. +> [!TIP] +> This step is required only if you're interested in creating cmdlet reference articles for **all** available cmdlets in the product (using the _ModuleInfo_ parameter in **New-MarkdownCommandHelp**). If you're going to manually specify the cmdlet names (using the _CommandInfo_ parameter in **New-MarkdownCommandHelp**), you can skip this step. -platyPS needs the name of the loaded PowerShell module or snap-in that contains the cmdlets you want to update. To find the name, run the following command: +platyPS needs the name of the loaded PowerShell module or snap-in that contains the cmdlets you want to update. To find the module name, run the following command: ```powershell Get-Module | Format-Table -Auto ``` -The command returns all of the currently loaded modules or snap-ins, and the output will resemble this: +The command returns all of the currently loaded modules or snap-ins as shown in the following example output: ```powershell ModuleType Version Name ExportedCommands ---------- ------- ---- ---------------- -Manifest 3.1.0.0 Microsoft.PowerShell.Management {Add-Computer, Add-Content, Checkpoint-Computer, Clear-Con... -Manifest 3.0.0.0 Microsoft.PowerShell.Security {ConvertFrom-SecureString, ConvertTo-SecureString, Get-Acl... +Manifest 3.1.0.0 Microsoft.PowerShell.Management {Add-Computer, Add-Content, Checkpoint-Computer, Clear-Con...} +Manifest 3.0.0.0 Microsoft.PowerShell.Security {ConvertFrom-SecureString, ConvertTo-SecureString, Get-Acl...} Manifest 3.1.0.0 Microsoft.PowerShell.Utility {Add-Member, Add-Type, Clear-Variable, Compare-Object...} -Binary 1.0.0.1 PackageManagement {Find-Package, Find-PackageProvider, Get-Package, Get-Pack... -Script 2.2.5 PowerShellGet {Find-Command, Find-DscResource, Find-Module, Find-RoleCap... -Script 2.0.0 PSReadline {Get-PSReadlineKeyHandler, Get-PSReadlineOption, Remove-PS... -Script 1.0 tmp_byivwzpq.e1k {Add-AvailabilityAddressSpace, Add-DistributionGroupMember... +Binary 1.0.0.1 PackageManagement {Find-Package, Find-PackageProvider, Get-Package, Get-Pack...} +Script 2.2.5 PowerShellGet {Find-Command, Find-DscResource, Find-Module, Find-RoleCap...} +Script 2.0.0 PSReadline {Get-PSReadlineKeyHandler, Get-PSReadlineOption, Remove-PS...} +Script 1.0 tmp_byivwzpq.e1k {Add-AvailabilityAddressSpace, Add-DistributionGroupMember...} ``` -or this: +Or the following example output: ```powershell ModuleType Version Name ExportedCommands ---------- ------- ---- ---------------- Manifest 3.1.0.0 Microsoft.PowerShell.Management {Add-Computer, Add-Content, Checkpoint-Computer, Clear-Content...} Manifest 3.1.0.0 Microsoft.PowerShell.Utility {Add-Member, Add-Type, Clear-Variable, Compare-Object...} -Script 4.2.0 MicrosoftTeams {Add-TeamChannelUser, Add-TeamUser, Connect-MicrosoftTeams, Disconnect-Microso... +Script 4.2.0 MicrosoftTeams {Add-TeamChannelUser, Add-TeamUser, Connect-MicrosoftTeams, Disconnect-Microso...} Script 1.4.7 PackageManagement {Find-Package, Find-PackageProvider, Get-Package, Get-PackageProvider...} Script 2.2.5 PowerShellGet {Find-Command, Find-DscResource, Find-Module, Find-RoleCapability...} -Script 2.0.0 PSReadline {Get-PSReadLineKeyHandler, Get-PSReadLineOption, Remove-PSReadLineKeyHandler, ... +Script 2.0.0 PSReadline {Get-PSReadLineKeyHandler, Get-PSReadLineOption, Remove-PSReadLineKeyHandler, ...} ``` -For services that use remote connections (Exchange), the module name is a temporary value that changes every time you connect. In the example output, the module name is `tmp_byivwzpq.e1k`, but yours will be different. +For services that use remote connections (Exchange), the module name is a temporary value that changes every time you connect. In the example output, the module name for the Exchange Online PowerShell session is `tmp_byivwzpq.e1k`. For Microsoft Teams, the module name is always `MicrosoftTeams`. Either way, take note of your module name. You'll need it in the next steps. -### Step 5: Run platyPS to generate topic files +### Step 5: Run platyPS to generate article files You have two choices: -- **Dump _all_ cmdlets in the module/snap-in to files**: This is simple but could take a while, and you'll end up with dozens or possibly hundreds of cmdlet files you don't need. The basic syntax is: +- **Dump _all_ cmdlets in the module/snap-in to files**: This method is simple but could take a while, and you end up with dozens or possibly hundreds of cmdlet files you don't need. The basic syntax is: ```powershell - New-MarkdownHelp -Module -OutputFolder " + New-MarkdownCommandHelp -ModuleInfo (Get-Module -Name ) -OutputFolder "" ``` -- **Dump specific cmdlets to files**: This is a bit harder to set up, but the output is much quicker, and there are no extra topic files created. The basic syntax is: +- **Dump specific cmdlets to files**: This method is a bit harder to set up, but the output is quicker, and no extra article files are created. The basic syntax is: ```powershell - New-MarkdownHelp -Command -OutputFolder " + New-MarkdownCommandHelp -CommandInfo (Get-Command ) -OutputFolder "" ``` or ```powershell - $x = "","",..."" + $x = Get-Command "","",..."" - New-MarkdownHelp -Command $x -OutputFolder " + New-MarkdownHelp -Command $x -OutputFolder "" ``` **Notes**: - \ is the value you found in [Step 4](#step-4-find-your-module-name) (for example, `tmp_byivwzpq.e1k` or `MicrosoftTeams`). - -- If the \ location doesn't exist, it's created for you. +- If the \ location doesn't exist, the folder structure is created for you. +- Regardless of the method you use, the \ value is automatically appended to the _OutputFolder_ value you specify. #### Dump all cmdlets in the module/snap-in to files -This example creates topic files for all available cmdlets in the Microsoft Teams module `MicrosoftTeams` in the folder C:\My Docs\Teams. +This example creates article files for all available cmdlets in the Microsoft Teams module `MicrosoftTeams` in the folder C:\My Docs\Teams. ```powershell -New-MarkdownHelp -Module MicrosoftTeams -OutputFolder "C:\My Docs\Teams" +New-MarkdownCommandHelp -ModuleInfo (Get-Module -Name MicrosoftTeams) -OutputFolder "C:\My Docs\Teams" ``` #### Dump specific cmdlets to files -This example creates a topic file for the cmdlet named **Get-CoolFeature** in the Exchange Online PowerShell session in the folder "C:\My Docs\ExO". +- This example creates an article file for the cmdlet named **Get-CoolFeature** in the Exchange Online PowerShell session in the folder "C:\My Docs\ExO". -```powershell -New-MarkdownHelp -Command "Get-CoolFeature" -OutputFolder "C:\My Docs\ExO" -``` + ```powershell + New-MarkdownCommandHelp -CommandInfo (Get-Command "Get-CoolFeature") -OutputFolder "C:\My Docs\ExO" + ``` -This example creates topic files for the **Get-CoolFeature**, **New-CoolFeature**, **Remove-CoolFeature**, and **Set-CoolFeature** cmdlets from the Exchange Online session in the folder C:\My Docs\ExO. +- This example creates article files for the **Get-CoolFeature**, **New-CoolFeature**, **Remove-CoolFeature**, and **Set-CoolFeature** cmdlets from the Exchange Online session in the folder C:\My Docs\ExO. -The first command stores the cmdlet names in a variable. The second command uses that variable to identify the cmdlets and write the output files. + The first command stores the cmdlet names in a variable. The second command uses that variable to identify the cmdlets and write the output files. -```powershell -$NewCmdlets = "Get-CoolFeature","New-CoolFeature","Remove-CoolFeature","Set-CoolFeature" + ```powershell + $NewCmdlets = Get-Command "Get-CoolFeature","New-CoolFeature","Remove-CoolFeature","Set-CoolFeature" -New-MarkdownHelp -Command $NewCmdlets -OutputFolder "C:\My Docs\ExO" -``` + New-MarkdownCommandHelp -CommandInfo $NewCmdlets -OutputFolder "C:\My Docs\ExO" + ``` ### Step 6: Document the new cmdlet -Now that you have topic files for the new cmdlets, you can actually document them. The topics are plain text UTF-8 files that are formatted using [markdown](https://guides.github.com/features/mastering-markdown/). Office writers use [Visual Studio Code](https://code.visualstudio.com/) to edit topic files, but you can use Notepad or your favorite text editor. +Now that you have article files for the new cmdlets, you can actually document them. The articles are plain text UTF-8 files that are formatted using [markdown](https://guides.github.com/features/mastering-markdown/). Writers use [Visual Studio Code](https://code.visualstudio.com/) to edit article files, but you can use Notepad or your favorite text editor. -These are the basic topic elements that require your attention, regardless of the product or service: +These basic article elements require your attention, regardless of the product or service: - **The SYNOPSIS section**: Be brief. Use the DESCRIPTION section for less critical information. - **The DESCRIPTION section**: More details (for example, permissions required to run the cmdlet) -- **One or more code examples in the EXAMPLES section**: The code block (only one code block) goes first, then the description text. +- **One or more code examples in the EXAMPLES section**: The code block goes first (only one code block per example), then the description text. - **A description for every parameter in each parameter section** +- **Cmdlet and parameter metadata** -We highly encourage you to plagiarize existing content and formatting from other cmdlet topics in the product or service. Many parameters are common across a wide variety of cmdlets. +We highly encourage you to plagiarize existing content and formatting from other cmdlet articles in the product or service. Many parameters are common across a wide variety of cmdlets. -#### Metadata in the new cmdlet +#### Cmdlet metadata -Less obvious but still important information that's often manually required in every topic is **cmdlet metadata** at the top of the topic and **parameter metadata** in every parameter section. +platyPS automatically populates the metadata of every cmdlet reference article it creates. Some properties are required, some aren't, and some are missing that you need to add manually. Also, depending on whether the cmdlet is new or previously documented, the property values might be populated, blank, correct, or incorrect. -##### Cmdlet metadata +The following example shows the cmdlet metadata from the default output of a **New-MarkdownCommandHelp** command for a new, undocumented cmdlet: -Every cmdlet reference topic needs (at a minimum) the following properties in the metadata field at the top of the reference article: +```yaml +--- +document type: cmdlet +external help file: tmpEXO_xaympem4.exn-Help.xml +HelpUri: '' +Locale: en-US +Module Name: tmpEXO_xaympem4.exn +ms.date: 09/18/2025 +PlatyPS schema version: 2024-05-01 +title: Get-PrivacyManagementComplianceCaseMember +--- +``` -```text -external help file: Microsoft.OutlookApps.StaffHub.PowershellCmdlets.dll-Help.xml -Module Name: Microsoft.OutlookApps.StaffHub.PowershellCmdlets -online version: https://learn.microsoft.com/powershell/module/skype/add-cssladelegates -applicable: Skype for Business Server 2015 -title: Add-CsSlaDelegates -author: -ms.author: -ms.reviewer: -manager: +The following example shows what the cmdlet metadata should look like for publication in (other products might use or require different values): + +```yaml +--- +applicable: Security & Compliance +author: chrisda +external help file: Microsoft.Exchange.RecordsandEdge-Help.xml +Locale: en-US +Module Name: ExchangePowerShell +ms.author: chrisda +online version: https://learn.microsoft.com/powershell/module/exchangepowershell/get-privacymanagementcompliancecasemember schema: 2.0.0 +title: Get-PrivacyManagementComplianceCaseMember +--- ``` -- **external help file**: Defines which MAML/XML file the cmdlet help topic goes in for `Get-Help` at the command line. This value very product-specific, and the location is specified somewhere in product code. Some products (Skype) use only one XML file that's well-known and the same for all cmdlets; others (Exchange) use multiple XML files. See other topics for available values. Don't guess; a wrong value here will affect the availability of the help topic at the command line. +The properties and values are explained in the following list: -- **Module Name**: In Exchange topics, this value is `ExchangeOnlineManagement` for those few cmdlets that are [baked into the Exchange Online PowerShell V3 module itself](https://learn.microsoft.com/powershell/exchange/exchange-online-powershell-v2#cmdlets-in-the-exchange-online-powershell-module). For other products, this is the module name of the product. +- **applicable (Exchange/Skype/Teams only)**: Notice the property name starts with a lowercase 'a.' You need to manually add this property and value. See other cmdlet reference articles for available values. Don't guess or invent new values. The value must come from the list of predefined values. -- **online version**: This is the URL of the topic. This URL value is what makes the `Get-Help -Online` command work, so it's very important. +- **author**: The GitHub alias of the person who owns the article. You need to manually add this property and value. The value could be a writer, program manager, or developer. -- **applicable**: You need to add this attribute and value yourself. Notice that it starts with a lowercase 'a'. See other topics for available values. Don't invent new values here. The value **must** come from the list of predefined values. +- **external help file**: Defines which MAML XML file the cmdlet help article goes in for `Get-Help` at the command line. If the cmdlet is baked directly into the module, the automatically populated value is likely correct. If the cmdlet is from a remote session (Exchange/Skype/Teams), you need to manually add this value. -- **title**: You need to add this attribute and value yourself. This is simply the name of the cmdlet. + The value is specified somewhere in product code. Some products (Skype) use only one XML file that's well-known and the same for all cmdlets. Other products (Exchange) use multiple XML files. See other articles for available values. Don't guess. An incorrect value affects the availability of the help article at the command line. -- **schema**: This value is always 2.0.0 in all products. +- **Locale**: The value is `en-US` and is automatically populated. -- **author**: The GitHub alias of the person that owns this topic. Usually the PM or sometimes a dev that owns the cmdlet. +- **Module Name**: This value must match the folder name where the cmdlet reference articles live in GitHub and learn.microsoft.com. If that value happens to match the module name, the original value is correct. Otherwise, you need to manually add this value. Don't guess or invent new values. An incorrect/unavailable value causes build error when you try to check in the new article on GitHub. -- **ms.author**: The Microsoft alias of the same author. +- **online version**: The live URL of the article when published. This URL value is used by `Get-Help -Online`. For new cmdlet articles, this value is blank. You can refer to other published articles to get the correct URL path. The cmdlet name is unique to this article. -- **ms.reviewer**: The Microsoft alias of someone that can approve any technical changes (if different than the author). +- **ms.author**: The Microsoft alias of the author. -- **manager**: The Microsoft alias of a manager for the team that owns the cmdlet. This is useful if the person that owns the cmdlet leaves the company. The manager will be reached to in order to find the new author. +- **schema**: This value is always 2.0.0 in all products. + +- **title**: This value is the name of the cmdlet and is automatically populated. -##### Parameter metadata +#### Parameter metadata -Here's an example of the parameter metadata that's present in every parameter section: +platyPS automatically populates the metadata for every parameter. Here's an example of the parameter metadata that's present in every parameter section: -```text +```yaml +--- Type: String Parameter Sets: (All) Aliases: -Applicable: Microsoft StaffHub Required: False Position: 1 Default value: None Accept pipeline input: False Accept wildcard characters: False +--- ``` -Most of the attributes and values are generated automatically by platyPS. The ones that require manual intervention are: +Most autogenerated property values are correct, but the following properties require manual intervention: - **Type**: In any environment, the values `Object` or `Object[]` are wrong. As previously described, REST API connections in the Exchange Online PowerShell V3 module incorrectly identify many parameter **Type** values as `Object` or `Object[]`. Other values like `String`, `Boolean`, and `DateTime` are detected correctly. The true parameter type values are visible in product code. -- **Applicable**: You need to add this attribute and value yourself. Notice the capital 'A'. See other topics for available values (same available values as the **applicable** attribute at the top of the topic). Don't invent new values here. The value **must** come from the list of predefined values. +- **Default value** and **Accept wildcard characters**: These properties are present, but platyPS or any other PowerShell utility is unable to truthfully populate the values (the values are always None and False, respectively). You can correct the values if you think it's important. + +- As of August 2025, parameter metadata no longer supports the **Applicable** property (notice the uppercase 'A'). For Exchange/Skype/Teams cmdlets, you now add the **Applicable** property and value in the description text of the parameter. for example: -- **Default value** and **Accept wildcard characters**: These attributes are present, but the values are never truthfully populated by platyPS **or any other PowerShell utility** (they're always None and False, respectively). You can correct the values if you think it's important. Otherwise, leave them as is. + ```text + ... -### Step 8: Add the new cmdlet topic files to the repository + ### -Identity -When you're done editing the topics, upload them to GitHub. Note that you need to fork the repo, upload your files to your fork, and then submit a Pull Request. + > Applicable: Security & Compliance + + ... + ``` + + See other articles for available values (select from the same available values as the **applicable** attribute in the cmdlet metadata). Don't guess or invent new values. The value must come from the list of predefined values. + +### Step 8: Add the new cmdlet article files to the repository + +When you're done editing the articles, upload them to GitHub. You need to fork the repo, upload your files to your fork, and then submit a Pull Request. 1. Go to the correct location in the appropriate GitHub repository: - - Exchange: - - Office Web Apps: - - Skype: - - StaffHub: + - Exchange: + - Office Web Apps: + - Skype: - Teams: - - Whiteboard: - - SharePoint / OneDrive: + - Whiteboard: 2. Select **Add file** \> **Upload files** @@ -252,13 +304,13 @@ When you're done editing the topics, upload them to GitHub. Note that you need t 3. After you're done adding files, go to the **Propose changes** section at the bottom of the page: - A brief title is required. By default, the title is the name of the file, but you can change it. - - Optionally, you can enter more details in the **Add an optional extended description** box. You should @ include the GitHub alias of someone who can review and approve your upload. + - Optionally, you can enter more details in the **Add an optional extended description** box. @ include the GitHub alias of someone who can review and approve your upload. - When you're ready, click the green **Propose changes** button. + When you're ready, select the green **Propose changes** button. ![Propose file change section.](../images/propose-file-change.png) -4. On the **Open a pull request** page that appears, click the green **Create pull request** button. +4. On the **Open a pull request** page that appears, select the green **Create pull request** button. ![Open a pull request page.](../images/open-a-pull-request-page.png) @@ -268,24 +320,24 @@ When you're done editing the topics, upload them to GitHub. Note that you need t Add the cmdlet to Table of Contents (TOC) file in the GitHub repo. TOC file is the name of the module. For example: -- Exchange +- Exchange > [!TIP] - > Exchange also uses pseudo folders to organize cmdlets. You need to add any new cmdlets in the proper location in the file: . + > Exchange also uses pseudo folders to organize cmdlets. You need to add any new cmdlets in the proper location in the file: . -- Office Web Apps: +- Office Web Apps: -- Skype: +- Skype: -- StaffHub: +- SharePoint Migration Tool: -- Teams: +- Teams: -- Whiteboard: +- Whiteboard: -In the TOC file, you can fill in a description or remove the template text line. However, if you leave the template text line make sure it's in _exactly_ the right format so it won't render as a template text. +In the TOC file, you can fill in a description or remove the template text line. However, if you leave the template text line make sure it's in _exactly_ the right format so it doesn't render as template text. -The steps to edit and publish the TOC file are identical to modifying any existing topic. The instructions are [here](https://github.com/MicrosoftDocs/office-docs-powershell/blob/main/README.md) (you're starting at Step 4). +The steps to edit and publish the TOC file are identical to modifying any existing article. The instructions are [here](https://github.com/MicrosoftDocs/office-docs-powershell/blob/main/README.md) (you're starting at Step 4). ## Appendix @@ -302,24 +354,36 @@ The steps to edit and publish the TOC file are identical to modifying any existi ### Install platyPS on older versions of Windows > [!NOTE] -> The procedures in this section aren't required in current versions of Windows (Windows 10, Windows Server 2016, or later) or other versions of Windows where the WMF 5.1 is already installed. +> The procedures in this section aren't required in versions of Windows where the WMF 5.1 is included: +> +> - Windows 11 +> - Windows 10 Anniversary Update (version 1607 from August 2016) or later +> - Windows Server 2022 +> - Windows Server 2019 +> - Windows Server 2016 -The following older versions of Windows don't automatically include Windows PowerShell 5.1, but they support it. You need to download and install the Windows Management Framework (WMF) 5.1 from on these versions of Windows: +The following older versions of Windows don't automatically include Windows PowerShell 5.1, but they support it. You need to download and install the Windows Management Framework (WMF) 5.1 from on these versions of Windows: - Windows 8.1 - Windows Server 2012 or Windows Server 2012 R2 -- Windows 7 Service Pack 1 (SP1)1,2 -- Windows Server 2008 R2 SP11,2 +- Windows 7 Service Pack 1 (SP1)¹ ² +- Windows Server 2008 R2 SP1¹ ² + +- ¹ Windows PowerShell 5.1 on this version of Windows requires the .NET Framework 4.5 or later. +- ² You can't use this version of Windows to connect to Exchange Online PowerShell or Security & Compliance PowerShell. Although you can install version 2.0.3 of the ExchangeOnlineManagement module, this version of the module lacks support for REST API connections. -- 1 This version of Windows has reached its end of support, and is now supported only in Azure virtual machines. -- 2 Windows PowerShell 5.1 on this version of Windows requires the .NET Framework 4.5 or later. For more information, see [Windows Management Framework 5.1](https://aka.ms/wmf5download). +Now you can install platyPS v14.2 on the target computer by running the following command: + +```powershell +Install-Module -Name platyPS -Scope CurrentUser +``` ### Install platyPS on really old versions of Windows (WMF 3.0 or 4.0) > [!NOTE] -> The procedures in this section aren't required in current versions of Windows (Windows 10, Windows Server 2016, or later) or other versions of Windows where the WMF 5.1 is already installed. +> The procedures in this section aren't required for the previously described versions of Windows where the WMF 5.1 is included or installable. -To install platyPS for use with products that require PowerShell 3.0 or 4.0 and don't initially have access to the **Install-Module** cmdlet, do the steps in this section. +To install platyPS 14.x for use with products that require PowerShell 3.0 or 4.0 and don't initially have access to the **Install-Module** cmdlet, do the steps in this section. 1. Download and install PowerShellGet. The steps are described in [Installing PowerShellGet](https://learn.microsoft.com/powershell/scripting/gallery/installing-psget) and are summarized here as follows: @@ -332,7 +396,7 @@ To install platyPS for use with products that require PowerShell 3.0 or 4.0 and ) ``` - b. On another computer running PowerShell 5.1 or later where PowerShellGet is installed and working, open an elevated Windows PowerShell window and run the following command: + b. On another computer running PowerShell 5.1 or later where PowerShellGet is installed and working, run the following command from an elevated Windows PowerShell window: ```powershell Save-Module PowerShellGet -Path "" @@ -340,7 +404,7 @@ To install platyPS for use with products that require PowerShell 3.0 or 4.0 and Where \ is **an existing** folder/path that's easy to find (for example, `C:\Temp\PSG`). - c. The command will create two new folders in the target path: + c. The command creates two new folders in the target path: - `PackageManagement\\` - `PowerShellGet\\` @@ -350,12 +414,12 @@ To install platyPS for use with products that require PowerShell 3.0 or 4.0 and - `PackageManagement\` - `PowerShellGet\` -2. On the target computer, delete the following folders or move them to a remote location for safekeeping: +2. On the target computer, delete the following folders or move them to a backup location: - `C:\Program Files\WindowsPowerShell\Modules\PackageManagement` - `C:\Program Files\WindowsPowerShell\Modules\PowerShellGet` -3. Copy the `PackageManagement` and `PowerShellGet` folders that you downloaded and fixed in Step 1b to `C:\Program Files\WindowsPowerShell\Modules` on the target computer. +3. Copy the `PackageManagement` and `PowerShellGet` folders that you downloaded and fixed in Step 1 to `C:\Program Files\WindowsPowerShell\Modules` on the target computer. You should have the following folders on the target computer: @@ -368,7 +432,7 @@ To install platyPS for use with products that require PowerShell 3.0 or 4.0 and Set-PSRepository -Name PSGallery -InstallationPolicy Trusted ``` -5. Now you can finally install platyPS on the target computer by running the usual command: +5. Now you can install platyPS v14.2 on the target computer by running the following command: ```powershell Install-Module -Name platyPS -Scope CurrentUser diff --git a/repo_docs/UPDATE_CMDLETS.md b/repo_docs/UPDATE_CMDLETS.md index 0f89ae5ffa..c844b8c304 100644 --- a/repo_docs/UPDATE_CMDLETS.md +++ b/repo_docs/UPDATE_CMDLETS.md @@ -1,6 +1,6 @@ -# Update existing cmdlet topics +# Update existing cmdlet articles -Manually adding new parameters to a cmdlet reference topic is doable, but there are several obstacles to overcome: +Manually adding new parameters to a cmdlet reference article is doable, but there are several obstacles to overcome: - **Add the parameter and Type value to the SYNTAX block(s)**: Easy to do if there's only one, but what if there are multiple SYNTAX blocks (also known as parameter sets)? Does the new parameter go in one, some, or all of them? And what about the parameter Type value (String? `$true | $ false`? A finite list of values?) @@ -8,25 +8,26 @@ Manually adding new parameters to a cmdlet reference topic is doable, but there The reality is: you almost always need the open-source [platyPS](https://github.com/PowerShell/platyPS) tool to automatically answer the unknowns about new parameters. -Currently, the best method with platyPS is to simply create a new version of the topic using the **New-MarkdownHelp** cmdlet, and copy whatever you need out of it. Theoretically, platyPS has an **Update-MarkdownHelp** cmdlet that automatically updates an existing local copy of the topic for you, which you can then upload in its entirety to the GitHub website to replace the existing topic. This approach currently has some issues in our environment: +Currently, the best method with platyPS is to create a new version of the article using the **New-MarkdownCommandHelp** cmdlet, and copy whatever you need out of it. Theoretically, platyPS has an **Update-MarkdownCommandHelp** cmdlet that automatically updates an existing local copy of the article for you, which you can then upload in its entirety to the GitHub website to replace the existing article. This approach currently has some issues in our environment: -- It's difficult to get a local copy of an existing cmdlet topic from the GitHub website (unless you're interested in forking the repo and having a local cloned copy on your computer). You have to copy/paste everything from the Raw view of the topic on the web site, and the local copy text file you manually create needs to be UTF-8 formatted (instead of the Notepad default of ANSI). +- It's difficult to get a local copy of an existing cmdlet article from the GitHub website (unless you're interested in forking the repo and having a local cloned copy on your computer). + - You need to copy/paste everything from the Raw view of the article on the web site. + - You need to manually create a local text file that's UTF-8 formatted (instead of the Notepad default of ANSI). +- The updated article has missing or incorrect _unrelated_ parameter and cmdlet metadata information that you copy/paste _from_ the existing article on GitHub back into your local article. -- The updated topic will have missing or incorrect _unrelated_ parameter and other topic metadata information that you'll need to change by copy/pasting those values _back from_ the existing topic on GitHub into your local topic before you can even think about uploading the updated topic to GitHub (more than double the work required). +In short, it's easier and faster to generate a new local copy of the cmdlet article, and copy/paste only what you need into the existing article on GitHub. -In short, it's simply easier and faster to generate a new local copy of the cmdlet topic, and copy/paste only what you need into the existing topic on GitHub. +Removing parameters from articles is a manual exercise, but this article explains the process fully. -Removing parameters from topics is a manual exercise, but we'll explain the process fully. - -## Use platyPS to add new cmdlets to existing topics +## Use platyPS to add new cmdlets to existing articles ### Step 1: Install platyPS -The steps are the same as [Create new cmdlet topics](NEW_CMDLETS.md#step-1-install-platyps). +The steps are the same as in [Create new cmdlet articles](NEW_CMDLETS.md#step-1-install-platyps-on-current-versions-of-windows). ### Step 2: Connect to the PowerShell environment that has the cmdlet -You probably know how to do this already, but the available workloads and connection methods are also described in [Create new cmdlet topics](NEW_CMDLETS.md#step-2-connect-to-the-powershell-environment-that-has-the-cmdlet). +You probably know how to connect, but the available workloads and connection methods are also described in [Create new cmdlet articles](NEW_CMDLETS.md#step-2-connect-to-the-powershell-environment-that-has-the-cmdlet). > [!NOTE] > Remote PowerShell connections are deprecated in Exchange Online PowerShell and Security & Compliance PowerShell in favor of REST API connections. For more information, see the following articles: @@ -39,113 +40,98 @@ You probably know how to do this already, but the available workloads and connec ### Step 3: Load platyPS in the PowerShell environment -After you've connected in PowerShell to the server or service (either in a regular Windows PowerShell window or from a specific PowerShell console shortcut), run the following command to make the platyPS cmdlets available in your session: +After you connect in PowerShell to the server or service (either in a regular Windows PowerShell window or from a specific PowerShell console shortcut), run the following command to make the platyPS cmdlets available in your session: ```powershell -Import-Module platyPS +Import-Module Microsoft.PowerShell.PlatyPS ``` ### Step 4: Use New-MarkdownHelp to dump the latest version of the cmdlet to a file -These instructions are the same (up to a point) as in [Create new cmdlet topics](NEW_CMDLETS.md): +These instructions are the same (up to a point) as in [Create new cmdlet articles](NEW_CMDLETS.md): The basic syntax is: ```powershell -New-MarkdownHelp -Command -OutputFolder " +New-MarkdownCommandHelp -Command (Get-Command -Name ) -OutputFolder " ``` -or +Or ```powershell -$x = "","",..."" +$x = Get-Command "","",..."" -New-MarkdownHelp -Command $x -OutputFolder " +New-MarkdownCommandHelp -CommandInfo $x -OutputFolder " ``` -This example create a topic file for the updated cmdlet named **Get-CoolFeature** in the Exchange Online PowerShell session in the folder "C:\My Docs\ExO". +This example creates an article file for the updated cmdlet named **Get-CoolFeature** in the Exchange Online PowerShell session in the folder "C:\My Docs\ExO". ```powershell -New-MarkdownHelp -Command "Get-CoolFeature" -OutputFolder "C:\My Docs\ExO" +New-MarkdownCommandHelp -Command (Get-Command "Get-CoolFeature") -OutputFolder "C:\My Docs\ExO" ``` -This example creates topic files for the updated cmdlets **Get-CoolFeature**, **New-CoolFeature**, **Remove-CoolFeature**, and **Set-CoolFeature** from the Exchange Online session in the folder C:\My Docs\ExO. +This example creates article files for the updated cmdlets **Get-CoolFeature**, **New-CoolFeature**, **Remove-CoolFeature**, and **Set-CoolFeature** from the Exchange Online session in the folder C:\My Docs\ExO. The first command stores the cmdlet names in a variable. The second command uses that variable to identify the cmdlets and write the output files. ```powershell $Delta = "Get-CoolFeature","New-CoolFeature","Remove-CoolFeature","Set-CoolFeature" -New-MarkdownHelp -Command $Delta -OutputFolder "C:\My Docs\ExO" +New-MarkdownCommandHelp -CommandInfo $Delta -OutputFolder "C:\My Docs\ExO" ``` ### Step 5: Document the new parameters -The resulting topics are plain text UTF-8 files that are formatted using [markdown](https://guides.github.com/features/mastering-markdown/). Office writers use [Visual Studio Code](https://code.visualstudio.com/) to edit topic files, but you can use Notepad or your favorite text editor. - -1. Find the new parameter(s) in the SYNTAX block and the parameter sections. - -2. Add a parameter description. We highly encourage you to plagiarize existing content and formatting from other cmdlet topics. Many parameters are common across a wide variety of cmdlets. - -3. Create/fill out the parameter metadata like other existing parameters in the topic. - - Here's an example of the parameter metadata that's present in every parameter section: +The resulting articles are plain text UTF-8 files that are formatted using [markdown](https://guides.github.com/features/mastering-markdown/). Office writers use [Visual Studio Code](https://code.visualstudio.com/) to edit article files, but you can use Notepad or your favorite text editor. - ```yaml - Type: String - Parameter Sets: (All) - Aliases: - Applicable: Microsoft StaffHub +1. Find the new parameters in the SYNTAX block and the parameter sections. - Required: False - Position: 1 - Default value: None - Accept pipeline input: False - Accept wildcard characters: False - ``` +2. Add a parameter description. We highly encourage you to plagiarize existing content and formatting from other cmdlet articles. Many parameters are common across a wide variety of cmdlets. - Most of the attributes and values are generated automatically by platyPS. The ones that require manual intervention are: +3. Create/fill out the parameter metadata like other existing parameters in the article. For a complete description, see [Parameter metadata](NEW_CMDLETS.md#parameter-metadata). - - **Type**: In any environment, the values `Object` or `Object[]` are wrong. As previously described, REST API connections in the Exchange Online PowerShell V3 module incorrectly identify many parameter **Type** values as `Object` or `Object[]`. Other values like `String`, `Boolean`, and `DateTime` are detected correctly. The true parameter type values are visible in product code. +### Step 6: Copy your changes into the existing article on GitHub - - **Applicable**: You need to add this attribute and value yourself. Notice the capital 'A'. See other topics for available values (same available values as the **applicable** attribute at the top of the topic). Don't invent new values here. The value **must** come from the list of predefined values. +1. Go to the cmdlet articles location in the appropriate GitHub repository: - - **Default value** and **Accept wildcard characters**: These attributes are present, but the values are never truthfully populated by platyPS **or any other PowerShell utility** (they're always None and False, respectively). You can correct the values if you think it's important. Otherwise, leave them as is. + - Exchange: + - Office Web Apps: + - Skype: + - Teams: + - Whiteboard: -### Step 6: Copy your changes into the existing topic on GitHub +2. Find the existing article and select **Edit this file**. -1. Go to the cmdlet topics location in the appropriate GiHub repository: +3. Copy/paste your updates (and only your updates) from your new, local copy of the article into the existing article (select the **Preview** tab to see what they look like). - - Exchange: - - Office Web Apps: - - Skype: - - StaffHub: - - Teams: - - Whiteboard: + > [!IMPORTANT] + > The layout of headings and subheadings follow a specific schema required for **Get-Help** in PowerShell. As little as one text character in the wrong place can throw errors in the Pull Request. Look at currently publish cmdlet reference articles for formatting and text examples. -2. Find the existing topic and click **Edit**. +4. At this point, the steps are identical to [Learn how to contribute](../README.md), but you're starting at Step 4. -3. Copy/paste your updates (and only your updates) from your new, local copy of the topic into the existing topic (click the **Preview** tab to see what they'll look like). +## Remove existing parameters from existing articles - > [!IMPORTANT] - > The layout of headings and subheadings must follow a very specific schema that is required for PowerShell Get-Help. Any deviation will throw errors in the Pull Request. The schema can be found here: . +Removing parameters is a search and destroy mission in the existing articles on GitHub using the basic [Editing instructions](../README.md). -4. At this point, the steps are identical to [Short URL: aka.ms/office-powershell](../README.md) (You're starting at Step 4). +The most important thing to remember: a parameter isn't gone until it's truly not available to customers. If a parameter is still available, it needs to remain in the article until the parameter is removed from customer view in product code. -## Remove existing parameters from existing topics +The following reasons aren't sufficient to remove an available parameter from a cmdlet reference article: -Removing parameters is a search and destroy mission in the existing topics on GitHub, using the basic [Editing Instructions](../README.md). +- The parameter is going away "at some point in the future." +- The parameter doesn't work correctly. +- The parameter isn't supposed to be available. Possible exceptions to this rule are: + - The parameter name itself gives something away. + - The parameter is available only to an extremely limited number of Preview customers. -The most important thing to remember: a parameter isn't gone until it's truly not available to customers. If a parameter is still available, but it's going away "in the future", it doesn't work correctly anymore, or isn't supposed to be available, it needs to remain in the topic until the product code is actually changed to remove the parameter. Until then, you can use this type of language for the parameter description: +Don't delete parameters in this state. Instead, use the following language for the description: - This parameter is reserved for internal Microsoft use. +- This parameter is deprecated and no longer used. -- This parameter has been deprecated and is no longer used. - -Hear me now, believe me later: Removing available parameters from a cmdlet reference topic can create as many issues as their removal is supposed to solve. +Removing an available parameter from a cmdlet reference article can create as many issues as the removal is supposed to solve. -After you've confirmed that the parameter in question is really gone, find and remove all references to the parameter in the topic: +After you confirm the parameter in question is really gone, find and remove all references to the parameter in the article: -- The SYNTAX block(s) -- Examples +- SYNTAX blocks. +- Examples. - The individual parameter sections where each parameter is described. Be sure to delete the whole section including the \`\`\`yaml part at the end (don't leave trailing \`\`\`, which is easy to do).