A better have a look at the Crescendo configuration

In my earlier publish, I regarded on the particulars of a Crescendo output handler from my VssAdmin module. On this publish, I clarify the small print of a cmdlet definition within the Crescendo JSON configuration file.

The aim of the configuration

The construction for the interface of a cmdlet is a fairly predictable factor.

• The cmdlet makes use of a regular Verb-Noun format
• The cmdlets take enter utilizing units of parameters
• Cmdlets that make adjustments to the system assist -Affirm and -WhatIf parameters

The sample of the script code to assist these suits a template.

The tougher a part of the cmdlet is within the code that does the work. Crescendo separates the useful code (the output handler) from the cmdlet interface code. The Crescendo configuration file defines the interfaces of cmdlets that you really want Crescendo to create.

The Crescendo configuration file is a JSON file containing an array of cmdlet definitions. JSON supplies an expressive, structured syntax for outlining the properties of objects. However so does, PowerShell. So why use JSON and never a PowerShell knowledge (PSD1) file? The reply is easy: schema! Not like PowerShell’s PSD1 recordsdata, JSON helps a schema. Having a schema ensures that the syntax of your definition is appropriate. And with instruments like Visible Studio Code (VS Code), the schema supplies IntelliSense, making it simpler to creator.

Defining a cmdlet interface

The construction of a cmdlet definition might be divided into three property classes within the JSON file:

• Required properties
  • Verb
  • Noun
  • OriginalName
  • OriginalCommandElements[]
  • OutputHandlers[]
• As-required properties
  • DefaultParameterSetName
  • Parameters[]
• Good-to-have properties
  • “Assist” properties like Description, Utilization, and Examples[]

You may discover that defining Parameters is elective. This isn’t unusual. In my VssAdmin module, the cmdlets Get-VssProvider, Get-VssVolume, and Get-VssWriter should not have parameters. These easy cmdlets don’t require any enter to return the requested data.

Let’s take a better have a look at a easy cmdlet definition.

• The Verb and Noun properties kind the title of the cmdlet.
• The OriginalName property incorporates the trail to the native command that the cmdlet runs to get the output.
• The OriginalCommandElements is an array of strings which might be handed to the native command as parameters. A typical CLI like vssadmin has its personal set of instructions that carry out totally different actions. These instructions might have extra parameters. On this instance, the vssadmin checklist suppliers command has no extra parameters.
• The OutputHandlers property is an array containing a number of handler definitions. The handlers obtain the output of the native command and return an object containing the information parsed from the output.
  • The HandlerType might be Inline, Operate, or Script. On this instance I take advantage of Operate.
  • The Handler is the title of the Script or Operate to be referred to as, or the precise PowerShell code to run if the sort is Inline.

{
    "$schema": "https://aka.ms/Crescendo/Schema.json",
    "Instructions": [
        {
            "Verb": "Get",
            "Noun": "VssProvider",
            "OriginalName": "$env:Windir/system32/vssadmin.exe",
            "OriginalCommandElements": [
                "list",
                "providers"
            ],
            "Description": "Listing registered quantity shadow copy suppliers",
            "Utilization": {
                "Synopsis": "Listing registered quantity shadow copy suppliers"
            },
            "Examples": [
                {
                    "Command": "Get-VssProvider",
                    "Description": "Get a list of VSS Providers",
                    "OriginalCommand": "vssadmin list providers"
                }
            ],
            "OutputHandlers": [
                {
                    "ParameterSetName": "Default",
                    "HandlerType": "Function",
                    "Handler": "ParseProvider"
                }
            ]
        }
    ]
}

The remaining properties — Description, Utilization, and Examples — are elective. Crescendo makes use of these values to create the comment-based assist for the cmdlet when it creates the module.

Defining parameters and parameter units

Among the vssadmin instructions have elective parameters that can be utilized in numerous mixtures. For instance:

• vssadmin Listing Shadows [/For=ForVolumeSpec] [/Shadow=ShadowId|/Set=ShadowSetId] – 3 elective parameters in 2 parameter units
• vssadmin Listing ShadowStorage [/For=ForVolumeSpec|/On=OnVolumeSpec] – 2 parameter units with 1 elective parameter every

Let’s check out the assistance for vssadmin Resize ShadowStorage.

vssadmin 1.1 - Quantity Shadow Copy Service administrative command-line device
(C) Copyright 2001-2013 Microsoft Corp.

