Wskazówki dotyczące projektowania — użycie zdecydowanie zalecane

  • Artykuł

W tej sekcji opisano wytyczne, które należy wykonać podczas pisania polecenia cmdlet. Są one podzielone na wytyczne dotyczące projektowania polecenia cmdlet i wytyczne dotyczące pisania kodu polecenia cmdlet. Może się okazać, że te wytyczne nie mają zastosowania w każdym scenariuszu. Jeśli jednak te zalecenia nie są stosowane i nie są zgodne z tymi wytycznymi, użytkownicy mogą mieć złe doświadczenie podczas korzystania z twoich polecenia cmdlet.

Zalecenia dotyczące projektowania

Podczas projektowania polecenia cmdlet należy przestrzegać poniższych wytycznych, aby zapewnić spójne środowisko użytkownika między używaniem ich a innymi poleceniami cmdlet. Jeśli znajdziesz wytyczne dotyczące projektowania, które dotyczą Twojej sytuacji, pamiętaj, aby przyjrzeć się wytycznym dotyczącym kodu dla podobnych wytycznych.

Używanie określonego rzeczownika dla nazwy polecenia cmdlet (SD01)

Rzeczowniki używane w nazewnictwa polecenia cmdlet muszą być bardzo specyficzne, aby użytkownik może odnaleźć twoje polecenia cmdlet. Prefiks dla rzeczowników ogólnych, takich jak "serwer", skróconą wersją nazwy produktu. Jeśli na przykład rzeczownik odwołuje się do serwera z uruchomionym wystąpieniem Microsoft SQL Server, użyj rzeczownika, takiego jak "SQLServer". Kombinacja określonych rzeczowników i krótkiej listy zatwierdzonych czasowników umożliwia użytkownikowi szybkie odnajdywanie i przewidywanie funkcji przy jednoczesnym uniknięciu duplikowania nazw polecenia cmdlet.

Aby ulepszyć środowisko użytkownika, rzeczownik, który wybierzesz dla nazwy polecenia cmdlet, powinien być pojedynczej. Na przykład użyj nazwy Get-Process zamiast Get-Processes . Najlepiej przestrzegać tej reguły dla wszystkich nazw polecenia cmdlet, nawet jeśli polecenie cmdlet może działać na więcej niż jednym elementze.

Użyj pascal case dla nazw polecenia cmdlet (SD02)

W nazwach parametrów należy używać liter Pascal. Innymi słowy, pierwszą literę czasownika i wszystkie terminy używane w rzeczowniku należy ująć w literę . Na przykład „Clear-ItemProperty”.

Wytyczne dotyczące projektowania parametrów (SD03)

Polecenie cmdlet wymaga parametrów, które odbierają dane, na których musi działać, oraz parametrów wskazujących informacje używane do określenia właściwości operacji. Na przykład polecenie cmdlet może mieć parametr, który odbiera dane z potoku, a polecenie cmdlet może mieć parametr wskazujący, że polecenie cmdlet może zostać wymuszone do wykonania Name Force jego operacji. Nie ma żadnego ograniczenia liczby parametrów, które można zdefiniować za pomocą polecenia cmdlet.

Używanie standardowych nazw parametrów

Polecenie cmdlet powinno używać standardowych nazw parametrów, aby użytkownik może szybko określić, co oznacza określony parametr. Jeśli wymagana jest bardziej konkretną nazwa, użyj standardowej nazwy parametru, a następnie podaj bardziej konkretną nazwę jako alias. Na przykład polecenie cmdlet ma parametr o nazwie Get-Service ogólnej ( ) i bardziej Name specyficznym aliasie ( ServiceName ). Oba terminy mogą służyć do określania parametru.

Aby uzyskać więcej informacji o nazwach parametrów i ich typach danych, zobacz Cmdlet Parameter Name and Functionality Guidelines (Wytyczne dotyczące nazwy i funkcjonalności parametrów polecenia cmdlet).

Używanie nazw parametrów w pojedynczej

Unikaj używania nazw w liczbie mnogiej dla parametrów, których wartość jest pojedynczym elementem. Obejmuje to parametry, które przyjmą tablice lub listy, ponieważ użytkownik może podać tablicę lub listę tylko z jednym elementem.

