Udostępnij za pomocą

Tworzenie polecenia cmdlet Crescendo

Nowoczesne narzędzia wiersza polecenia udostępniają polecenia umożliwiające efektywne zarządzanie technologiami specyficznymi dla domeny. Użytkownicy administracyjni mogą bezpiecznie wykonywać te polecenia w programie PowerShell i uzyskiwać oczekiwane wyniki. Jednak użytkownicy programu PowerShell preferują składnię, czytelność i dane wyjściowe oparte na obiektach, które zapewniają polecenia cmdlet, szczególnie w automatyzacji.

Jak wspomniano wcześniej, istnieje kilka powodów, dla których warto wzmocnić narzędzie wiersza polecenia:

  • Dane wyjściowe ciągu są trudne do użycia w automatyzacji
  • Składnia polecenia jest trudna do użycia lub zapamiętania
  • Narzędzie nie ma dokumentacji pomocy informacyjnej

W poprzednim artykule omówiliśmy sposób odnajdywania i wybierania funkcji narzędzia, które chcesz wzmocnić za pomocą narzędzia Crescendo. W przykładach w tym artykule będziemy nadal używać azcmagent narzędzia wiersza polecenia, które zostało wcześniej wprowadzone.

Tworzenie konfiguracji polecenia cmdlet Crescendo

Konfiguracja crescendo opisuje nowe polecenie cmdlet. Definicja polecenia cmdlet obejmuje następujące elementy:

  • Lokalizacja oryginalnego narzędzia wiersza polecenia
  • Podpolecenia i parametry przekazane do narzędzia wiersza polecenia
  • Nazwa Verb-Noun nowego polecenia cmdlet
  • Parametry używane przez polecenie cmdlet

Narzędzie Crescendo pobiera plik konfiguracji i generuje polecenia cmdlet serwera proxy dla oryginalnego narzędzia wiersza polecenia. Wygenerowany kod jest przechowywany w module skryptu programu PowerShell gotowym do wdrożenia.

Możesz utworzyć własny plik konfiguracji, skopiować istniejący plik i zmodyfikować go lub uruchomić nową konfigurację przy użyciu New-CrescendoCommand polecenia cmdlet . Pliki konfiguracji Crescendo są zapisywane w formacie JSON.

  • Parametr Verb określa czasownik dla nowego polecenia cmdlet. Użyj polecenia Get-Verb , aby uzyskać listę zatwierdzonych nazw czasowników.
  • Parametr rzeczownika określa rzeczownik, na który działa czasownik.
  • Parametr OriginalName określa ścieżkę do oryginalnego narzędzia wiersza polecenia.
$parameters = @{
    Verb = 'Show'
    Noun = 'AzCmAgent'
    OriginalName = "c:/program files/AzureConnectedMachineAgent/azcmagent.exe"
}
New-CrescendoCommand @parameters | Format-List *

New-CrescendoCommand Tworzy obiekt polecenia Crescendo. Polecenie cmdlet wypełnia wszystkie możliwe wartości właściwości.

FunctionName            : Show-AzCmAgent
Verb                    : Show
Noun                    : AzCmAgent
OriginalName            : c:/program files/AzureConnectedMachineAgent/azcmagent.exe
OriginalCommandElements :
Platform                : {Windows, Linux, MacOS}
Elevation               :
Aliases                 :
DefaultParameterSetName :
SupportsShouldProcess   : False
ConfirmImpact           :
SupportsTransactions    : False
NoInvocation            : False
Description             :
Usage                   :
Parameters              : {}
Examples                : {}
OriginalText            :
HelpLinks               :
OutputHandlers          :

W poniższym przykładzie pokazano, jak utworzyć nowy plik konfiguracji.

$parameters = @{
    Verb = 'Show'
    Noun = 'AzCmAgent'
    OriginalName = "c:/program files/AzureConnectedMachineAgent/azcmagent.exe"
}
$CrescendoCommands += New-CrescendoCommand @parameters
Export-CrescendoCommand -command $CrescendoCommands -fileName .\AzCmAgent.json

Plik konfiguracji Crescendo ma schemat JSON i może zawierać co najmniej jedną definicję polecenia cmdlet w tablicy. W tym przykładzie $NewConfiguration jest obiektem zawierającym link do schematu JSON i tablicą zawierającą definicje poleceń cmdlet. Dane wyjściowe polecenia New-CrescendoCommand są dodawane do tablicy Polecenia . Element $NewConfiguration jest konwertowany na format JSON i zapisywany w pliku. Plik AzCmAgent.json zawiera następujący kod:

{
  "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06",
  "Commands": [
    {
      "Verb": "Show",
      "Noun": "AzCmAgent",
      "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
      "Platform": [
        "Windows",
        "Linux",
        "MacOS"
      ],
      "SupportsShouldProcess": false,
      "SupportsTransactions": false,
      "NoInvocation": false,
      "Parameters": [],
      "Examples": []
    }
  ]
}

