{"id":19802,"date":"2022-12-06T09:25:05","date_gmt":"2022-12-06T17:25:05","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/powershell\/?p=19802"},"modified":"2022-12-06T09:25:05","modified_gmt":"2022-12-06T17:25:05","slug":"announcing-powershell-crescendo-1-1-0-preview01","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/powershell\/announcing-powershell-crescendo-1-1-0-preview01\/","title":{"rendered":"Announcing PowerShell Crescendo 1.1.0-preview01"},"content":{"rendered":"<p>We&#8217;re pleased to announce the release of <strong>PowerShell Crescendo 1.1.0-preview01<\/strong>. <a href=\"https:\/\/learn.microsoft.com\/powershell\/utility-modules\/crescendo\/overview\">Crescendo<\/a>\nis a framework to rapidly develop PowerShell cmdlets for common command line tools, regardless of\nplatform. This preview includes a new schema, support for argument value transformation, the ability\nto bypass the output handler, and improved error handling.<\/p>\n<p>This is a community driven release built from the many suggestions and requests received directly or\nfrom our <a href=\"https:\/\/github.com\/PowerShell\/Crescendo\/issues\">Github<\/a>. Thank you PowerShell Community for your adoption and suggestions!<\/p>\n<p>The preview release is now available for download on the <a href=\"https:\/\/www.powershellgallery.com\/packages\/Microsoft.PowerShell.Crescendo\/1.1.0-preview01\">PowerShell Gallery<\/a>.<\/p>\n<h2>Installing Crescendo<\/h2>\n<p>Requirements:<\/p>\n<ul>\n<li><strong>Microsoft.PowerShell.Crescendo<\/strong> requires PowerShell 7.0 or higher<\/li>\n<\/ul>\n<p>To install <strong>Microsoft.PowerShell.Crescendo<\/strong>:<\/p>\n<pre><code class=\"language-powershell\">Install-Module -Name Microsoft.PowerShell.Crescendo -AllowPreRelease<\/code><\/pre>\n<p>To install <strong>Microsoft.PowerShell.Crescendo<\/strong> using the new <a href=\"https:\/\/www.powershellgallery.com\/packages\/PowerShellGet\/3.0.17-beta\">PowerShellGet v3<\/a>:<\/p>\n<pre><code class=\"language-powershell\">Install-PSResource -Name Microsoft.PowerShell.Crescendo -AllowPreRelease<\/code><\/pre>\n<h2>Highlighted features<\/h2>\n<p>This preview release includes many fixes and suggestions. Here are just a few of the highlights\nadded for this preview.<\/p>\n<ul>\n<li><a href=\"https:\/\/github.com\/PowerShell\/Crescendo\/issues\/122\">Allow for module manifest adaptations<\/a> (Thanks <a href=\"https:\/\/github.com\/tbergstedt\">@tbergstedt<\/a>)<\/li>\n<li><a href=\"https:\/\/github.com\/PowerShell\/Crescendo\/issues\/177\">Crescendo should offer a way to bypass the output handler<\/a> (Thanks <a href=\"https:\/\/github.com\/potatoqualitee\">@potatoqualitee<\/a>)<\/li>\n<li><a href=\"https:\/\/github.com\/PowerShell\/Crescendo\/issues\/129\">Generated commands cannot handle output written to the error stream<\/a> (Thanks <a href=\"https:\/\/github.com\/draproctor\">@draproctor<\/a>)<\/li>\n<li><a href=\"https:\/\/github.com\/PowerShell\/Crescendo\/issues\/139\">Allow for Parameter values to be translated via key\/value pair<\/a> (Thanks <a href=\"https:\/\/github.com\/EmeraldFlame\">@EmeraldFlame<\/a>)<\/li>\n<li><a href=\"https:\/\/github.com\/PowerShell\/Crescendo\/issues\/31\">Conversion of input parameter values<\/a> (Thanks <a href=\"https:\/\/github.com\/cdhunt\">@cdhunt<\/a>)<\/li>\n<\/ul>\n<h3>New schema version<\/h3>\n<p>The Crescendo schema has been updated to include support for two new members to the <strong>Parameter<\/strong>\nclass, <code>ArgumentTransform<\/code> and <code>ArgumentTransformType<\/code>. The schema works with supported tools like\nVisual Studio Code to provide intellisense and tooltips during the authoring experience.<\/p>\n<p>URL location of the always-available Crescendo schema:<\/p>\n<pre><code class=\"language-json\">{\r\n   \"$schema\": \"https:\/\/aka.ms\/PowerShell\/Crescendo\/Schemas\/2022-06\",\r\n   \"Commands\": []\r\n}<\/code><\/pre>\n<h3>Prevent overwriting of the module manifest<\/h3>\n<p>Crescendo creates both the module <code>.psm1<\/code> and the module manifest <code>.psd1<\/code> when\n<code>Export-CrescendoModule<\/code> is executed. This can create problems when you have customized the module\nmanifest beyond the scope of Crescendo. The <code>Export-CrescendoModule<\/code> cmdlet now provides a\n<strong>NoClobberManifest<\/strong> switch parameter to prevent the manifest from being overwritten.<\/p>\n<pre><code class=\"language-powershell\">Export-CrescendoModule -ConfigurationFile .\\myconfig.json -ModuleName .\\Mymodule -NoClobberManifest<\/code><\/pre>\n<p><div class=\"alert alert-primary\"><p class=\"alert-divider\"><i class=\"fabric-icon fabric-icon--Info\"><\/i><strong>Note<\/strong><\/p>The <strong>NoClobberManifest<\/strong> switch parameter prevents Crescendo from\nupdating the module manifest. You are responsible for manually updating the manifest with any new\ncmdlets and settings.<\/div><\/p>\n<h3>Bypass output handling entirely<\/h3>\n<p>Some native commands respond with different output depending on whether the output is sent to the\nscreen or the pipeline. <a href=\"https:\/\/github.com\/sharkdp\/pastel\">Pastel<\/a> is an example of a command that changes its output\nfrom a graphical screen representation to a single string value when used in a pipeline. Crescendo\noutput handling is pipeline based and can cause these applications to return unwanted results.\nCrescendo now supports the ability to bypass the output handler entirely.<\/p>\n<p>To bypass all output handling by Crescendo:<\/p>\n<pre><code class=\"language-json\">\"OutputHandlers\": [\r\n    {\r\n        \"ParameterSetName\": \"Default\",\r\n        \"HandlerType\": \"ByPass\"\r\n    }\r\n]<\/code><\/pre>\n<h3>Handling error output<\/h3>\n<p>Previously, native command errors weren&#8217;t captured by Crescendo and allowed to stream directly to\nthe user. This prevented you from creating enhanced error handling. Crescendo now captures the\ngenerated command error output (stderr) and is now available to the output handler. Error messages\nare placed in a queue. You can access the queue in your output handler using a new function,\n<code>Pop-CrescendoNativeError<\/code>.<\/p>\n<p>If you don&#8217;t define an output handler, Crescendo uses the default handler. The default output\nhandler ensures that errors respect the <code>-ErrorVariable<\/code> and <code>-ErrorAction<\/code> parameters and adds\nerrors to <code>$Error<\/code>.<\/p>\n<p>Adding an output handler that includes <code>Pop-CrescendoNativeError<\/code> allows you to inspect errors in\nthe output handler so you can handle them or pass them through to the caller.<\/p>\n<pre><code class=\"language-json\">\"OutputHandlers\": [\r\n    {\r\n        \"ParameterSetName\": \"Default\",\r\n        \"StreamOutput\": true,\r\n        \"HandlerType\": \"Inline\",\r\n        \"Handler\": \"PROCESS { $_ } END { Pop-CrescendoNativeError -EmitAsError }\"\r\n    }\r\n]<\/code><\/pre>\n<h3>Argument value transformation<\/h3>\n<p>You may find situations where the input values handed to a Crescendo wrapped command should be\ntranslated to a different value for the underlying native command. Crescendo now supports argument\ntransformation to support these scenarios. We updated the schema to add two new members to the\n<strong>Parameter<\/strong> class, <code>ArgumentTransform<\/code> and <code>ArgumentTransformType<\/code>. Use these members to transform\nparameter arguments inline or invoke a script block that takes the parameter value as an argument.\nThe default value for <code>ArgumentTransformType<\/code> is inline.<\/p>\n<p>Example: Multiplication of a value.<\/p>\n<pre><code class=\"language-json\">\"Parameters\": [\r\n    {\r\n        \"Name\": \"mult2\",\r\n        \"OriginalName\": \"--p3\",\r\n        \"ParameterType\": \"int\",\r\n        \"OriginalPosition\": 2,\r\n        \"ArgumentTransform\": \"param([int]$v) $v * 2\"\r\n    }\r\n]<\/code><\/pre>\n<p>Example: Accepting an ordered hashtable.<\/p>\n<pre><code class=\"language-json\">\"Parameters\": [\r\n    {\r\n        \"Name\": \"hasht2\",\r\n        \"OriginalName\": \"--p1ordered\",\r\n        \"ParameterType\": \"System.Collections.Specialized.OrderedDictionary\",\r\n        \"OriginalPosition\": 0,\r\n        \"ArgumentTransform\": \"param([System.Collections.Specialized.OrderedDictionary]$v) $v.Keys.ForEach({''{0}={1}'' -f $_,$v[$_]}) -join '',''\"\r\n    }\r\n]<\/code><\/pre>\n<p>Example: Argument transformation with join.<\/p>\n<pre><code class=\"language-json\">\"Parameters\": [\r\n    {\r\n        \"Name\": \"join\",\r\n        \"OriginalName\": \"--p2\",\r\n        \"ParameterType\": \"string[]\",\r\n        \"OriginalPosition\": 1,\r\n        \"ArgumentTransform\": \"param([string[]]$v) $v -join '',''\"\r\n    }\r\n]<\/code><\/pre>\n<p>Example: Calling a script based transformation.<\/p>\n<pre><code class=\"language-json\">\"Parameters\": [\r\n    {\r\n        \"Name\" : \"Param1\",\r\n        \"ArgumentTransform\": \"myfunction\",\r\n        \"ArgumentTransformType\" : \"function\"\r\n    }\r\n]<\/code><\/pre>\n<h2>More information<\/h2>\n<p>To get started using Crescendo, check out the <a href=\"https:\/\/learn.microsoft.com\/powershell\/utility-modules\/crescendo\/overview\">documentation<\/a>.<\/p>\n<h2>Future plans<\/h2>\n<p>We value your ideas and feedback and hope you give Crescendo a try. Stop by our\n<a href=\"https:\/\/github.com\/PowerShell\/Crescendo\">GitHub repository<\/a> and let us know of any issues you find or features you would like added.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>**PowerShell Crescendo 1.1.0-preview01**. This preview includes a new schema, support for argument value transformation, the ability to bypass the output handler, and improved error handling.<\/p>\n","protected":false},"author":7527,"featured_media":13641,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[3173],"class_list":["post-19802","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-powershell","tag-powershell-crescendo"],"acf":[],"blog_post_summary":"<p>**PowerShell Crescendo 1.1.0-preview01**. This preview includes a new schema, support for argument value transformation, the ability to bypass the output handler, and improved error handling.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/19802","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/users\/7527"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/comments?post=19802"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/posts\/19802\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media\/13641"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/media?parent=19802"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/categories?post=19802"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/powershell\/wp-json\/wp\/v2\/tags?post=19802"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}