Zdecydowanie zalecane wytyczne dotyczące rozwoju

W tej sekcji opisano wskazówki, które należy przestrzegać podczas pisania poleceń cmdlet. Są rozdzielone na wytyczne dotyczące projektowania poleceń 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 mają one zastosowanie i nie przestrzegasz tych wytycznych, użytkownicy mogą mieć złe doświadczenie podczas korzystania z cmdletów.

Wytyczne dotyczące projektowania

Podczas projektowania cmdletów należy przestrzegać poniższych wskazówek, aby zapewnić spójne doświadczenie użytkownika porównywalne z używaniem innych cmdletów. Jeśli znajdziesz wytyczne dotyczące projektowania, które mają zastosowanie do Twojej sytuacji, zapoznaj się z wytycznymi kodowania odnoszącymi się do podobnych wytycznych.

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

Rzeczowniki używane w nazewnictwie poleceń cmdlet muszą być bardzo konkretne, aby użytkownik mógł je łatwo odnaleźć. Poprzedź ogólne rzeczowniki, takie jak "serwer", skróconą wersją nazwy produktu. Jeśli na przykład rzeczownik odnosi się do serwera z uruchomionym wystąpieniem programu Microsoft SQL Server, użyj rzeczownika takiego jak "SQLServer". Kombinacja określonych czasowników i krótkiej listy zatwierdzonych czasowników umożliwia użytkownikowi szybkie odnajdywanie i przewidywanie funkcjonalności przy jednoczesnym unikaniu duplikowania nazw poleceń cmdlet.

Aby ulepszyć doświadczenia użytkownika, rzeczownik wybrany dla nazwy polecenia cmdlet powinien być w liczbie pojedynczej. Na przykład użyj nazwy Get-Process zamiast Get-Processes. Najlepiej przestrzegać tej reguły dla wszystkich nazw poleceń cmdlet, nawet jeśli polecenie cmdlet może działać na więcej niż jednym elemencie.

Użyj wielkości liter pascal dla nazw poleceń cmdlet (SD02)

Użyj stylu zapisu Pascal dla nazw parametrów. Innymi słowy, użyj wielkiej litery na początku czasownika i dla wszystkich terminów używanych w rzeczowniku. Na przykład „Clear-ItemProperty”.

Wytyczne dotyczące projektowania parametrów (SD03)

Polecenie cmdlet wymaga parametrów odbierających dane, na których musi działać, oraz parametrów, które wskazują informacje używane do określania cech operacji. Na przykład polecenie cmdlet może mieć parametr Name, który odbiera dane z potoku, a polecenie cmdlet może mieć parametr Force wskazujący, że polecenie cmdlet może być zmuszone do wykonania operacji. Nie ma limitu 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 mógł szybko określić, co oznacza określony parametr. Jeśli wymagana jest bardziej określona nazwa, użyj standardowej nazwy parametru, a następnie określ bardziej konkretną nazwę jako alias. Na przykład polecenie cmdlet Get-Service ma parametr o nazwie ogólnej (Name) i bardziej szczegółowym aliasie (ServiceName). Oba terminy mogą służyć do określenia parametru.

Aby uzyskać więcej informacji na temat nazw parametrów i ich typów danych, zobacz Cmdlet Nazwa parametru i Wytyczne dotyczące funkcjonalności.

Używanie pojedynczych nazw parametrów

Unikaj używania nazw w liczbie mnogiej dla parametrów, których wartość jest pojedynczym elementem. Obejmuje to parametry, które przyjmują 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 tych przypadkach, gdy wartość parametru jest zawsze wartością wieloelementową. W takich przypadkach polecenie cmdlet powinno sprawdzić, czy podano wiele elementów, a polecenie cmdlet powinno wyświetlić ostrzeżenie dla użytkownika, jeśli nie podano wielu elementów.

Użyj zapisu "Pascal Case" dla nazw parametrów

Użyj zapisu PascalCase dla nazw parametrów. Innymi słowy, napisz wielką literą pierwszą literę każdego wyrazu w nazwie parametru, w tym pierwszą literę samej nazwy. Na przykład nazwa parametru ErrorAction używa poprawnej wielkości liter. Następujące nazwy parametrów używają nieprawidłowych liter:

• errorAction
• erroraction

Parametry, które przyjmują 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), który określa 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 o tym atrybucie, zobacz ValidateSet Attribute Declaration.

Używanie typów standardowych dla parametrów

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