Nazwy parametrów w liczbie mnogiej powinny być używane tylko w przypadkach, gdy wartość parametru jest zawsze wartością wielo elementową. W takich przypadkach polecenie cmdlet powinno sprawdzić, czy jest podanych wiele elementów, a polecenie cmdlet powinno wyświetlać ostrzeżenie dla użytkownika, jeśli wiele elementów nie zostanie dostarczonych.

Użyj pascal case dla nazw parametrów

W nazwach parametrów należy używać liter Pascal. Innymi słowy, pierwszą literę każdego wyrazu w nazwie parametru należy w tym pierwszą literę nazwy. Na przykład nazwa parametru ErrorAction używa poprawnej liter. Następujące nazwy parametrów używają niepoprawnej liter:

  • errorAction
  • erroraction

Parametry, które mają listę opcji

Istnieją dwa sposoby tworzenia parametru, którego wartość można wybrać z zestawu opcji.

  • Zdefiniuj typ wyliczenia (lub użyj istniejącego typu wyliczenia) określający prawidłowe wartości. Następnie użyj typu wyliczenia, aby utworzyć parametr tego typu.

  • Dodaj atrybut ValidateSet do deklaracji parametru. Aby uzyskać więcej informacji na temat tego atrybutu, zobacz ValidateSet Attribute Declaration.

Używanie typów standardowych dla parametrów

Aby zapewnić spójność z innymi poleceniami cmdlet, używaj typów standardowych dla parametrów tam, gdzie to możliwe. Aby uzyskać więcej informacji o typach, które powinny być używane dla różnych parametrów, zobacz Nazwy i typy parametrów standardowego polecenia cmdlet. Ten temat zawiera linki do kilku tematów opisujących nazwy i typy .NET Framework dla grup standardowych parametrów, takich jak "parametry działania".

Używanie Strongly-Typed .NET Framework typów

Parametry należy zdefiniować jako typy .NET Framework, aby zapewnić lepszą walidację parametrów. Na przykład parametry, które są ograniczone do jednej wartości z zestawu wartości, powinny być zdefiniowane jako typ wyliczenia. Aby obsługiwać Uniform Resource Identifier (URI), zdefiniuj parametr jako typ System.Uri. Unikaj podstawowych parametrów ciągu dla wszystkich właściwości tekstu o foremce wolnej.

Używanie spójnych typów parametrów

Jeśli ten sam parametr jest używany przez wiele polecenia cmdlet, zawsze używaj tego samego typu parametru. Jeśli na przykład parametr jest typem System.Int16 dla jednego polecenia cmdlet, nie należy określać parametru dla innego polecenia Process Process cmdlet typem System.Uint16.

Parametry, które mają wartość true i false

Jeśli parametr przyjmuje tylko wartości true i false , zdefiniuj parametr jako typ System.Management.Automation.SwitchParameter. Parametr switch jest traktowany true jak określony w poleceniu. Jeśli parametr nie jest uwzględniony w poleceniu, Windows PowerShell wartość parametru to false . Nie należy definiować parametrów logicznych.

Jeśli parametr musi rozróżnić 3 wartości: $true, $false i "nieokreślony", zdefiniuj parametr typu Dopuszcza wartość <bool> null. Potrzeba trzeciej, "nieokreślonych" wartości zwykle występuje, gdy polecenie cmdlet może modyfikować właściwość logiczną obiektu. W tym przypadku "nieokreślony" oznacza, że nie należy zmieniać bieżącej wartości właściwości.

Obsługa tablic dla parametrów

Często użytkownicy muszą wykonać tę samą operację względem wielu argumentów. W przypadku tych użytkowników polecenie cmdlet powinno akceptować tablicę jako dane wejściowe parametrów, dzięki czemu użytkownik może przekazać argumenty do parametru jako zmienną Windows PowerShell zmienną. Na przykład polecenie cmdlet Get-Process używa tablicy dla ciągów, które identyfikują nazwy procesów do pobrania.

Obsługa parametru PassThru