Resize ShadowStorage /For=ForVolumeSpec /On=OnVolumeSpec /MaxSize=MaxSizeSpec
    - Resizes the utmost dimension for a shadow copy storage affiliation between
    ForVolumeSpec and OnVolumeSpec.  Resizing the storage affiliation might trigger shadow
    copies to vanish.  As sure shadow copies are deleted, the shadow copy storage
    area will then shrink.  If MaxSizeSpec is ready to the worth UNBOUNDED, the shadow copy
    space for storing can be limitless.  MaxSizeSpec might be laid out in bytes or as a
    proportion of the ForVolumeSpec storage quantity.  For byte degree specification,
    MaxSizeSpec should be 320MB or higher and accepts the next suffixes: KB, MB, GB, TB,
    PB and EB.  Additionally, B, Okay, M, G, T, P, and E are acceptable suffixes.  To specify MaxSizeSpec
    as proportion, use the % character because the suffix to the numeric worth.  If a suffix isn't
    equipped, MaxSizeSpec is in bytes.

    Instance Utilization:  vssadmin Resize ShadowStorage /For=C: /On=D: /MaxSize=900MB
                    vssadmin Resize ShadowStorage /For=C: /On=D: /MaxSize=UNBOUNDED
                    vssadmin Resize ShadowStorage /For=C: /On=C: /MaxSize=20%

The vssadmin Resize ShadowStorage command has three required parameters, however the third parameter /MaxSize can take three various kinds of enter. In PowerShell, we want fastened sorts for parameter values. We are able to remedy this by creating three totally different parameters, every utilized in a distinct parameter set.

The next JSON defines the Resize-VssShadowStorage cmdlet. The definition begins with the required properties and a few assist data. This definition additionally has SupportsShouldProcess set to true. With this property, Crescendo provides the [SupportsShouldProcess()] attribute to the cmdlet, which routinely provides the -WhatIf and -Affirm parameters.

The fascinating half begins within the parameter definitions.

  {
      "Verb": "Resize",
      "Noun": "VssShadowStorage",
      "OriginalName": "c:/home windows/system32/vssadmin.exe",
      "OriginalCommandElements": [
          "Resize",
          "ShadowStorage"
      ],
      "Description": "Resizes the utmost dimension for a shadow copy storage affiliation between ForVolumeSpec and OnVolumeSpec. Resizing the storage affiliation might trigger shadow copies to vanish. As sure shadow copies are deleted, the shadow copy space for storing will then shrink.",
      "Utilization": {
          "Synopsis": "Resize the utmost dimension of a shadow copy storage affiliation."
      },
      "Examples": [
          {
              "Command": "Resize-VssShadowStorage -For C: -On C: -MaxSize 900MB",
              "Description": "Set the new storage size to 900MB",
              "OriginalCommand": "vssadmin Resize ShadowStorage /For=C: /On=C: /MaxSize=900MB"
          },
          {
              "Command": "Resize-VssShadowStorage -For C: -On C: -MaxPercent '20%'",
              "Description": "Set the new storage size to 20% of the OnVolume size",
              "OriginalCommand": "vssadmin Resize ShadowStorage /For=C: /On=C: /MaxSize=20%"
          },
          {
              "Command": "Resize-VssShadowStorage -For C: -On C: -Unbounded",
              "Description": "Set the new storage size to unlimited",
              "OriginalCommand": "vssadmin Resize ShadowStorage /For=C: /On=C: /MaxSize=UNBOUNDED"
          }
      ],
      "SupportsShouldProcess": true,
      "DefaultParameterSetName": "ByMaxSize",
      "Parameters": [
          {
              "OriginalName": "/For=",
              "Name": "For",
              "ParameterType": "string",
              "ParameterSetName": [ "ByMaxSize", "ByMaxPercent", "ByMaxUnbound" ],
              "NoGap": true,
              "Description": "Present a quantity title like 'C:'"
          },
          {
              "OriginalName": "/On=",
              "Title": "On",
              "ParameterType": "string",
              "ParameterSetName": [ "ByMaxSize", "ByMaxPercent", "ByMaxUnbound" ],
              "Necessary": true,
              "NoGap": true,
              "Description": "Present a quantity title like 'C:'"
          },
          {
              "OriginalName": "/MaxSize=",
              "Title": "MaxSize",
              "ParameterType": "Int64",
              "ParameterSetName": [ "ByMaxSize" ],
              "AdditionalParameterAttributes": [
                  "[ValidateScript({$_ -ge 320MB})]"
              ],
              "Necessary": true,
              "NoGap": true,
              "Description": "New most dimension in bytes. Should be 320MB or extra."
          },
          {
              "OriginalName": "/MaxSize=",
              "Title": "MaxPercent",
              "ParameterType": "string",
              "ParameterSetName": [ "ByMaxPercent" ],
              "AdditionalParameterAttributes": [
                  "[ValidatePattern('[0-9]+%')]"
              ],
              "Necessary": true,
              "NoGap": true,
              "Description": "A proportion string like '20%'."
          },
          {
              "OriginalName": "/MaxSize=UNBOUNDED",
              "Title": "Unbounded",
              "ParameterType": "swap",
              "ParameterSetName": [ "ByMaxUnbound" ],
              "Necessary": true,
              "Description": "Units the utmost dimension to UNBOUNDED."
          }
      ],
      "OutputHandlers": [
          {
              "ParameterSetName": "ByMaxSize",
              "HandlerType": "Function",
              "Handler": "ParseResizeShadowStorage"
          },
          {
              "ParameterSetName": "ByMaxPercent",
              "HandlerType": "Function",
              "Handler": "ParseResizeShadowStorage"
          },
          {
              "ParameterSetName": "ByMaxUnbound",
              "HandlerType": "Function",
              "Handler": "ParseResizeShadowStorage"
          }
      ]
  }

