From cb27fdfac1ee9133dc365da650a769da0ed03940 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 5 May 2026 10:42:52 -0500 Subject: [PATCH 1/2] Merge pull request #392 from sdwheeler/sdw-w575907-crescendo Add deprecation notice for Crescendo --- .../Crescendo/advanced/handling-errors.md | 2 ++ .../Crescendo/advanced/transforming-arguments.md | 2 ++ .../Crescendo/advanced/using-crescendo-cmdlets.md | 2 ++ .../Crescendo/get-started/choose-command-line-tool.md | 2 ++ .../Crescendo/get-started/create-new-cmdlet.md | 2 ++ .../Crescendo/get-started/generate-module.md | 2 ++ .../Crescendo/get-started/install-crescendo.md | 2 ++ .../Crescendo/get-started/research-tool.md | 2 ++ reference/docs-conceptual/Crescendo/overview.md | 2 ++ .../Crescendo/whats-new/whats-new-in-crescendo-11.md | 2 ++ reference/includes/crescendo-deprecated.md | 11 +++++++++++ .../About/about_Crescendo.md | 2 ++ .../Export-CrescendoCommand.md | 2 ++ .../Export-CrescendoModule.md | 2 ++ .../Microsoft.PowerShell.Crescendo/Export-Schema.md | 2 ++ .../Import-CommandConfiguration.md | 2 ++ .../Microsoft.PowerShell.Crescendo.md | 2 ++ .../New-CrescendoCommand.md | 2 ++ .../Microsoft.PowerShell.Crescendo/New-ExampleInfo.md | 2 ++ .../New-OutputHandler.md | 2 ++ .../New-ParameterInfo.md | 2 ++ .../Microsoft.PowerShell.Crescendo/New-UsageInfo.md | 2 ++ .../Test-IsCrescendoCommand.md | 3 +++ 23 files changed, 56 insertions(+) create mode 100644 reference/includes/crescendo-deprecated.md diff --git a/reference/docs-conceptual/Crescendo/advanced/handling-errors.md b/reference/docs-conceptual/Crescendo/advanced/handling-errors.md index a158b72b..8b187d9d 100644 --- a/reference/docs-conceptual/Crescendo/advanced/handling-errors.md +++ b/reference/docs-conceptual/Crescendo/advanced/handling-errors.md @@ -5,6 +5,8 @@ title: Handling errors in Crescendo --- # Handling errors in Crescendo +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + Prior to Crescendo 1.1, native command errors were streamed directly to the user, not captured by Crescendo. This prevented you from creating enhanced error handling. Now, Crescendo can capture error output (stderr) from the native command. diff --git a/reference/docs-conceptual/Crescendo/advanced/transforming-arguments.md b/reference/docs-conceptual/Crescendo/advanced/transforming-arguments.md index 4ebf2ebf..098fd46c 100644 --- a/reference/docs-conceptual/Crescendo/advanced/transforming-arguments.md +++ b/reference/docs-conceptual/Crescendo/advanced/transforming-arguments.md @@ -5,6 +5,8 @@ title: Transforming arguments in Crescendo --- # Transforming arguments in Crescendo +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + There are many scenarios where the input values handed to a Crescendo wrapped command must be translated to a different format for the underlying native command. Crescendo 1.1 added two new members to the **Parameter** class, `ArgumentTransform` and `ArgumentTransformType` to support these diff --git a/reference/docs-conceptual/Crescendo/advanced/using-crescendo-cmdlets.md b/reference/docs-conceptual/Crescendo/advanced/using-crescendo-cmdlets.md index 69476f06..dbb07f31 100644 --- a/reference/docs-conceptual/Crescendo/advanced/using-crescendo-cmdlets.md +++ b/reference/docs-conceptual/Crescendo/advanced/using-crescendo-cmdlets.md @@ -5,6 +5,8 @@ title: Create a Crescendo configuration using the Crescendo cmdlets --- # Create a Crescendo configuration using the Crescendo cmdlets +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + The Crescendo module includes a set of cmdlets that create various Crescendo object types. You can use these cmdlets to create a Crescendo configuration without the need to manually edit a JSON file. diff --git a/reference/docs-conceptual/Crescendo/get-started/choose-command-line-tool.md b/reference/docs-conceptual/Crescendo/get-started/choose-command-line-tool.md index 8b7f54ed..1a427fde 100644 --- a/reference/docs-conceptual/Crescendo/get-started/choose-command-line-tool.md +++ b/reference/docs-conceptual/Crescendo/get-started/choose-command-line-tool.md @@ -5,6 +5,8 @@ title: Choosing a command-line tool to amplify --- # Choosing the command-line tool for Crescendo +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + Using Crescendo is a rapid, reliable way to _amplify_ a command-line tool to produce a cmdlet-like experience. Many times, the tool you need to work with is directly tied to the technology you are attempting to automate. This makes the tool choice simple. However, not all tools work the same way. diff --git a/reference/docs-conceptual/Crescendo/get-started/create-new-cmdlet.md b/reference/docs-conceptual/Crescendo/get-started/create-new-cmdlet.md index a28571ab..dfce2741 100644 --- a/reference/docs-conceptual/Crescendo/get-started/create-new-cmdlet.md +++ b/reference/docs-conceptual/Crescendo/get-started/create-new-cmdlet.md @@ -5,6 +5,8 @@ title: Create a Crescendo cmdlet --- # Create a Crescendo cmdlet +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + 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 diff --git a/reference/docs-conceptual/Crescendo/get-started/generate-module.md b/reference/docs-conceptual/Crescendo/get-started/generate-module.md index 8f753642..cf70e26d 100644 --- a/reference/docs-conceptual/Crescendo/get-started/generate-module.md +++ b/reference/docs-conceptual/Crescendo/get-started/generate-module.md @@ -5,6 +5,8 @@ title: Generate and test a Crescendo module --- # Generate and test a Crescendo module +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + In the [previous article][01] we created configurations for two new cmdlets. Using this configuration, Crescendo can generate a new PowerShell script module. diff --git a/reference/docs-conceptual/Crescendo/get-started/install-crescendo.md b/reference/docs-conceptual/Crescendo/get-started/install-crescendo.md index db8d5a18..dfb8195d 100644 --- a/reference/docs-conceptual/Crescendo/get-started/install-crescendo.md +++ b/reference/docs-conceptual/Crescendo/get-started/install-crescendo.md @@ -5,6 +5,8 @@ title: Installing Crescendo --- # Install the Crescendo module +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + Requirements: **Microsoft.PowerShell.Crescendo** requires PowerShell 7.0 or higher. diff --git a/reference/docs-conceptual/Crescendo/get-started/research-tool.md b/reference/docs-conceptual/Crescendo/get-started/research-tool.md index 2ad6daa7..4947131a 100644 --- a/reference/docs-conceptual/Crescendo/get-started/research-tool.md +++ b/reference/docs-conceptual/Crescendo/get-started/research-tool.md @@ -5,6 +5,8 @@ title: Research the command-line tool's syntax and output --- # Research the command-line tool's syntax and output +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + 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. diff --git a/reference/docs-conceptual/Crescendo/overview.md b/reference/docs-conceptual/Crescendo/overview.md index b41f94b2..5e6ebe37 100644 --- a/reference/docs-conceptual/Crescendo/overview.md +++ b/reference/docs-conceptual/Crescendo/overview.md @@ -5,6 +5,8 @@ title: Crescendo overview --- # Microsoft.PowerShell.Crescendo overview +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + PowerShell, like other shells, is capable of invoking command-line tools. However, it would improve the experience if the command-line tool could participate in the PowerShell pipeline and take advantage of the parameter behaviors that are part of PowerShell. diff --git a/reference/docs-conceptual/Crescendo/whats-new/whats-new-in-crescendo-11.md b/reference/docs-conceptual/Crescendo/whats-new/whats-new-in-crescendo-11.md index 80d2a986..46705bc8 100644 --- a/reference/docs-conceptual/Crescendo/whats-new/whats-new-in-crescendo-11.md +++ b/reference/docs-conceptual/Crescendo/whats-new/whats-new-in-crescendo-11.md @@ -5,6 +5,8 @@ title: What's new in Crescendo 1.1 --- # What's new in Crescendo 1.1 +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + This preview includes a new cmdlet, a new schema, support for argument value transformation, the ability to bypass the output handler, and improved error handling. diff --git a/reference/includes/crescendo-deprecated.md b/reference/includes/crescendo-deprecated.md new file mode 100644 index 00000000..b14b59d6 --- /dev/null +++ b/reference/includes/crescendo-deprecated.md @@ -0,0 +1,11 @@ +--- +author: sdwheeler +ms.author: sewhee +ms.date: 05/05/2026 +ms.topic: include +--- + + +> [!IMPORTANT] +> As of May 2026, the Crescendo project is no longer being actively maintained. This project +> should be considered archived from an engineering standpoint. diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md index ac05afb5..8a837e72 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/About/about_Crescendo.md @@ -9,6 +9,8 @@ title: about_Microsoft.PowerShell.Crescendo --- # about_Microsoft.PowerShell.Crescendo +[!INCLUDE[crescendo-deprecated](../../../includes/crescendo-deprecated.md)] + ## Short description The PowerShell Crescendo module provides a novel way to create proxy functions diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoCommand.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoCommand.md index d4e8a39b..2eef94d1 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoCommand.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoCommand.md @@ -28,6 +28,8 @@ Export-CrescendoCommand [-command] -fileName [-Force] [-Wha ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + This cmdlet creates JSON configuration files for Crescendo **Command** objects. It can create one JSON file per **Command** object or create one JSON file containing all objects passed to it. diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md index d5a7d655..c6cde9e8 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-CrescendoModule.md @@ -20,6 +20,8 @@ Export-CrescendoModule [-ConfigurationFile] [-ModuleName] [- ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + This cmdlet exports an object that can be converted into a function that acts as a proxy for a platform specific command. The resultant module file should be executable down to version 5.1 of PowerShell. diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-Schema.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-Schema.md index d03005e9..81dcb81b 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-Schema.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Export-Schema.md @@ -19,6 +19,8 @@ Export-Schema ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + Exports the JSON schema for command configuration as a PowerShell object. ## EXAMPLES diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Import-CommandConfiguration.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Import-CommandConfiguration.md index 1a088b26..99155c40 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Import-CommandConfiguration.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Import-CommandConfiguration.md @@ -19,6 +19,8 @@ Import-CommandConfiguration [-file] [] ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + This cmdlet exports an object that can be converted into a function that acts as a proxy for the platform specific command. The resultant object may then be used to call a native command that can participate in the PowerShell pipeline. The `ToString` method of the output object returns a string diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Microsoft.PowerShell.Crescendo.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Microsoft.PowerShell.Crescendo.md index 90860c3d..3da2b01a 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Microsoft.PowerShell.Crescendo.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Microsoft.PowerShell.Crescendo.md @@ -11,6 +11,8 @@ ms.date: 12/13/2022 ## Description +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + Crescendo is a development accelerator enabling you to rapidly build PowerShell cmdlets that leverage existing command-line tools. Crescendo amplifies the command-line experience of the original tool to include object output for the PowerShell pipeline, privilege elevation, and diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-CrescendoCommand.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-CrescendoCommand.md index 670054a0..9b9b0f50 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-CrescendoCommand.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-CrescendoCommand.md @@ -20,6 +20,8 @@ New-CrescendoCommand [-Verb] [-Noun] [[-OriginalName] ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + Creates a PowerShell command object. You can use this object to set the properties of the command you are defining. The resulting object can be converted to JSON to be added to a configuration file. diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-ExampleInfo.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-ExampleInfo.md index eb70bed2..d46dae2f 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-ExampleInfo.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-ExampleInfo.md @@ -20,6 +20,8 @@ New-ExampleInfo [-command] [-description] [[-originalCommand] ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + Creates a PowerShell object representing an example used in a Crescendo command object. The resulting object can be converted to JSON to be inserted into a configuration file or added to a command object conversion to JSON later. diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-OutputHandler.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-OutputHandler.md index 6081e483..ae304d71 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-OutputHandler.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-OutputHandler.md @@ -19,6 +19,8 @@ New-OutputHandler ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + Creates a PowerShell object representing a Crescendo output handler. You can assign values to the properties of the object. The resulting object can be added to the **OutputHandlers** property of a command object or it can be converted to JSON to be inserted in the configuration file. diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-ParameterInfo.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-ParameterInfo.md index 67cc9294..1582087b 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-ParameterInfo.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-ParameterInfo.md @@ -19,6 +19,8 @@ New-ParameterInfo [-Name] [-OriginalName] [] ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + Creates a PowerShell object representing a Crescendo Parameter definition. You can assign values to the properties of the object. The resulting object can be added to the **Parameters** property of a command object or it can be converted to JSON to be inserted in the configuration file. diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-UsageInfo.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-UsageInfo.md index 06dc2061..c34447cf 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-UsageInfo.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/New-UsageInfo.md @@ -19,6 +19,8 @@ New-UsageInfo [-usage] [] ## DESCRIPTION +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + Creates a PowerShell object representing a Crescendo Usage definition. You can assign values to the properties of the object. The resulting object can be added to the **Usage** property of a command object or it can be converted to JSON to be inserted in the configuration file. The **Synopsis** of diff --git a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Test-IsCrescendoCommand.md b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Test-IsCrescendoCommand.md index fd324415..6dc22383 100644 --- a/reference/ps-modules/Microsoft.PowerShell.Crescendo/Test-IsCrescendoCommand.md +++ b/reference/ps-modules/Microsoft.PowerShell.Crescendo/Test-IsCrescendoCommand.md @@ -18,6 +18,9 @@ Test-IsCrescendoCommand [-Command] [] ``` ## DESCRIPTION + +[!INCLUDE[crescendo-deprecated](../../includes/crescendo-deprecated.md)] + Tests a cmdlet to see if it was created by Crescendo. ## EXAMPLES From 6de32f3fc645c9995c2e1c0f5addfada3afd763d Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Tue, 5 May 2026 10:52:15 -0500 Subject: [PATCH 2/2] Update landing page and TOC (#393) --- reference/docs-conceptual/overview.md | 9 ++-- reference/docs-conceptual/toc.yml | 60 +++++++++++++-------------- 2 files changed, 36 insertions(+), 33 deletions(-) diff --git a/reference/docs-conceptual/overview.md b/reference/docs-conceptual/overview.md index 412df898..fff165af 100644 --- a/reference/docs-conceptual/overview.md +++ b/reference/docs-conceptual/overview.md @@ -1,6 +1,6 @@ --- description: This documentation set contains reference for modules published and maintained by the PowerShell team, but aren't part of the PowerShell package. -ms.date: 01/30/2026 +ms.date: 05/05/2026 title: PowerShell utility modules --- # PowerShell utility modules @@ -12,12 +12,15 @@ level of support for each module varies. For more details, see the landing page This documentation set contains cmdlet reference for the following modules. -- [Microsoft.PowerShell.Crescendo][02] - [Microsoft.PowerShell.SecretManagement][03] - [Microsoft.PowerShell.SecretStore][04] - [PlatyPS][05] - [PSScriptAnalyzer][06] -- [AIShell][01] - **Deprecated as of January 2026** + +Deprecated modules + +- [Microsoft.PowerShell.Crescendo][02] - **Deprecated May 2026** +- [AIShell][01] - **Deprecated January 2026** [01]: ./AIShell/overview.md diff --git a/reference/docs-conceptual/toc.yml b/reference/docs-conceptual/toc.yml index 03557631..1fbfbd36 100644 --- a/reference/docs-conceptual/toc.yml +++ b/reference/docs-conceptual/toc.yml @@ -1,36 +1,6 @@ items: - name: Overview href: overview.md - - name: AIShell - href: AIShell/toc.yml - - name: Crescendo - items: - - name: Overview - href: Crescendo/overview.md - - name: Get started - items: - - name: Install Crescendo - href: Crescendo/get-started/install-crescendo.md - - name: Choose a command-line tool - href: Crescendo/get-started/choose-command-line-tool.md - - name: Decide which features to amplify - href: Crescendo/get-started/research-tool.md - - name: Create a Crescendo cmdlet - href: Crescendo/get-started/create-new-cmdlet.md - - name: Generate and test a Crescendo module - href: Crescendo/get-started/generate-module.md - - name: What's new in Crescendo - items: - - name: What's new in Crescendo 1.1 - href: Crescendo/whats-new/whats-new-in-crescendo-11.md - - name: Advanced topics - items: - - name: Create a configuration using the cmdlets - href: Crescendo/advanced/using-crescendo-cmdlets.md - - name: Handling errors in Crescendo - href: Crescendo/advanced/handling-errors.md - - name: Transforming arguments in Crescendo - href: Crescendo/advanced/transforming-arguments.md - name: PlatyPS items: - name: Overview @@ -229,3 +199,33 @@ items: href: SecretManagement/how-to/using-secrets-in-automation.md - name: Use Azure Key Vault in automation href: SecretManagement/how-to/using-azure-keyvault.md + - name: AIShell + href: AIShell/toc.yml + - name: Crescendo + items: + - name: Overview + href: Crescendo/overview.md + - name: Get started + items: + - name: Install Crescendo + href: Crescendo/get-started/install-crescendo.md + - name: Choose a command-line tool + href: Crescendo/get-started/choose-command-line-tool.md + - name: Decide which features to amplify + href: Crescendo/get-started/research-tool.md + - name: Create a Crescendo cmdlet + href: Crescendo/get-started/create-new-cmdlet.md + - name: Generate and test a Crescendo module + href: Crescendo/get-started/generate-module.md + - name: What's new in Crescendo + items: + - name: What's new in Crescendo 1.1 + href: Crescendo/whats-new/whats-new-in-crescendo-11.md + - name: Advanced topics + items: + - name: Create a configuration using the cmdlets + href: Crescendo/advanced/using-crescendo-cmdlets.md + - name: Handling errors in Crescendo + href: Crescendo/advanced/handling-errors.md + - name: Transforming arguments in Crescendo + href: Crescendo/advanced/transforming-arguments.md