Wskazówki dotyczące projektowania — użycie wymagane
Podczas pisania polecenia cmdlet należy przestrzegać poniższych wytycznych. Są one podzielone na wytyczne dotyczące projektowania polecenia cmdlet i wytyczne dotyczące pisania kodu polecenia cmdlet. Jeśli nie będziesz stosować się do tych wytycznych, polecenia cmdlet mogą się nie powieść, a użytkownicy będą mieć złe doświadczenie podczas korzystania z twoich polecenia cmdlet.
W tym temacie
Zalecenia dotyczące projektowania
Wytyczne dotyczące kodu
Zalecenia dotyczące projektowania
Podczas projektowania polecenia cmdlet należy przestrzegać poniższych wytycznych w celu zapewnienia spójnego środowiska użytkownika między korzystaniem z tych i innych. W przypadku znalezienia wytycznych dotyczących projektowania, które mają zastosowanie do Twojej sytuacji, pamiętaj, aby przyjrzeć się wytycznym dotyczącym kodu dla podobnych wytycznych.
Używaj tylko zatwierdzonych czasowników (RD01)
Czasownik określony w atlicie polecenia cmdlet musi pochodzić z rozpoznanego zestawu zleceń dostarczonych przez Windows PowerShell. Nie może to być jeden z zabronionych synonimów. Użyj ciągów stałych zdefiniowanych przez następujące wyliczenia, aby określić czasowniki polecenia cmdlet:
Aby uzyskać więcej informacji na temat zatwierdzonych nazw zleceń, zobacz Polecenia cmdlet Verbs.
Użytkownicy potrzebują zestawu wykrywalnych i oczekiwanych nazw cmdlet. Użyj odpowiedniego czasownika, aby użytkownik może szybko dokonać oceny działania polecenia cmdlet i łatwo odnaleźć możliwości systemu. Na przykład następujące polecenie wiersza polecenia pobiera listę wszystkich poleceń w systemie, których nazwy zaczynają się od "start": get-command start-* . Użyj rzeczowników w poleceniach cmdlet, aby odróżnić polecenia cmdlet od innych. Rzeczownik wskazuje zasób, na którym zostanie wykonana operacja. Sama operacja jest reprezentowana przez czasownik.
Nazwy polecenia cmdlet: znaki, których nie można użyć (RD02)
Podczas nazywania polecenia cmdlet nie należy używać żadnego z następujących znaków specjalnych.
| Znak | Nazwa |
|---|---|
| # | znak numeru |
| , | Przecinek |
| () | Nawiasy |
| {} | Nawiasy klamrowe |
| [] | Nawiasach |
| & | Ampersand |
| - | łącznik Uwaga: łącznik może służyć do oddzielania czasownika od rzeczownika, ale nie może być używany w rzeczowniku ani w czasowniku. |
| / | Ukośnikiem |
| \ | ukośnik odwrotny |
| $ | znak dolara |
| ^ | daszek |
| ; | Średnik |
| : | Dwukropek |
| " | podwójny cudzysłów |
| ' | pojedynczy cudzysłów |
| <> | Nawiasy |
| | | pionowy pasek |
| ? | znak zapytania |
| @ | na znak |
| ` | znacznik wstecz (akcent akcentu) |
| * | gwiazdka |
| % | znak procentu |
| + | znak plus |
| = | znak równości |
| ~ | Tyldy |
Nazwy parametrów, których nie można użyć (RD03)
Windows PowerShell udostępnia wspólny zestaw parametrów dla wszystkich polecenia cmdlet oraz dodatkowe parametry, które są dodawane w określonych sytuacjach. Podczas projektowania własnych cmdlet nie można używać następujących nazw: Confirm, Debug, ErrorAction, ErrorVariable, OutBuffer, OutVariable, WarningAction, WarningVariable, WhatIf, UseTransaction i Verbose. Aby uzyskać więcej informacji na temat tych parametrów, zobacz Typowe nazwy parametrów.
Obsługa żądań potwierdzenia (RD04)
Polecenia cmdlet, które wykonują operację modyfikującą system, powinny wywołać metodę System.Management.Automation.Cmdlet.Cmdlet.ShouldProcess*, aby zażądać potwierdzenia, a w szczególnych przypadkach wywołać metodę System.Management.Automation.Cmdlet.ShouldContinue*. (Metoda System.Management.Automation.Cmdlet.ShouldContinue* powinna być wywoływana dopiero po wywołaniu metody System.Management.Automation.Cmdlet.ShouldProcess*).
Aby wykonać te wywołania, polecenie cmdlet musi określić, że obsługuje żądania potwierdzenia, ustawiając słowo kluczowe SupportsShouldProcess atrybutu polecenia cmdlet. Aby uzyskać więcej informacji na temat ustawiania tego atrybutu, zobacz Deklaracji atrybutu polecenia cmdlet.
Uwaga
Jeśli atrybut polecenia cmdlet klasy cmdlet wskazuje, że polecenie cmdlet obsługuje wywołania metody System.Management.Automation.Cmdlet.Cmdlet.ShouldProcess*, a polecenie cmdlet nie może wykonać wywołania metody System.Management.Automation.Cmdlet.ShouldProcess*, użytkownik może nieoczekiwanie zmodyfikować system.
Użyj metody System.Management.Automation.Cmdlet.ShouldProcess* w celu modyfikacji systemu. Preferencje użytkownika i WhatIf parametr kontrolują metodę System.Management.Automation.Cmdlet.ShouldProcess*. Z kolei wywołanie System.Management.Automation.Cmdlet.ShouldContinue* wykonuje dodatkowe sprawdzanie potencjalnie niebezpiecznych modyfikacji. Ta metoda nie jest kontrolowana przez żadnych preferencji użytkownika lub WhatIf parametru. Jeśli twoje polecenie cmdlet wywołuje metodę System.Management.Automation.Cmdlet.ShouldContinue*, powinno ono mieć parametr, który pomija wywołania tych dwóch metod i kontynuuje Force operację. Jest to ważne, ponieważ umożliwia korzystanie z polecenia cmdlet w nieinterakcyjnych skryptach i hostach.
Jeśli polecenia cmdlet obsługują te wywołania, użytkownik może określić, czy rzeczywiście należy wykonać akcję. Na przykład polecenie cmdlet Stop-Process wywołuje metodę System.Management.Automation.Cmdlet.ShouldContinue* przed zatrzymaniem zestawu procesów krytycznych, w tym procesów System, Winlogon i Spoolsv.
Aby uzyskać więcej informacji na temat obsługi tych metod, zobacz Żądanie potwierdzenia.
Obsługa parametru Force dla sesji interaktywnych (RD05)
Jeśli twoje polecenie cmdlet jest używane interaktywnie, zawsze podaj parametr Force, aby przesłonić akcje interaktywne, takie jak monity lub odczytywanie wierszy danych wejściowych). Jest to ważne, ponieważ umożliwia korzystanie z polecenia cmdlet w nieinterakcyjnych skryptach i hostach. Następujące metody mogą być implementowane przez hosta interakcyjnego.
System.Management.Automation.Host.PSHostUserInterface.Prompt*
System.Management.Automation.Host.Pshostuserinterface.PromptForChoice
System.Management.Automation.Host.Ihostuisupportsmultiplechoiceselection.PromptForChoice
System.Management.Automation.Host.Pshostuserinterface.PromptForCredential*
System.Management.Automation.Host.Pshostuserinterface.ReadLine*
System.Management.Automation.Host.Pshostuserinterface.ReadLineAsSecureString*
Udokumentuj obiekty wyjściowe (RD06)
Windows PowerShell używa obiektów zapisywanych w potoku. Aby użytkownicy mogą korzystać z obiektów zwracanych przez każde polecenie cmdlet, należy udokumentować zwracane obiekty i udokumentować elementy członkowskie tych zwracanych obiektów.
Wytyczne dotyczące kodu
Podczas pisania kodu polecenia cmdlet należy przestrzegać poniższych wytycznych. W przypadku znalezienia wytycznych dotyczących kodu, które dotyczą Twojej sytuacji, pamiętaj, aby przyjrzeć się wytycznym dotyczącym projektowania dla podobnych wytycznych.
Wyprowadzanie z klas polecenia cmdlet lub PSCmdlet (RC01)
Polecenie cmdlet musi pochodzić z klasy bazowej System.Management.Automation.Cmdlet lub System.Management.Automation.PSCmdlet. Polecenia cmdlet pochodzące z klasy System.Management.Automation.Cmdlet nie zależą od Windows PowerShell uruchomieniowego. Mogą być wywoływane bezpośrednio z dowolnego języka .NET Framework Microsoft. Polecenia cmdlet pochodzące z klasy System.Management.Automation.PSCmdlet zależą od Windows PowerShell uruchomieniowego. W związku z tym są one wykonywane w przestrzeni uruchamiania.
Wszystkie implementowane klasy polecenia cmdlet muszą być klasami publicznymi. Aby uzyskać więcej informacji o tych klasach polecenia cmdlet, zobacz Omówienie polecenia cmdlet.
Określanie atrybutu polecenia cmdlet (RC02)
Aby polecenie cmdlet było rozpoznawane przez Windows PowerShell, jego klasa .NET Framework musi być dekorowana za pomocą atrybutu polecenia cmdlet. Ten atrybut określa następujące funkcje polecenia cmdlet.
Para czasownik-i-rzeczownik identyfikująca polecenie cmdlet.
Domyślny zestaw parametrów, który jest używany, gdy określono wiele zestawów parametrów. Domyślny zestaw parametrów jest używany, gdy Windows PowerShell nie ma wystarczających informacji, aby określić, który parametr ma być używany.
Wskazuje, czy polecenie cmdlet obsługuje wywołania metody System.Management.Automation.Cmdlet.ShouldProcess*. Ta metoda wyświetla użytkownikowi komunikat potwierdzający, zanim polecenie cmdlet zmieni system. Aby uzyskać więcej informacji na temat sposobu żądania potwierdzenia, zobacz Żądanie potwierdzenia.
Wskaż poziom wpływu (lub ważność) akcji skojarzonej z komunikatem potwierdzającym. W większości przypadków należy użyć wartości domyślnej Średni. Aby uzyskać więcej informacji o tym, jak poziom wpływu wpływa na żądania potwierdzenia wyświetlane użytkownikowi, zobacz Żądanie potwierdzenia.
Aby uzyskać więcej informacji na temat deklarowania atrybutu polecenia cmdlet, zobacz Deklarację atrybutu CmdletAttribute.
Zastępowanie metody przetwarzania danych wejściowych (RC03)
Aby polecenie cmdlet uczestniczyło w środowisku Windows PowerShell, musi zastąpić co najmniej jedną z następujących metod przetwarzania danych wejściowych.
System.Management.Automation.Cmdlet.BeginProcessing Ta metoda jest wywoływana jeden raz i służy do zapewnienia funkcji wstępnego przetwarzania.
System.Management.Automation.Cmdlet.ProcessRecord Ta metoda jest wywoływana wiele razy i służy do zapewnienia funkcji rekord po rekordzie.
System.Management.Automation.Cmdlet.EndProcessing Ta metoda jest wywoływana jeden raz i służy do zapewnienia funkcji przetwarzania końcowego.
Określanie atrybutu OutputType (RC04)
Atrybut OutputType (wprowadzony w Windows PowerShell 2.0) określa typ .NET Framework zwracany przez polecenie cmdlet do potoku. Określając typ danych wyjściowych polecenia cmdlet, obiekty zwracane przez to polecenie cmdlet są bardziej wykrywalne przez inne polecenia cmdlet. Aby uzyskać więcej informacji na temat dekorowania klasy polecenia cmdlet za pomocą tego atrybutu, zobacz OutputType Attribute Declaration.
Nie należy zachowywać dojść do obiektów wyjściowych (RC05)
Polecenie cmdlet nie powinno zachowywać żadnych dojść do obiektów przekazywanych do metody System.Management.Automation.Cmdlet.WriteObject*. Te obiekty są przekazywane do następnego polecenia cmdlet w potoku lub są używane przez skrypt. Jeśli zachowasz dojścia do obiektów, dwie jednostki będą właścicielami każdego obiektu, co powoduje błędy.
Niezawodna obsługa błędów (RC06)
Środowisko administracyjne z założenia wykrywa i wprowadza ważne zmiany w systemie, którym administrujesz. Dlatego ważne jest, aby polecenia cmdlet prawidłowo obsługiły błędy. Aby uzyskać więcej informacji na temat rekordów błędów, zobacz Windows PowerShell Raportowanie błędów.
Jeśli błąd uniemożliwia kontynuowanie przetwarzania kolejnych rekordów przez polecenie cmdlet, jest to błąd kończący. Polecenie cmdlet musi wywołać metodę System.Management.Automation.Cmdlet.ThrowTerminatingError*, która odwołuje się do obiektu System.Management.Automation.ErrorRecord. Jeśli wyjątek nie zostanie przechwycony przez polecenie cmdlet, środowisko Windows PowerShell uruchomieniowe zgłasza błąd kończący, który zawiera mniej informacji.
W przypadku błędu niepowodujące zakończenia, który nie zatrzymuje operacji na następnym rekordzie, który pochodzi z potoku (na przykład rekordu produkowanego przez inny proces), polecenie cmdlet musi wywołać metodę System.Management.Automation.Cmdlet.WriteError*, która odwołuje się do obiektu System.Management.Automation.ErrorRecord. Przykładem błędu niepowiązywające się z zakończeniem jest błąd, który występuje, gdy nie można zatrzymać określonego procesu. Wywołanie metody System.Management.Automation.Cmdlet.WriteError* umożliwia użytkownikowi spójne wykonywanie żądanych akcji i zachowywanie informacji dla określonych akcji, które się nie powiodą. Polecenie cmdlet powinno obsługiwać każdy rekord tak niezależnie, jak to możliwe.
Obiekt System.Management.Automation.ErrorRecord, do których odwołują się metody System.Management.Automation.Cmdlet.ThrowTerminatingError* i System.Management.Automation.Cmdlet.WriteError*, wymaga wyjątku. Podczas określania wyjątku do użycia postępuj zgodnie .NET Framework wytycznymi dotyczącymi projektowania. Jeśli błąd jest semantycznie taki sam jak istniejący wyjątek, należy użyć tego wyjątku lub pochodzić od tego wyjątku. W przeciwnym razie należy uzyskać nową hierarchię wyjątków lub wyjątków bezpośrednio z typu System.Exception.
Obiekt System.Management.Automation.ErrorRecord wymaga również kategorii błędów, która grupuje błędy dla użytkownika. Użytkownik może wyświetlać błędy na podstawie kategorii, ustawiając wartość zmiennej $ErrorView powłoki na CategoryView. Możliwe kategorie są definiowane przez wyliczenie System.Management.Automation.ErrorCategory.
Jeśli polecenie cmdlet tworzy nowy wątek, a kod uruchomiony w tym wątku zgłasza nieobsługiwany wyjątek, program Windows PowerShell nie przechwyci błędu i zakończy proces.
Jeśli obiekt ma w destruktorze kod, który powoduje nieobsługiwany wyjątek, Windows PowerShell nie przechwyci błędu i zakończy proces. Dzieje się tak również wtedy, gdy obiekt wywołuje metody Dispose, które powodują nieobsługiwany wyjątek.
Wdrażanie Windows PowerShell cmdlet za pomocą modułu administracyjnego (RC07)
Utwórz moduł Windows PowerShell, aby spakować i wdrożyć polecenia cmdlet. Obsługa modułów została wprowadzona w Windows PowerShell 2.0. Zestawów zawierających klasy polecenia cmdlet można używać bezpośrednio jako plików modułu binarnego (jest to bardzo przydatne podczas testowania polecenia cmdlet) lub można utworzyć manifest modułu, który odwołuje się do zestawów polecenia cmdlet. (Podczas korzystania z modułów można również dodać istniejące zestawy przyciągnij). Aby uzyskać więcej informacji na temat modułów, zobacz Writing a Windows PowerShell Module (Pisanie modułu Windows PowerShell module).
Zobacz też
Wskazówki dotyczące projektowania — użycie zdecydowanie zalecane
Opinia
Dostępne już wkrótce: W 2024 r. będziemy stopniowo wycofywać zgłoszenia z serwisu GitHub jako mechanizm przesyłania opinii na temat zawartości i zastępować go nowym systemem opinii. Aby uzyskać więcej informacji, sprawdź: https://aka.ms/ContentUserFeedback.
Prześlij i wyświetl opinię dla