Ważne jest, aby link schematu był w pliku konfiguracji Crescendo. Schemat udostępnia narzędzia, takie jak Visual Studio Code z funkcją IntelliSense i etykietkami narzędzi podczas tworzenia.

Kończenie konfiguracji polecenia Crescendo

W tym przykładzie azcmagent show tworzysz konfigurację dla polecenia . Polecenie cmdlet nie wymaga żadnych dodatkowych parametrów. Ponieważ azcmagent jest to nowoczesne narzędzie, które udostępnia dane wyjściowe JSON, przykład zawiera prostą procedurę obsługi danych wyjściowych w celu przekonwertowania danych wyjściowych JSON na obiekty.

Definicja polecenia zawiera następujące właściwości:

  • Czasownik: nazwa czasownika cmdlet
  • Noun: nazwa nounu polecenia cmdlet
  • Platforma: platforma uruchamiana przez to polecenie Crescendo w systemie (Windows, Linux, MacOS)
  • OriginalName: oryginalna natywna nazwa polecenia i lokalizacja
  • OriginalCommandElements: Niektóre narzędzia wiersza polecenia mają dodatkowe obowiązkowe przełączniki dla danego scenariusza
  • Opis: Opis polecenia cmdlet widocznego w Pomocy
  • Aliasy: alias lub krótka nazwa dla nowego polecenia cmdlet
  • OutputHandlers: program obsługi danych wyjściowych, który przechwytuje dane wyjściowe ciągu z narzędzia wiersza polecenia i przekształca je w obiekty programu PowerShell
  • Typ programu obsługi: może mieć wartość Inline, Functionlub Script. W tym przykładzie użyto Inline

Poniższy przykład przedstawia pełną definicję JSON nowego polecenia cmdlet po dodatkowej edycji.

{
  "$schema": "https://aka.ms/PowerShell/Crescendo/Schemas/2022-06",
  "Commands": [
    {
      "Verb": "Show",
      "Noun": "AzCmAgent",
      "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
      "OriginalCommandElements": [
         "show",
         "--json"
      ],
      "Platform": [
        "Windows"
      ],
      "Description": "Gets machine metadata and Agent status. This is primarily useful for troubleshooting.",
      "Aliases": [
        "azinfo"
      ],
      "OutputHandlers": [
        {
            "ParameterSetName": "Default",
            "HandlerType": "Inline",
            "Handler": "$args[0] | ConvertFrom-Json"
        }
      ],
      "SupportsShouldProcess": false,
      "SupportsTransactions": false,
      "NoInvocation": false,
      "Parameters": [],
      "Examples": []
    }
  ]
}

Definiowanie innego polecenia cmdlet z parametrami

W tym przykładzie utworzymy konfigurację crescendo dla azcmagent config get polecenia, które wyświetla informacje o właściwości. Parametr o nazwie Property jest mapowany na oryginalny parametr Get.

Definicja parametru zawiera następujące właściwości:

  • DefaultParameterSetName: definiuje domyślny zestaw parametrów, jeśli zaimplementowano wiele zestawów parametrów
  • Parametry: blok kodu zawierający definicję parametrów polecenia
  • Nazwa: jest to nazwa parametru programu PowerShell dla wygenerowanego polecenia cmdlet
  • OriginalName: nazwa parametru
  • ParameterType: definiuje typ danych wartości parametru
  • ParameterSetName: definiuje, który parametr należy do tego parametru
  • Obowiązkowe: ustawienie określające, czy parametr jest wymagany do posiadania wartości
  • Opis: opis parametru widocznego w Pomocy

W poniższym przykładzie przedstawiono pełną definicję JSON nowego polecenia cmdlet. Możesz umieścić ją w definicji w nowym pliku JSON lub dodać go do tablicy Polecenia poprzedniego pliku JSON.

{
    "Verb": "Get",
    "Noun": "AzCmAgentConfigProperty",
    "Platform": [
        "Windows"
    ],
    "OriginalCommandElements": [
        "config",
        "--json"
    ],
    "OriginalName": "c:/program files/AzureConnectedMachineAgent/azcmagent.exe",
    "Description": " Get a configuration property's value",
    "DefaultParameterSetName": "Default",
    "Parameters": [
        {
            "OriginalName": "get",
            "Name": "Property",
            "ParameterType": "string",
            "ParameterSetName": [
                "Default"
            ],
            "Mandatory": true,
            "Description": "Specify the name of the property to return"
        }
    ],
    "OutputHandlers": [
        {
            "ParameterSetName": "Default",
            "HandlerType": "Inline",
            "Handler": "$args[0] | ConvertFrom-Json"
        }
    ],
    "SupportsShouldProcess": false,
    "SupportsTransactions": false,
    "NoInvocation": false,
    "Examples": []
}

Aby zapoznać się z bardziej szczegółowym przykładem konfiguracji, zobacz wpis w blogu A closer look at the Crescendo configuration (Konfiguracja crescendo).

Następne kroki

Teraz, gdy już zdefiniowano polecenia cmdlet, możesz wygenerować nowy moduł.

Generowanie i testowanie modułu

  • Last updated on