Creare una configurazione di Crescendo usando i cmdlet Crescendo

Il modulo Crescendo include un set di cmdlet che creano vari tipi di oggetti Crescendo. È possibile usare questi cmdlet per creare una configurazione crescendo senza dover modificare manualmente un file JSON.

Durante la progettazione di Crescendo, questi cmdlet sono stati creati prima della decisione che il modulo e la creazione di cmdlet potrebbero essere gestiti meglio da un approccio dichiarativo. La loro utilità era ancora apprezzata, quindi abbiamo deciso di supportare entrambi gli approcci.

Importante

Poiché gli strumenti di sviluppo come Visual Studio Code (VS Code) forniscono IntelliSense in base allo schema JSON, la creazione della configurazione modificando il file JSON è il metodo preferito per la creazione di una configurazione. Questo articolo viene fornito come esempio per il modo in cui è possibile usare i cmdlet.

Creare una configurazione per due cmdlet

In questo esempio viene illustrato come creare la configurazione per due cmdlet che esegue il wrapping dello strumento VSSAdmin.exedella riga di comando di Windows. In particolare, lo script crea cmdlet per i vssadmin list providers comandi e vssadmin list shadows .

Esaminando la Guida per questi due comandi, è possibile notare che non accetta parametri aggiuntivi, ma vssadmin list shadows ha una combinazione di parametri facoltativi che vssadmin list providers formano più set di parametri.

vssadmin list providers /?
vssadmin list shadows /?

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

List Providers
    - List registered volume shadow copy providers.

     Example Usage:  vssadmin List Providers

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

List Shadows [/For=ForVolumeSpec] [/Shadow=ShadowId|/Set=ShadowSetId]
    - Displays existing shadow copies on the system.  Without any options,
    all shadow copies on the system are displayed ordered by shadow copy set.
    Combinations of options can be used to refine the list operation.
    - The Shadow Copy ID can be obtained by using the List Shadows command.
    When entering a Shadow ID, it must be in
    the following format:
       {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}
    where the X's are hexadecimal characters.

    Example Usage:  vssadmin List Shadows
                             /Shadow={c5946237-af12-3f23-af80-51aadb3b20d5}

Per il vssadmin list shadows comando, è possibile notare che il /For parametro è facoltativo e può essere usato da solo o con uno dei /Shadow parametri o /ShadowSetId . Ciò comporta tre set di parametri possibili.

Codice script

Lo script seguente definisce la configurazione per due nuovi cmdlet. I commenti nello script forniscono la struttura seguente delle attività:

• Creare un oggetto di configurazione vuoto
  • Creare il primo comando Crescendo e impostarne le proprietà
    • Aggiungere un esempio al comando
    • Aggiungere un gestore di output al comando
    • Aggiungere il comando all'insieme Commands della configurazione
  • Creare il secondo comando Crescendo e impostarne le proprietà
    • Aggiungere più esempi al comando
    • Definire i parametri e i set di parametri
    • Aggiungere un gestore di output al comando
  • Aggiungere il comando all'insieme Commands della configurazione
• Esportare la configurazione in un file JSON e creare il modulo

La configurazione contiene riferimenti alle funzioni del gestore di output. Queste funzioni sono contenute in un file di script separato che deve essere caricato nella sessione prima di poter esportare la configurazione per creare un nuovo modulo di PowerShell. Per una spiegazione dettagliata di questi gestori di output, vedere questa serie di post nel blog di PowerShell Community .

# Create an empty array for Command object
$CrescendoCommands = @()

## Create first Crescendo command and set its properties
$cmdlet = @{
    Verb = 'Get'
    Noun = 'VssProvider'
    OriginalName = '$env:Windir/system32/vssadmin.exe'
}
$newCommand = New-CrescendoCommand @cmdlet
$newCommand.OriginalCommandElements = @('list','providers')
$newCommand.Description = 'List registered volume shadow copy providers'
$newCommand.Usage = New-UsageInfo -usage $newCommand.Description
$newCommand.Platform = @('Windows')

### Add an example to the command
$example = @{
    Command = 'Get-VssProvider'
    Description = 'Get a list of VSS Providers'
    OriginalCommand = 'vssadmin list providers'
}
$newCommand.Examples += New-ExampleInfo @example

### Add an Output Handler to the command
$handler = New-OutputHandler
$handler.ParameterSetName = 'Default'
$handler.HandlerType = 'Function'
$handler.Handler = 'ParseProvider'
$newCommand.OutputHandlers += $handler