Domyślnie wiele polecenia cmdlet modyfikujące system, takich jak polecenie cmdlet Stop-Process, działa jako "ujścia" dla obiektów i nie zwraca wyniku. Te polecenie cmdlet powinno implementować parametr , aby wymusić zwrócenie obiektu przez polecenie PassThru cmdlet. Jeśli parametr jest określony, polecenie cmdlet zwraca obiekt przy użyciu wywołania metody PassThru System.Management.Automation.Cmdlet.WriteObject. Na przykład następujące polecenie zatrzymuje proces calc i przekazuje wynikowy proces do potoku.

Stop-Process calc -passthru

W większości przypadków polecenia cmdlet Add, Set i New powinny obsługiwać PassThru parametr .

Obsługa zestawów parametrów

Polecenie cmdlet ma na celu osiągnięcie jednego celu. Jednak często istnieje więcej niż jeden sposób opisania operacji lub obiektu docelowego operacji. Na przykład proces może być identyfikowany przez jego nazwę, identyfikator lub obiekt procesu. Polecenie cmdlet powinno obsługiwać wszystkie uzasadnione reprezentacje swoich celów. Zwykle polecenie cmdlet spełnia to wymaganie, określając zestawy parametrów (nazywane zestawami parametrów), które działają razem. Pojedynczy parametr może należeć do dowolnej liczby zestawów parametrów. Aby uzyskać więcej informacji na temat zestawów parametrów, zobacz Zestawy parametrów polecenia cmdlet.

Podczas określania zestawów parametrów ustaw tylko jeden parametr w zestawie na wartość ValueFromPipeline. Aby uzyskać więcej informacji na temat deklarowania atrybutu Parameter, zobacz ParameterAttribute Declaration.

Gdy są używane zestawy parametrów, domyślny zestaw parametrów jest definiowany przez atrybut polecenia cmdlet. Domyślny zestaw parametrów powinien zawierać parametry, które najprawdopodobniej będą używane w sesji Windows PowerShell interaktywnej. Aby uzyskać więcej informacji na temat deklarowania atrybutu polecenia cmdlet, zobacz Deklarację atrybutu CmdletAttribute.

Przekazać opinię użytkownikowi (SD04)

Skorzystaj z wytycznych w tej sekcji, aby przekazać opinię użytkownikowi. Dzięki tej opinii użytkownik może wiedzieć, co dzieje się w systemie, i podejmować lepsze decyzje administracyjne.

Środowisko Windows PowerShell uruchomieniowe umożliwia użytkownikowi określenie sposobu obsługi danych wyjściowych z każdego wywołania metody przez Write ustawienie zmiennej preferencji. Użytkownik może ustawić kilka zmiennych preferencji, w tym zmienną, która określa, czy system powinien wyświetlać informacje, i zmienną, która określa, czy system powinien odpytują użytkownika przed podjęciem dalszych działań.

Obsługa metod WriteWarning, WriteVerbose i WriteDebug

Polecenie cmdlet powinno wywołać metodę System.Management.Automation.Cmdlet.WriteWarning, gdy polecenie cmdlet ma wykonać operację, która może mieć niezamierzony wynik. Na przykład polecenie cmdlet powinno wywołać tę metodę, jeśli polecenie cmdlet ma zastąpić plik tylko do odczytu.

Polecenie cmdlet powinno wywołać metodę System.Management.Automation.Cmdlet.WriteVerbose, gdy użytkownik wymaga szczegółowych informacji o tym, co robi polecenie cmdlet. Na przykład polecenie cmdlet powinno wywołać te informacje, jeśli autor polecenia cmdlet uważa, że istnieją scenariusze, które mogą wymagać dodatkowych informacji o tym, co robi polecenie cmdlet.

Polecenie cmdlet powinno wywołać metodę System.Management.Automation.Cmdlet.WriteDebug, gdy deweloper lub inżynier pomocy technicznej produktu musi zrozumieć, co zostało uszkodzone w operacji polecenia cmdlet. Nie jest konieczne, aby polecenie cmdlet wywołać metodę System.Management.Automation.Cmdlet.WriteDebug w tym samym kodzie, który wywołuje metodę System.Management.Automation.Cmdlet.WriteVerbose, ponieważ parametr przedstawia oba zestawy Debug informacji.