The parameters have the next properties:

• OriginalName incorporates the unique parameter utilized by the native command. Crescendo combines the worth handed into the cmdlet with the unique parameter string. The ensuing native parameter is added to the unique native command that will get executed by the cmdlet.
• Title is the title of the parameter for the PowerShell cmdlet you might be defining.
• ParameterType is the kind of the parameter for the cmdlet.
• ParameterSetName is an array of a number of parameter set names that the parameter belongs to.
• AdditionalParameterAttributes is an array of strings that comprise any extra attribute you need added to the parameter. You should use this so as to add parameter validation attributes.
• NoGap tells Crescendo not so use an area between the OriginalName parameter and the worth handed into the cmdlet.
• Description is the outline of the parameter displayed by Get-Assist.

For this cmdlet, the primary two parameters -For and -On are in all three parameter units. The remaining three parameters are distinctive to every parameter set.

• The -MaxSize parameter accepts a 64-bit integer. That worth is added to the /MaxSize= string to kind the native parameter. The parameter validation ensures that the worth handed in is larger than 320MB.
• The -MaxPercent parameter accepts a string containing a proportion worth. That string is added to the /MaxSize= string to kind the native parameter. The parameter validation ensures that the string represents a legitimate proportion.
• The -Unbounded swap parameter is used choose a local parameter of /MaxSize=UNBOUNDED.

Defining the output handlers

Since there are three parameters units, I have to outline an output handler for every set. You could possibly have a separate perform for every set. In my case that was not vital. The vssadmin Resize ShadowStorage command doesn’t have any output until there’s an error. Additionally, because the command makes adjustments, I assumed I ought to name Get-VssShadowStorage to indicate the brand new settings.

perform ParseResizeShadowStorage {
    param(
        [Parameter(Mandatory)]
        $cmdResults
    )
    $textBlocks = ($cmdResults | Out-String) -split "`r`n`r`n"

    if ($textBlocks[1] -like 'Error*') {
        Write-Error $textBlocks[1]
    } elseif ($textBlocks[1] -like 'Success*') {
        Get-VssShadowStorage
    } else {
        $textBlocks[1]
    }
}

The ultimate step

As soon as the configuration file was full, I used the Export-CrescendoModule cmdlet to create my VssAdmin module.

Export-CrescendoModule -ConfigurationFile vssadmin.crescendo.config.json -ModuleName VssAdmin.psm1

Crescendo created two new recordsdata:

• The module code file – VssAdmin.psm1
• The module manifest file – VssAdmin.psd1

These are the one two recordsdata that have to be put in. The VssAdmin.psm1 file incorporates all of the cmdlets that Crescendo generated from the configuration and the Output Handler capabilities I wrote to parse the output into objects.

Conclusion

Crescendo separates the structural interface code required to create a cmdlet from the useful code that extracts the information. The configuration file defines the cmdlet interfaces. The Export-CrescendoModule cmdlet creates a brand new module containing the cmdlets outlined within the configuration (full with the assistance textual content offered) and the output handler capabilities required by the cmdlets. It additionally creates a correct module manifest, full with exports for the brand new cmdlets.

Assets

Posts on this sequence

References

Sean Wheeler
Sr. Content material Developer for PowerShell, Microsoft Developer Relations | Content material + Studying