Korzystanie z typów programu .NET Framework Strongly-Typed

Parametry powinny być zdefiniowane 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ć wartość identyfikatora URI (Uniform Resource Identifier), zdefiniuj parametr jako typ System.Uri. Unikaj podstawowych parametrów ciągu znaków z wyjątkiem właściwości tekstu o dowolnej formie.

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

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

Parametry, które przyjmują wartość True i False

Jeśli parametr przyjmuje tylko true i false, zdefiniuj parametr jako typ System.Management.Automation.SwitchParameter. Parametr przełącznika jest traktowany jako true, gdy jest określony w poleceniu. Jeśli parametr nie jest uwzględniony w poleceniu, program Windows PowerShell uzna wartość parametru za false. Nie należy definiować parametrów logicznych.

Jeśli parametr musi rozróżniać 3 wartości: $true, $false i "nieokreślony", zdefiniuj parametr typu Nullable<bool>. Zapotrzebowanie na trzecią wartość „nieokreśloną” zwykle występuje, gdy cmdlet może zmodyfikować właściwość logiczną obiektu. W tym przypadku "nieokreślony" oznacza, że nie 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. Dla tych użytkowników polecenie cmdlet powinno zaakceptować tablicę jako parametr wejściowy, aby użytkownik mógł przekazać argumenty wejściowe do parametru jako zmienną programu Windows PowerShell. Na przykład polecenie cmdlet Get-Process używa tablicy zawierającej ciągi identyfikujące nazwy procesów do pobrania.

Obsługa parametru PassThru

Domyślnie wiele poleceń cmdlet modyfikujących system, takich jak polecenie cmdlet Stop-Process, działa jako "ujścia" dla obiektów i nie zwraca wyniku. Te polecenia cmdlet powinny zaimplementować parametr PassThru, aby wymusić zwrócenie obiektu. Po określeniu parametru PassThru polecenie cmdlet zwraca obiekt, używając wywołania metody System.Management.Automation.Cmdlet.WriteObject. Na przykład następujące polecenie zatrzymuje program Calc (CalculatorApp.exe) i przekazuje powstały proces do potoku danych.

Stop-Process -Name CalculatorApp -PassThru

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

Obsługa zestawów parametrów