Obsługa writeProgress dla operacji, które długo trwają

Operacje cmdlet, których ukończenie trwa długo i których nie można uruchomić w tle, powinny obsługiwać raportowanie postępu za pośrednictwem okresowych wywołań metody System.Management.Automation.Cmdlet.WriteProgress.

Korzystanie z interfejsów hosta

Czasami polecenie cmdlet musi komunikować się bezpośrednio z użytkownikiem, a nie przy użyciu różnych metod Write lub Should obsługiwanych przez klasę System.Management.Automation.Cmdlet. W takim przypadku polecenie cmdlet powinno pochodzić z klasy System.Management.Automation.PSCmdlet i używać właściwości System.Management.Automation.PSCmdlet.Host*. Ta właściwość obsługuje różne poziomy typu komunikacji, w tym typy PromptForChoice, Prompt i WriteLine/ReadLine. Na najbardziej specyficznym poziomie zapewnia również sposoby odczytu i zapisu poszczególnych kluczy oraz radzenia sobie z buforami.

O ile polecenie cmdlet nie zostało specjalnie zaprojektowane do generowania graficznego interfejsu użytkownika (GUI), nie powinno pomijać hosta przy użyciu właściwości System.Management.Automation.PSCmdlet.Host*. Przykładem polecenia cmdlet przeznaczonego do generowania graficznego interfejsu użytkownika jest polecenie cmdlet Out-GridView.

Uwaga

Polecenia cmdlet nie powinny używać interfejsu API System.Console.

Tworzenie pliku pomocy polecenia cmdlet (SD05)

Dla każdego zestawu polecenia cmdlet utwórz plik Help.xml zawierający informacje o poleceni cmdlet. Te informacje obejmują opis polecenia cmdlet, opisy parametrów polecenia cmdlet, przykłady użycia polecenia cmdlet i nie tylko.

Wytyczne dotyczące kodu

Podczas kodowania polecenia cmdlet należy przestrzegać poniższych wytycznych, aby zapewnić spójne środowisko użytkownika między używaniem tych i innych. W przypadku znalezienia wytycznych dotyczących kodu, które dotyczą Twojej sytuacji, pamiętaj, aby przyjrzeć się wytycznym dotyczącym projektowania dla podobnych wytycznych.

Parametry kodowania (SC01)

Zdefiniuj parametr, deklarując właściwość publiczną klasy polecenia cmdlet, która jest dekorowana za pomocą atrybutu Parameter. Parametry nie muszą być statycznymi składami klasy pochodnej .NET Framework polecenia cmdlet. Aby uzyskać więcej informacji na temat deklarowania atrybutu parameter, zobacz Deklaracja atrybutu parametru.

Obsługa Windows PowerShell ścieżek

Ścieżka Windows PowerShell jest mechanizmem normalizacji dostępu do przestrzeni nazw. Po przypisaniu Windows PowerShell do parametru w poleceniach cmdlet użytkownik może zdefiniować niestandardowy "dysk", który działa jako skrót do określonej ścieżki. Gdy użytkownik wyznaczy taki dysk, dane przechowywane, takie jak dane w rejestrze, mogą być używane w spójny sposób.

Jeśli polecenie cmdlet umożliwia użytkownikowi określenie pliku lub źródła danych, należy zdefiniować parametr typu System.String. Jeśli obsługiwanych jest więcej niż jeden dysk, typ powinien być tablicą. Nazwa parametru powinna mieć wartość Path , z aliasem PSPath . Ponadto parametr powinien Path obsługiwać symbole wieloznaczne. Jeśli obsługa symboli wieloznacznych nie jest wymagana, zdefiniuj LiteralPath parametr.

Jeśli dane odczytywane lub zapisywane przez polecenie cmdlet muszą być plikami, polecenie cmdlet powinno akceptować dane wejściowe ścieżki Windows PowerShell, a polecenie cmdlet powinno używać właściwości System.Management.Automation.Sessionstate.Path, aby przetłumaczyć ścieżki Windows PowerShell na ścieżki rozpoznane przez system plików. Konkretne mechanizmy obejmują następujące metody:

Jeśli dane odczytywane lub zapisywane przez polecenie cmdlet są tylko zestawem ciągów zamiast pliku, polecenie cmdlet powinno używać informacji o zawartości dostawcy (członek) do odczytu i Content zapisu. Te informacje są uzyskiwane z właściwości System.Management.Automation.Provider.CmdletProvider.InvokeProvider. Te mechanizmy umożliwiają innym magazynom danych uczestnictwo w odczytywaniu i zapisie danych.

Obsługa symboli wieloznacznych

Jeśli to możliwe, polecenie cmdlet powinno obsługiwać symbole wieloznaczne. Obsługa symboli wieloznacznych występuje w wielu miejscach w poleceniach cmdlet (szczególnie wtedy, gdy parametr przyjmuje ciąg w celu zidentyfikowania jednego obiektu z zestawu obiektów). Na przykład przykładowe Stop-Proc polecenie cmdlet z samouczka StopProc definiuje parametr do obsługi ciągów Name reprezentujących nazwy procesów. Ten parametr obsługuje symbole wieloznaczne, dzięki czemu użytkownik może łatwo określić procesy do zatrzymania.

Gdy jest dostępna obsługa symboli wieloznacznych, operacja polecenia cmdlet zwykle tworzy tablicę. Czasami obsługa tablicy nie ma sensu, ponieważ użytkownik może jednocześnie używać tylko jednego elementu. Na przykład polecenie cmdlet Set-Location nie musi obsługiwać tablicy, ponieważ użytkownik ustawia tylko jedną lokalizację. W tym przypadku polecenie cmdlet nadal obsługuje symbole wieloznaczne, ale wymusza rozdzielczość do pojedynczej lokalizacji.

Aby uzyskać więcej informacji na temat wzorców symboli wieloznacznych, zobacz Obsługa symboli wieloznacznych w parametrach polecenia cmdlet.

Definiowanie obiektów

Ta sekcja zawiera wytyczne dotyczące definiowania obiektów dla polecenia cmdlet i rozszerzania istniejących obiektów.

Definiowanie standardowych elementów członkowskich

Definiowanie standardowych elementów członkowskich w celu rozszerzenia typu obiektu w niestandardowym pliku Types.ps1xml (użyj pliku Types.ps1xml Windows PowerShell types.ps1xml jako szablonu). Standardowe elementy członkowskie są definiowane przez węzeł o nazwie PSStandardMembers. Definicje te umożliwiają innym poleceniam cmdlet i Windows PowerShell uruchomieniowe pracę z obiektem w spójny sposób.

Definiowanie właściwości ObjectMembers, które mają być używane jako parametry

Jeśli projektujesz obiekt dla polecenia cmdlet, upewnij się, że jego elementy członkowskie są mapowane bezpośrednio na parametry polecenia cmdlet, które będą go używać. To mapowanie umożliwia łatwe wysłanie obiektu do potoku i jego przekazanie z jednego polecenia cmdlet do innego.

W przypadku .NET Framework, które są zwracane przez polecenia cmdlet, często brakuje niektórych ważnych lub wygodnych elementów członkowskich, które są wymagane przez dewelopera lub użytkownika skryptu. Te brakujące elementy członkowskie mogą być szczególnie ważne w przypadku wyświetlania i tworzenia poprawnych nazw elementów członkowskich, dzięki czemu obiekt może być prawidłowo przekazywany do potoku. Utwórz niestandardowy plik Types.ps1xml, aby udokumentować te wymagane elementy członkowskie. Podczas tworzenia tego pliku zalecamy następującą konwencję nazewnictwa: <Your_Product_Name>. Types.ps1xml.

Na przykład można dodać właściwość script do typu Mode System.IO.FileInfo, aby bardziej czytelnie wyświetlić atrybuty pliku. Ponadto można dodać właściwość aliasu do typu Count System.Array, aby umożliwić spójne użycie tej nazwy właściwości (zamiast Length ).

Implementowanie interfejsu IComparable

Implementowanie interfejsu System.IComparable na wszystkich obiektach wyjściowych. Umożliwia to łatwe potokowanie obiektów wyjściowych do różnych cmdlet sortowania i analizy.

Aktualizowanie informacji wyświetlanych

