Merge pull request #164 from MicrosoftDocs/main

8/23/2023 PM Publish

reference/docfx.json

@@ -15,16 +15,8 @@
     "externalReference": [],
     "fileMetadata": {
       "author": {
-        "**/Microsoft.PowerShell.Crescendo/**.md": "JamesWTruher",
-        "**/Microsoft.PowerShell.Crescendo/**.yml": "JamesWTruher",
-        "**/Microsoft.PowerShell.SecretManagement/**.yml": "PaulHigin",
-        "**/Microsoft.PowerShell.SecretStore/**.yml": "PaulHigin",
-        "**/PlatyPS/**.md": "adityapatwardhan",
-        "**/PlatyPS/**.yml": "adityapatwardhan",
-        "**/PSScriptAnalyzer/**.yml": "JamesWTruher",
-        "**/PSDesiredStateConfiguration/**.md": "sdwheeler",
-        "**/PSDesiredStateConfiguration/**.yml": "sdwheeler",
-        "docs-conceptual/**.md": "sdwheeler"
+        "**/**.md": "sdwheeler",
+        "**/**.yml": "sdwheeler"
       },
       "feedback_product_url": {
         "ps-modules/Microsoft.PowerShell.Crescendo/**.md": "https://github.com/PowerShell/Crescendo/issues/new/choose",
@@ -39,16 +31,8 @@
         "**/**": "mkluck"
       },
       "ms.author": {
-        "**/Microsoft.PowerShell.Crescendo/**.md": "jimtru",
-        "**/Microsoft.PowerShell.Crescendo/**.yml": "jimtru",
-        "**/Microsoft.PowerShell.SecretManagement/**.yml": "paulhi",
-        "**/Microsoft.PowerShell.SecretStore/**.yml": "paulhi",
-        "**/PlatyPS/**.md": "adityap",
-        "**/PlatyPS/**.yml": "adityap",
-        "**/PSScriptAnalyzer/**.yml": "jimtru",
-        "**/PSDesiredStateConfiguration/**.md": "sewhee",
-        "**/PSDesiredStateConfiguration/**.yml": "sewhee",
-        "docs-conceptual/**.md": "sewhee"
+        "**/**.md": "sewhee",
+        "**/**.yml": "sewhee"
       },
       "ms.prod": {
         "**/**.md": "powershell",

reference/docs-conceptual/Crescendo/advanced/handling-errors.md

@@ -1,6 +1,6 @@
 ---
 description: This article describes how to handle native command errors in your Crescendo output handler.
-ms.date: 06/28/2023
+ms.date: 08/23/2023
 title: Handling errors in Crescendo
 ---
 # Handling errors in Crescendo
@@ -21,6 +21,13 @@ Crescendo v1.1 adds two internal functions to manage errors.
 - `Pop-CrescendoNativeError` removes an error from the error queue. Use this function to inspect
   errors in the output handler so you can handle them or pass them through to the caller.
 
+By default, `$PSNativeCommandUseErrorActionPreference` is set to `$true`. This causes Crescendo to
+produce an additional error record for every error. To prevent this, Crescendo changes the value to
+`$false` for each generated cmdlet. This change is scoped to your cmdlets in the generated module, so
+it doesn't affect cmdlets outside of the module.
+
+## Returning errors to the user
+
 The following output handler definition uses `Pop-CrescendoNativeError` to return errors to the
 user.
 
@@ -107,7 +114,7 @@ fizztool.exe v1.0.0 (c) 2021 Tailspin Toys, Ltd.
 ERROR: Key not found: buzz
 ```
 
-## Handling the errors in Crescendo
+### Handling the errors in Crescendo
 
 The following Crescendo configuration defines the cmdlet `Get-FizzBuzz` that calls the
 `fizztool.exe`, processes the output, and handles error conditions.
@@ -171,7 +178,7 @@ The `FizzToolParser` function does the following actions:
   - You could inspect the errors and handle them or pass them through to the caller, as shown in the
     function.
 
-## Using the new cmdlet
+### Using the new cmdlet
 
 ```powershell
 Get-FizzBuzz -Key fizz

reference/docs-conceptual/Crescendo/get-started/create-new-cmdlet.md

@@ -1,24 +1,24 @@
 ---
 description: How to create a Crescendo cmdlet.
-ms.date: 06/28/2023
+ms.date: 08/23/2023
 title: Create a Crescendo cmdlet
 ---
 # Create a Crescendo cmdlet
 
-Modern command-line tools provide commands for effective management of domain-specific
-technologies. Administrative users can confidently execute these commands inside of PowerShell and
-get the expected results. However, PowerShell users prefer the syntax, readability, and object-based
-output that cmdlets provide, especially in automation.
+Modern command-line tools provide commands for effective management of domain-specific technologies.
+Administrative users can confidently execute these commands inside of PowerShell and get the
+expected results. However, PowerShell users prefer the syntax, readability, and object-based output
+that cmdlets provide, especially in automation.
 
 As previously discussed, there are several reasons you may want to amplify a command-line tool:
 
 - The string output is difficult to use in automation
 - The command syntax is difficult to use or remember
 - The tool lacks informative help documentation
 
-In the [previous article](research-tool.md), we discussed how to discover and choose the feature of
-the tool that you want to amplify with Crescendo. For the examples in this article, we continue to
-use the `azcmagent` command-line tool that was previously introduced.
+In the [previous article][04], we discussed how to discover and choose the feature of the tool that
+you want to amplify with Crescendo. For the examples in this article, we continue to use the
+`azcmagent` command-line tool that was previously introduced.
 
 ## Creating the configuration for a Crescendo cmdlet
 
@@ -117,13 +117,12 @@ an array to contain the cmdlet definitions. The output from `New-CrescendoComman
 }
 ```
 
-It is important to have the schema link in the Crescendo configuration file. The schema provides
-tools like [Visual Studio Code](https://code.visualstudio.com) with IntelliSense and tooltips during
-the authoring experience.
+It's important to have the schema link in the Crescendo configuration file. The schema provides
+tools like [Visual Studio Code][02] with IntelliSense and tooltips during the authoring experience.
 
 ## Completing the Crescendo command configuration
 
-In this example, we are creating a configuration for the `azcmagent show` command. The cmdlet
+In this example, we're creating a configuration for the `azcmagent show` command. The cmdlet
 doesn't require any additional parameters. Since `azcmagent` is a modern tool that provides JSON
 output, the example includes a simple output handler to convert the JSON output to objects.
 
@@ -133,9 +132,9 @@ The command definition includes the following properties:
 - **Noun**: The name of the cmdlet noun
 - **Platform**: The platform that this Crescendo command run on (Windows, Linux, MacOS)
 - **OriginalName**: The original native command name and location
-- **OriginalCommandElements**: Some CLI commands have additional mandatory switches to execute
-  properly for a given scenario
-- **Description**: Description for the cmdlet that is seen in Help
+- **OriginalCommandElements**: Some command-line tools have additional mandatory switches for a
+  given scenario
+- **Description**: Description for the cmdlet that's seen in Help
 - **Aliases**: An alias, or short name, for the new cmdlet
 - **OutputHandlers**: The output handler that captures the string output from the command-line tool
   and transforms it into PowerShell objects
@@ -156,7 +155,7 @@ The following example shows the full JSON definition of the new cmdlet after add
          "--json"
       ],
       "Platform": [
-        "Windows",
+        "Windows"
       ],
       "Description": "Gets machine metadata and Agent status. This is primarily useful for troubleshooting.",
       "Aliases": [
@@ -193,9 +192,9 @@ A parameter definition includes the following properties:
 - **Name**: This is the name of the PowerShell parameter for the generated cmdlet
 - **OriginalName**: The name of the parameter
 - **ParameterType**: Defines the data type of the parameter value
-- **ParameterSetName**: Defines which parameter set this parameter is included
+- **ParameterSetName**: Defines which parameter set this parameter belongs to
 - **Mandatory**: Setting that determines if the parameter is required to have a value
-- **Description**: Description for the parameter that is seen in Help
+- **Description**: Description for the parameter that's seen in Help
 
 The following example shows the full JSON definition of the new cmdlet. You can put this to a
 definition in a new JSON file or add it to the **Commands** array of the previous JSON file.
@@ -236,17 +235,22 @@ definition in a new JSON file or add it to the **Commands** array of the previou
     "SupportsShouldProcess": false,
     "SupportsTransactions": false,
     "NoInvocation": false,
-    "Parameters": [],
     "Examples": []
 }
 ```
 
 For a more detailed configuration example, see the blog post
-[https://devblogs.microsoft.com/powershell-community/a-closer-look-at-the-crescendo-configuration/](https://devblogs.microsoft.com/powershell-community/a-closer-look-at-the-crescendo-configuration/).
+[A closer look at the Crescendo configuration][03].
 
 ## Next steps
 
 Now that you have defined your cmdlets, you are ready to generate your new module.
 
 > [!div class="nextstepaction"]
-> [Generate and test your module](generate-module.md)
+> [Generate and test your module][01]
+
+<!-- link references -->
+[01]: generate-module.md
+[02]: https://code.visualstudio.com
+[03]: https://devblogs.microsoft.com/powershell-community/a-closer-look-at-the-crescendo-configuration/
+[04]: research-tool.md

reference/docs-conceptual/Crescendo/get-started/generate-module.md

@@ -1,16 +1,16 @@
 ---
 description: How to generate a Crescendo module from a configuration.
-ms.date: 06/28/2023
+ms.date: 08/23/2023
 title: Generate and test a Crescendo module
 ---
 # Generate and test a Crescendo module
 
-In the [previous article](create-new-cmdlet.md) we created configurations for two new cmdlets. Using
-this configuration, Crescendo can generate a new PowerShell script module.
+In the [previous article][01] we created configurations for two new cmdlets. Using this
+configuration, Crescendo can generate a new PowerShell script module.
 
 ## Generate your new module
 
-Now we are ready to create your module. Use the `Export-CrescendoModule` cmdlet to generate the new
+Now you're ready to create your module. Use the `Export-CrescendoModule` cmdlet to generate the new
 PowerShell script module.
 
 ```powershell
@@ -21,9 +21,9 @@ The **ConfigurationFile** can take an array of filenames. This allows you to cre
 files for each cmdlet. The **ModuleName** parameter specifies the full path and filename for the
 module file being created. In this example, the files are being created in the current directory.
 
-As seen the the following output, `Export-CrescendoModule` creates two files -- the module (PSM1)
-file and the module manifest (PSD1) file. These are the only files that end user of your module
-needs to install.
+As seen the following output, `Export-CrescendoModule` creates two files -- the module (PSM1) file
+and the module manifest (PSD1) file. These are the only files that end user of your module needs to
+install.
 
 ```output
     Directory: D:\temp\azcmagent
@@ -142,10 +142,5 @@ Get-AzCmAgentConfigProperty True               False
 > for privilege elevation for all platforms. However, we didn't include elevation in our
 > configuration examples.
 
-## Upcoming articles
-
-We are still working on more documentation for Crescendo. Check back for new content that covers the
-following topics:
-
-- Creating cmdlets that require privilege elevation
-- Packaging your module for distribution
+<!-- link references -->
+[01]: create-new-cmdlet.md

reference/docs-conceptual/Crescendo/get-started/install-crescendo.md

@@ -1,6 +1,6 @@
 ---
 description: How to install the Crescendo module.
-ms.date: 06/28/2023
+ms.date: 08/23/2023
 title: Installing Crescendo
 ---
 # Install the Crescendo module
@@ -9,18 +9,24 @@ Requirements:
 
 **Microsoft.PowerShell.Crescendo** requires PowerShell 7.0 or higher.
 
-Crescendo can be used to create modules that run on Windows PowerShell 5.1 and newer.
+Crescendo can create modules that run on Windows PowerShell 5.1 and newer.
 
 To install using **PowerShellGet 2.x**:
 
 ```powershell
+# Install the current release
 Install-Module Microsoft.PowerShell.Crescendo -Force
+# Install the preview release
+Install-Module Microsoft.PowerShell.Crescendo -AllowPrerelease -Force
 ```
 
-To install using **PowerShellGet 3.0** (beta):
+To install using **Microsoft.PowerShell.PSResourceGet** (beta):
 
 ```powershell
+# Install the current release
 Install-PSResource Microsoft.PowerShell.Crescendo -Reinstall
+# Install the preview release
+Install-PSResource Microsoft.PowerShell.Crescendo -Prerelease -Reinstall
 ```
 
 The **Force** or **Reinstall** parameters are only necessary when you have an older version of
@@ -38,4 +44,7 @@ Using the **Force** parameter ensures that you get the latest available help con
 ## Next step
 
 > [!div class="nextstepaction"]
-> [Choose the command-line tool to wrap](choose-command-line-tool.md)
+> [Choose the command-line tool to wrap][01]
+
+<!-- link references -->
+[01]: choose-command-line-tool.md

reference/docs-conceptual/Crescendo/get-started/research-tool.md

@@ -1,27 +1,26 @@
 ---
 description: How to collect information about the command-line tool to decide which features to implement in your cmdlets.
-ms.date: 06/28/2023
+ms.date: 08/23/2023
 title: Research the command-line tool's syntax and output
 ---
 # Research the command-line tool's syntax and output
 
-The [previous article](choose-command-line-tool.md) provided criteria for selecting the command-line
-tool you want to amplify with Crescendo. In this article we describe ways to collect information
-about the tool that helps you design cmdlets using Crescendo.
+The [previous article][03] provided criteria for selecting the command-line tool you want to amplify
+with Crescendo. In this article we describe ways to collect information about the tool that helps
+you design cmdlets using Crescendo.
 
 For the examples in this article, we use the Azure Connected Machine agent tool (`azcmagent`). We
 chose this tool because:
 
-- It is easy to install and remove
+- It's easy to install and remove
 - It doesn't require an active Azure subscription for basic usage
 - It has useful in-console help and online documentation
 - It produces easily consumable output
 
 > [!TIP]
 > If you don't have this tool, you don't need to install it unless you want to try out the examples.
 >
-> For more information, see the [Installing the azcmagent tool](#installing-the-azcmagent-tool)
-> section of this article.
+> For more information, see the [Installing the azcmagent tool][02] section of this article.
 
 ## Start with command-line help and documentation
 
@@ -117,9 +116,8 @@ Extension Service extensionservice running
 Agent Service     himds            running
 ```
 
-For more complex examples of parsing output, see this
-[blog post](https://devblogs.microsoft.com/powershell-community/a-closer-look-at-the-parsing-code-of-a-crescendo-output-handler/)
-from the PowerShell Community blog.
+For more complex examples of parsing output, see this [blog post][06] from the PowerShell Community
+blog.
 
 > [!NOTE]
 > The `azcmagent` tool must be run with Administrative privilege. This also means that the module
@@ -130,16 +128,24 @@ from the PowerShell Community blog.
 You can download the Azure Connected Machine agent package for Windows and Linux from the locations
 listed below.
 
-- Download the Windows Installer package for the
-  [Windows agent](https://aka.ms/AzureConnectedMachineAgent) from the Microsoft Download Center.
-- The Linux agent is distributed from Microsoft's
-  [package repository](https://packages.microsoft.com/). Choose the preferred package format for the
-  distribution (RPM or DEB).
+- Download the Windows Installer package for the [Windows agent][05] from the Microsoft Download
+  Center.
+- The Linux agent is distributed from Microsoft's [package repository][07]. Choose the preferred
+  package format for the distribution (RPM or DEB).
 
 For more information about the Azure Connected Machine agent, see
-[Managing and maintaining the Connected Machine agent](/azure/azure-arc/servers/manage-agent).
+[Managing and maintaining the Connected Machine agent][01].
 
 ## Next step
 
 > [!div class="nextstepaction"]
-> [Create a cmdlet configuration](create-new-cmdlet.md)
+> [Create a cmdlet configuration][04]
+
+<!-- link references -->
+[01]: /azure/azure-arc/servers/manage-agent
+[02]: #installing-the-azcmagent-tool
+[03]: choose-command-line-tool.md
+[04]: create-new-cmdlet.md
+[05]: https://aka.ms/AzureConnectedMachineAgent
+[06]: https://devblogs.microsoft.com/powershell-community/a-closer-look-at-the-parsing-code-of-a-crescendo-output-handler/
+[07]: https://packages.microsoft.com/