Polecenie cmdlet jest przeznaczone do osiągnięcia jednego konkretnego celu. Jednak często istnieje więcej niż jeden sposób opisywania operacji lub celu operacji. Na przykład proces może być identyfikowany według jego nazwy, identyfikatora lub obiektu procesu. Polecenie cmdlet powinno obsługiwać wszystkie uzasadnione odwzorowania swoich obiektów docelowych. Zwykle polecenie cmdlet spełnia to wymaganie, określając zestawy parametrów (określane jako zestawy 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 poleceń Cmdlet.

Po określeniu zestawów parametrów ustaw tylko jeden parametr w zestawie na WartośćFromPipeline. Aby uzyskać więcej informacji na temat deklarowania atrybutu Parametru, zobacz Deklaracja atrybutu Parametru.

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

Prześlij opinię użytkownikowi (SD04)

Skorzystaj z wytycznych w tej sekcji, aby przekazać opinię użytkownikowi. Ta opinia pozwala użytkownikowi znać, co dzieje się w systemie i podejmować lepsze decyzje administracyjne.

Środowisko uruchomieniowe programu Windows PowerShell umożliwia użytkownikowi określenie sposobu obsługi danych wyjściowych z każdego wywołania do metody Write przez 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 wysyłać zapytanie do 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 uszkodziło operację polecenia cmdlet. Nie jest konieczne, aby polecenie cmdlet wywoływało metodę System.Management.Automation.Cmdlet.WriteDebug w tym samym kodzie co metoda System.Management.Automation.Cmdlet.WriteVerbose, ponieważ parametr Debug przedstawia oba zestawy informacji.

Obsługa operacji WriteProgress, które zajmują dużo czasu

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

Korzystanie z interfejsów hosta

Czasami cmdlet musi komunikować się bezpośrednio z użytkownikiem, zamiast korzystać z 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żyć właściwości System.Management.Automation.PSCmdlet.Host*. Ta właściwość obsługuje różne poziomy komunikacji, w tym typy PromptForChoice, Prompt i WriteLine/ReadLine. Na najbardziej konkretnym poziomie zapewnia również sposoby odczytywania i zapisywania kluczy indywidualnych oraz zarządzania buforami.

O ile polecenie cmdlet nie jest 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 poleceń cmdlet (SD05)

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

Wytyczne dotyczące kodu

Podczas kodowania poleceń cmdlet należy przestrzegać poniższych wskazówek, aby zapewnić spójne doświadczenie użytkownika między używaniem twoich poleceń cmdlet a innymi poleceniami cmdlet. Kiedy znajdziesz wytyczne dotyczące kodu, które pasują do twojej sytuacji, upewnij się, że zapoznałeś się z wytycznymi projektowymi dotyczącymi podobnych sytuacji.

Parametry kodowania (SC01)

Zdefiniuj parametr, deklarując właściwość publiczną klasy cmdlet, która jest ozdobiona atrybutem Parametr. Parametry nie muszą być statycznymi członkami klasy .NET Framework pochodnej dla polecenia cmdlet. Aby uzyskać więcej informacji na temat deklarowania parametru atrybutu, zobacz Deklarację atrybutu parametru.

Obsługa ścieżek programu Windows PowerShell

Ścieżka środowiska Windows PowerShell to mechanizm normalizacji dostępu do przestrzeni nazw. Po przypisaniu ścieżki środowiska Windows PowerShell do parametru w poleceniu 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, przechowywane dane, 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, powinien zdefiniować parametr typu System.String. Jeśli obsługiwany jest więcej niż jeden dysk, typ powinien być tablicą. Nazwa parametru powinna być Path, z aliasem PSPath. Ponadto parametr Path powinien obsługiwać symbole wieloznaczne. Jeśli obsługa symboli wieloznacznych nie jest wymagana, zdefiniuj parametr LiteralPath.

Jeśli dane, które polecenie cmdlet odczytuje lub zapisuje, musi być plikiem, polecenie cmdlet powinno zaakceptować dane wejściowe ścieżki środowiska Windows PowerShell, a polecenie cmdlet powinno użyć właściwości System.Management.Automation.SessionState.Path, aby przetłumaczyć ścieżki programu Windows PowerShell na ścieżki rozpoznawane przez system plików. Określone mechanizmy obejmują następujące metody:

• System.Management.Automation.PSCmdlet.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PSCmdlet.GetUnresolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetResolvedProviderPathFromPSPath
• System.Management.Automation.PathIntrinsics.GetUnresolvedProviderPathFromPSPath

Jeśli dane, które cmdlet odczytuje lub zapisuje, stanowią tylko zestaw ciągów znaków zamiast pliku, cmdlet powinien używać informacji o zawartości dostawcy (członkaContent) do odczytu i 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 zapisywaniu 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 poleceniu cmdlet (zwłaszcza gdy parametr przyjmuje ciąg w celu zidentyfikowania jednego obiektu z zestawu obiektów). Na przykład przykładowe polecenie cmdlet Stop-Proc z samouczka StopProc definiuje parametr Name do obsługi ciągów reprezentujących nazwy procesów. Ten parametr obsługuje symbole wieloznaczne, dzięki czemu użytkownik może łatwo określić procesy do zatrzymania.

Kiedy dostępna jest obsługa symboli wieloznacznych, operacja polecenia cmdlet zwykle tworzy tablicę. Czasami nie ma sensu obsługiwać tablicy, ponieważ użytkownik może używać tylko jednego elementu w danym momencie. Przykładowo, polecenie cmdlet Set-Location nie musi obsługiwać tablicy, ponieważ użytkownik ustawia tylko pojedynczą lokalizację. W tym przypadku polecenie cmdlet nadal obsługuje symbole wieloznaczne, ale wymusza rozpoznawanie pojedynczej lokalizacji.

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

Definiowanie obiektów

Ta sekcja zawiera wskazówki dotyczące definiowania obiektów dla poleceń cmdlet i rozszerzania istniejących obiektów.

Zdefiniuj standardowych członków

Zdefiniuj standardowe elementy członkowskie, aby rozszerzyć typ obiektu w pliku "custom Types.ps1xml" (użyj pliku Windows PowerShell Types.ps1xml jako szablonu). Standardowe elementy członkowskie są definiowane przez węzeł o nazwie PSStandardMembers. Te definicje umożliwiają innym poleceniom cmdlet i środowisku uruchomieniowemu Windows PowerShell pracować z twoim obiektem w spójny sposób.

Zdefiniuj elementy ObjectMembers do użycia jako parametry

Jeśli projektujesz obiekt dla polecenia cmdlet, upewnij się, że jego członkowie odnoszą się bezpośrednio do parametrów poleceń cmdlet, które będą go używać. To mapowanie umożliwia łatwe wysyłanie obiektu do potoku oraz przekazywanie go z jednej funkcji cmdlet do innej.

Istniejące obiekty .NET Framework, które są zwracane przez polecenia cmdlet, często nie mają niektórych ważnych lub przydatnych członków, których potrzebuje deweloper lub użytkownik skryptu. Te brakujące członkowie mogą być szczególnie istotne dla wyświetlania oraz dla stworzenia poprawnych nazw członków, co umożliwia poprawne przekazanie obiektu do potoku. Utwórz niestandardowy plik Types.ps1xml, aby udokumentować te wymagane elementy. Podczas tworzenia tego pliku zalecamy następującą konwencję nazewnictwa: <Your_Product_Name>. Types.ps1xml.

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

Implementowanie interfejsu IComparable

Zaimplementuj interfejs System.IComparable na wszystkich obiektach wyjściowych. Dzięki temu obiekty wyjściowe mogą być łatwo pipetowane do różnych cmdletów sortowania i analizy.

Aktualizowanie informacji o wyświetlaniu

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

Wsparcie dobrze zdefiniowanych danych wejściowych pipeline'u (SC02)

Implementacja dla środka rurociągu

Zaimplementuj cmdlet, zakładając, że będzie wywoływany z środka potoku (czyli inne cmdlety będą generować dane wejściowe lub zużywać dane wyjściowe). Można na przykład założyć, że polecenie cmdlet Get-Process, ponieważ generuje dane, jest używane tylko jako pierwsze w potoku. Jednak ponieważ to polecenie cmdlet jest przeznaczone do użycia w środku potoku, umożliwia ono wcześniejszym poleceniom cmdlet lub danym w potoku określenie procesów do pobrania.

Obsługa danych wejściowych z potoku

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

Parametr akceptuje dane wejściowe z potoku, jeśli atrybut parametru zawiera słowo kluczowe ValueFromPipeline, atrybut słowa kluczowego ValueFromPipelineByPropertyName lub oba słowa kluczowe w jego deklaracji. Jeśli żaden z parametrów w zestawie parametrów nie obsługuje słów kluczowych ValueFromPipeline lub ValueFromPipelineByPropertyName, polecenia cmdlet nie można sensownie użyć po innym poleceniu cmdlet, ponieważ zignoruje ono wszelkie dane wejściowe potoku.

Obsługa metody ProcessRecord

Aby przyjąć wszystkie rekordy z poprzedniego polecenia cmdlet w potoku, twoje polecenie cmdlet musi implementować metodę System.Management.Automation.Cmdlet.ProcessRecord. Program Windows PowerShell wywołuje tę metodę wiele razy, raz dla każdego rekordu wysyłanego do cmdletu.

Zapisywanie pojedynczych rekordów w potoku (SC03)

Gdy polecenie cmdlet zwraca obiekty, polecenie cmdlet powinno zapisywać obiekty natychmiast po ich wygenerowaniu. Polecenie cmdlet nie powinno przechowywać ich w celu buforowania ich 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 pojedynczo, powinno wywołać metodę System.Management.Automation.Cmdlet.WriteObject. Polecenie cmdlet, które generuje obiekty wyjściowe w partiach (na przykład ponieważ podstawowy interfejs API zwraca tablicę obiektów wyjściowych), powinno wywołać metodę System.Management.Automation.Cmdlet.WriteObject Method z drugim parametrem ustawionym na true.

Tworzenie poleceń cmdlet Case-Insensitive i Case-Preserving (SC04)

Domyślnie Windows PowerShell nie rozróżnia wielkości liter. Jednak ponieważ współpracuje z wieloma istniejącymi systemami, program Windows PowerShell zachowuje wielkość liter, aby ułatwić działanie i zapewnić zgodność. Innymi słowy, jeśli znak jest dostarczany w wielkich literach, program Windows PowerShell przechowuje go w wielkich literach. Aby systemy działały dobrze, polecenie cmdlet musi przestrzegać tej konwencji. Jeśli to możliwe, powinno działać w sposób niewrażliwy na wielkość liter. Należy jednak zachować oryginalną formę poleceń cmdlet, które pojawiają się w dalszej części polecenia lub w potoku.

Zobacz też

wymagane wytyczne programistyczne

Wytyczne dotyczące rozwoju poradnictwa

Tworzenie polecenia cmdlet programu Windows PowerShell