## Add the command to the Commands collection of the configuration
$CrescendoCommands += $newCommand

## Create second Crescendo command and set its properties
$cmdlet = @{
    Verb = 'Get'
    Noun = 'VssShadow'
    OriginalName = '$env:Windir/system32/vssadmin.exe'
}
$newCommand = New-CrescendoCommand @cmdlet
$newCommand.OriginalCommandElements = @('list','shadows')
$newCommand.Description = 'List existing volume shadow copies. Without any options, ' +
    'all shadow copies on the system are displayed ordered by shadow copy set. ' +
    'Combinations of options can be used to refine the output.'
$newCommand.Usage = New-UsageInfo -usage 'List existing volume shadow copies.'
$newCommand.Platform = ,'Windows'

### Add multiple examples to the command
$example = @{
    Command = 'Get-VssShadow'
    Description = 'Get a list of VSS shadow copies'
    OriginalCommand = 'vssadmin list shadows'
}
$newCommand.Examples += New-ExampleInfo @example
$example = @{
    Command = 'Get-VssShadow -For C:'
    Description = 'Get a list of VSS shadow copies for volume C:'
    OriginalCommand = 'vssadmin list shadows /For=C:'
}
$newCommand.Examples += New-ExampleInfo @example
$example = @{
    Command = "Get-VssShadow -Shadow '{c17ebda1-5da3-4f4a-a3dc-f5920c30ed0f}"
    Description = 'Get a specific shadow copy'
    OriginalCommand = 'vssadmin list shadows /Shadow={3872a791-51b6-4d10-813f-64b4beb9f935}'
}
$newCommand.Examples += New-ExampleInfo @example

### Define the parameters and parameter sets
$newCommand.DefaultParameterSetName = 'Default'

#### Add a new parameter to the command
$parameter = New-ParameterInfo -OriginalName '/For=' -Name 'For'
$parameter.ParameterType = 'string'
$parameter.ParameterSetName = @('Default','ByShadowId','BySetId')
$parameter.NoGap = $true
$parameter.Description = "List the shadow copies for volume name like 'C:'"
$newCommand.Parameters += $parameter

#### Add a new parameter to the command
$parameter = New-ParameterInfo -OriginalName '/Shadow=' -Name 'Shadow'
$parameter.ParameterType = 'string'
$parameter.ParameterSetName = @('ByShadowId')
$parameter.NoGap = $true
$parameter.Mandatory = $true
$parameter.Description = "List shadow copies matching the Id in GUID format: " +
    "'{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}'"
$newCommand.Parameters += $parameter

#### Add a new parameter to the command
$parameter = New-ParameterInfo -OriginalName '/Set=' -Name 'Set'
$parameter.ParameterType = 'string'
$parameter.ParameterSetName = @('BySetId')
$parameter.NoGap = $true
$parameter.Mandatory = $true
$parameter.Description = "List shadow copies matching the shadow set Id in GUID format: " +
    "'{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}'"
$newCommand.Parameters += $parameter

### Add an Output Handler to the command
$handler = New-OutputHandler
$handler.ParameterSetName = 'Default'
$handler.HandlerType = 'Function'
$handler.Handler = 'ParseShadow'
$newCommand.OutputHandlers += $handler

## Add the command to the Commands collection of the configuration
$CrescendoCommands += $newCommand

# Export the configuration to a JSON file and create the module
Export-CrescendoCommand -command $CrescendoCommands -fileName .\vssadmin.json
Export-CrescendoModule -ConfigurationFile vssadmin.json -ModuleName .\vssadmin.psm1 -Force

Casi d'uso avanzati

I cmdlet Crescendo sono strumenti potenti che possono essere usati negli scenari avanzati per creare configurazioni e moduli di compilazione. Esistono diversi esempi avanzati nella Experimental\HelpParsers cartella del modulo Microsoft.PowerShell.Crescendo . Questi esempi sperimentali mostrano come analizzare l'output della Guida di uno strumento da riga di comando e usare tali informazioni per creare una configurazione crescendo per un modulo che esegue il wrapping dello strumento. Il file README.md fornisce una spiegazione dettagliata della progettazione di questi parser della Guida.

È possibile usare questi parser della Guida in una pipeline CI/CD per compilare nuove versioni di un modulo quando lo strumento da riga di comando cambia.