Jeśli wyświetlanie obiektu nie zapewnia oczekiwanych wyników, utwórz niestandardowy obiekt <YourProductName> . Plik Format.ps1xml dla tego obiektu.

Obsługa dobrze zdefiniowanych danych wejściowych potoku (SC02)

Implementowanie na środku potoku

Zaim implementuj polecenie cmdlet przy założeniu, że zostanie ono wywołane z środka potoku (czyli inne polecenia cmdlet będą tworzyć jego dane wejściowe lub korzystać z danych wyjściowych). Można na przykład założyć, że polecenie cmdlet , ponieważ generuje dane, jest używane tylko jako Get-Process pierwsze polecenie cmdlet w potoku. Jednak ponieważ to polecenie cmdlet jest przeznaczone dla środka potoku, to polecenie cmdlet umożliwia poprzednim poleceniem cmdlet lub danych w potoku określenie procesów do pobrania.

Obsługa danych wejściowych z potoku

W każdym zestawie parametrów dla polecenia cmdlet uwzględnij co najmniej jeden parametr, który obsługuje dane wejściowe z potoku. Obsługa danych wejściowych potoku umożliwia użytkownikowi pobieranie danych lub obiektów, wysyłanie ich do poprawnego zestawu parametrów i bezpośrednie przesyłanie wyników do polecenia cmdlet.

Parametr akceptuje dane wejściowe z potoku, jeśli atrybut Parameter zawiera słowo kluczowe, atrybut słowa kluczowego lub oba słowa ValueFromPipeline kluczowe w jego ValueFromPipelineByPropertyName deklaracji. Jeśli żaden z parametrów w zestawie parametrów nie obsługuje słów kluczowych lub , nie można w zrozumiały sposób umieścić polecenia cmdlet po innym ValueFromPipeline poleceniem cmdlet, ponieważ zignoruje on wszelkie dane ValueFromPipelineByPropertyName wejściowe potoku.

Obsługa metody ProcessRecord

Aby akceptować wszystkie rekordy z poprzedniego polecenia cmdlet w potoku, należy zaimplementować metodę System.Management.Automation.Cmdlet.ProcessRecord. Windows PowerShell wywołuje tę metodę wielokrotnie, raz dla każdego rekordu wysyłanego do polecenia cmdlet.

Zapis pojedynczych rekordów w potoku (SC03)

Gdy polecenie cmdlet zwraca obiekty, polecenie cmdlet powinno zapisywać obiekty natychmiast po ich wygenerowaniu. Polecenie cmdlet nie powinno ich przechowywać w celu ich buforowania w połączonej tablicy. Polecenia cmdlet, które odbierają obiekty jako dane wejściowe, będą mogły przetwarzać, wyświetlać lub przetwarzać i wyświetlać obiekty wyjściowe bez opóźnień. Polecenie cmdlet, które generuje obiekty wyjściowe po jednym na raz, powinno wywołać metodę System.Management.Automation.Cmdlet.WriteObject. Polecenie cmdlet, które generuje obiekty wyjściowe w partiach (na przykład ponieważ bazowy interfejs API zwraca tablicę obiektów wyjściowych), powinno wywołać metodę System.Management.Automation.Cmdlet.WriteObject z drugim parametrem ustawionym na true .

Make Cmdlets Case-Insensitive and Case-Preserving (SC04)

Domyślnie w Windows PowerShell jest bez uwzględniania liter. Jednak ze względu na to, że obsługuje ona wiele wcześniejistniejących systemów, Windows PowerShell zachowuje przypadek w celu ułatwienia obsługi i zgodności. Innymi słowy, jeśli znak jest podany w wielkich literach, Windows PowerShell przechowuje go w wielkich literach. Aby systemy działały dobrze, polecenie cmdlet musi być zgodne z tą konwencją. Jeśli to możliwe, powinna działać bez uwzględniania liter. Należy jednak zachować oryginalną literę poleceń cmdlet, które występują później w poleceniu lub potoku.

Zobacz też

Wskazówki dotyczące projektowania — użycie wymagane

Pomocnicze wskazówki dotyczące projektowania

Pisanie polecenia cmdlet programu Windows PowerShell