Nuta
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Podczas pisania poleceń cmdlet należy przestrzegać poniższych wskazówek. Są one oddzielone wytycznymi dotyczącymi projektowania poleceń cmdlet i wytycznych dotyczących pisania kodu polecenia cmdlet. Jeśli nie przestrzegasz tych wytycznych, polecenia cmdlet mogą zakończyć się niepowodzeniem, a użytkownicy mogą mieć słabe środowisko podczas korzystania z poleceń cmdlet.
W tym temacie
Wytyczne dotyczące projektowania
nazwy poleceń cmdlet : znaki, których nie można użyć (RD02)
Wytyczne dotyczące kodu
wdrażanie poleceń cmdlet (RC07) przy użyciu modułu windows PowerShell
Wytyczne dotyczące projektowania
Podczas projektowania poleceń cmdlet należy przestrzegać poniższych wskazówek, aby zapewnić spójne środowisko użytkownika między używaniem poleceń cmdlet i innymi poleceniami cmdlet. Jeśli znajdziesz wytyczne dotyczące projektowania, które dotyczą Twojej sytuacji, zapoznaj się z wytycznymi dotyczącymi kodu dotyczącymi podobnych wytycznych.
Używaj tylko zatwierdzonych zleceń (RD01)
Czasownik określony w atrybucie Cmdlet musi pochodzić z rozpoznanego zestawu zleceń dostarczonych przez program Windows PowerShell. Nie może być jednym z zakazanych synonimów. Użyj ciągów stałych zdefiniowanych przez następujące wyliczenia, aby określić czasowniki poleceń cmdlet:
Aby uzyskać więcej informacji na temat zatwierdzonych nazw czasowników, zobacz polecenia cmdlet verbs.
Użytkownicy potrzebują zestawu nazw poleceń cmdlet możliwych do odnalezienia i oczekiwanych. Użyj odpowiedniego czasownika, aby użytkownik mógł szybko ocenić, co robi polecenie cmdlet i aby ł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 nouns w poleceniach cmdlet, aby odróżnić polecenia cmdlet od innych poleceń cmdlet. Noun wskazuje zasób, na którym zostanie wykonana operacja. Sama operacja jest reprezentowana przez czasownik.
Nazwy poleceń cmdlet: znaki, których nie można użyć (RD02)
Podczas nadawania nazw poleceń cmdlet nie należy używać żadnego z następujących znaków specjalnych.
| Charakter | Nazwa |
|---|---|
| # | znak numeru |
| , | przecinek |
| () | nawiasy |
| {} | szelki |
| [] | Nawiasach |
| & | ampersand |
| - | łącznik Uwaga: Łącznik może służyć do oddzielenia czasownika od ownika, ale nie może być używany w dzielniku ani w czasowniku. |
| / | Ukośnikiem |
| \ | ukośnik odwrotny |
| $ | znak dolara |
| ^ | caret |
| ; | średnik |
| : | dwukropek |
| " | podwójny cudzysłów |
| ' | pojedynczy cudzysłów |
| <> | Nawiasy |
| | | pionowy pasek |
| ? | znak zapytania |
| @ | pod znakiem |
| ` | tyka wsteczna (akcent grobowy) |
| * | gwiazdka |
| % | znak procentu |
| + | plus |
| = | znak równości |
| ~ | tylda |
Nazwy parametrów, których nie można użyć (RD03)
Program Windows PowerShell udostępnia wspólny zestaw parametrów dla wszystkich poleceń cmdlet oraz dodatkowe parametry, które są dodawane w określonych sytuacjach. Podczas projektowania własnych poleceń 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 Common Parameter Names.
Żądania potwierdzenia pomocy technicznej (RD04)
W przypadku poleceń cmdlet wykonujących operację modyfikującą system należy wywołać metodę System.Management.Automation.Cmdlet.ShouldProcess*, aby zażądać potwierdzenia, a w specjalnych przypadkach wywołać metodę System.Management.Automation.Cmdlet.ShouldContinue*. (Metoda System.Management.Automation.Cmdlet.ShouldContinue* powinna być wywoływana tylko 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 SupportsShouldProcess słowo kluczowe atrybutu cmdlet. Aby uzyskać więcej informacji na temat ustawiania tego atrybutu, zobacz deklaracji atrybutu polecenia cmdlet.
Uwaga
Jeśli atrybut cmdlet klasy cmdlet wskazuje, że polecenie cmdlet obsługuje wywołania metody System.Management.Automation.Cmdlet.ShouldProcess*, a polecenie cmdlet nie może wywołać metody System.Management.Automation.Cmdlet.ShouldProcess*, użytkownik może nieoczekiwanie zmodyfikować system.
Użyj metody System.Management.Automation.Cmdlet.ShouldProcess* dla każdej modyfikacji systemu. Preferencja użytkownika i parametr WhatIf kontrolują metodę System.Management.Automation.Cmdlet.ShouldProcess*. Natomiast wywołanie System.Management.Automation.Cmdlet.ShouldContinue* wykonuje dodatkowe sprawdzanie pod kątem potencjalnie niebezpiecznych modyfikacji. Ta metoda nie jest kontrolowana przez żadne preferencje użytkownika ani parametr WhatIf. Jeśli polecenie cmdlet wywołuje metodę System.Management.Automation.Cmdlet.ShouldContinue*, powinien mieć Force parametr, który pomija wywołania tych dwóch metod i który kontynuuje operację. Jest to ważne, ponieważ umożliwia użycie polecenia cmdlet w skryptach nieinterakcyjnych i hostach.
Jeśli polecenia cmdlet obsługują te wywołania, użytkownik może określić, czy akcja powinna zostać wykonana. 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 systemowych, Winlogon i Spoolsv.
Aby uzyskać więcej informacji na temat obsługi tych metod, zobacz Żądanie potwierdzenia.
Parametr force pomocy technicznej dla sesji interakcyjnych (RD05)
Jeśli polecenie cmdlet jest używane interaktywnie, zawsze podaj parametr Force, aby zastąpić akcje interakcyjne, takie jak monity lub odczytywanie wierszy danych wejściowych). Jest to ważne, ponieważ umożliwia użycie polecenia cmdlet w skryptach nieinterakcyjnych i hostach. Następujące metody można zaimplementować na hoście interaktywnym.
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*
Obiekty wyjściowe dokumentu (RD06)
Program Windows PowerShell używa obiektów zapisywanych w potoku. Aby użytkownicy korzystali z obiektów zwracanych przez każde polecenie cmdlet, należy udokumentować zwracane obiekty i udokumentować, do czego służą elementy członkowskie tych zwracanych obiektów.
Wytyczne dotyczące kodu
Podczas pisania kodu polecenia cmdlet należy przestrzegać poniższych wskazówek. Jeśli znajdziesz wytyczne dotyczące kodu, które dotyczą Twojej sytuacji, zapoznaj się z wytycznymi dotyczącymi projektowania podobnych wytycznych.
Wyprowadzanie z klas cmdlet lub PSCmdlet (RC01)
Polecenie cmdlet musi pochodzić z System.Management.Automation.Cmdlet lub System.Management.Automation.PSCmdlet klasy bazowej. Polecenia cmdlet pochodzące z klasy System.Management.Automation.Cmdlet nie zależą od środowiska uruchomieniowego programu Windows PowerShell. Mogą być wywoływane bezpośrednio z dowolnego języka programu Microsoft .NET Framework. Polecenia cmdlet pochodzące z klasy System.Management.Automation.PSCmdlet zależą od środowiska uruchomieniowego programu Windows PowerShell. W związku z tym są one wykonywane w przestrzeni uruchomieniowej.
Wszystkie zaimplementowane klasy poleceń cmdlet muszą być klasami publicznymi. Aby uzyskać więcej informacji na temat tych klas poleceń cmdlet, zobacz Cmdlet Overview.
Określ atrybut polecenia cmdlet (RC02)
Aby polecenie cmdlet było rozpoznawane przez program Windows PowerShell, jego klasa .NET Framework musi być ozdobiona atrybutem Cmdlet. Ten atrybut określa następujące funkcje polecenia cmdlet.
Para czasowników i noun identyfikujących polecenie cmdlet.
Domyślny zestaw parametrów używany podczas określania wielu zestawów parametrów. Domyślny zestaw parametrów jest używany, gdy program Windows PowerShell nie ma wystarczającej ilości 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 przed wprowadzeniem zmiany w systemie przez polecenie cmdlet. Aby uzyskać więcej informacji na temat sposobu wykonywania żądań potwierdzenia, zobacz Żądanie potwierdzenia.
Wskaż poziom wpływu (lub ważność) akcji skojarzonej z komunikatem potwierdzenia. W większości przypadków należy użyć wartości domyślnej Medium. Aby uzyskać więcej informacji na temat wpływu na poziom wpływu na żądania potwierdzenia wyświetlane użytkownikowi, zobacz Żądanie potwierdzenia.
Aby uzyskać więcej informacji na temat deklarowania atrybutu polecenia cmdlet, zobacz CmdletAttribute Declaration.
Przesłanianie metody przetwarzania danych wejściowych (RC03)
Aby polecenie cmdlet uczestniczyło w środowisku programu 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 jednorazowo i jest używana do zapewnienia funkcji przetwarzania wstępnego.
System.Management.Automation.Cmdlet.ProcessRecord Ta metoda jest wywoływana wiele razy i służy do udostępniania funkcji rekordu po rekordzie.
System.Management.Automation.Cmdlet.EndProcessing Ta metoda jest wywoływana jednorazowo i jest używana do zapewnienia funkcji przetwarzania końcowego.
Określ atrybut OutputType (RC04)
Atrybut OutputType (wprowadzony w programie Windows PowerShell 2.0) określa typ programu .NET Framework, który polecenie cmdlet powraca do potoku. Określając typ danych wyjściowych poleceń cmdlet, które sprawiają, że obiekty zwracane przez polecenie cmdlet są bardziej wykrywalne przez inne polecenia cmdlet. Aby uzyskać więcej informacji na temat dekorowania klasy cmdlet za pomocą tego atrybutu, zobacz deklaracji atrybutu OutputType.
Nie zachowaj dojść do obiektów wyjściowych (RC05)
Polecenie cmdlet nie powinno przechowywać ż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 natury wykrywa i wprowadza ważne zmiany w administrowanym systemie. Dlatego ważne jest, aby polecenia cmdlet prawidłowo obsługiwały błędy. Aby uzyskać więcej informacji na temat rekordów błędów, zobacz Raportowanie błędów programu Windows PowerShell.
Gdy błąd uniemożliwia kontynuowanie przetwarzania kolejnych rekordów przez polecenie cmdlet, jest to błąd zakończenia. Polecenie cmdlet musi wywołać metodę System.Management.Automation.Cmdlet.ThrowTerminatingError* odwołującą się do obiektu System.Management.Automation.ErrorRecord. Jeśli wyjątek nie zostanie przechwycony przez polecenie cmdlet, środowisko uruchomieniowe programu Windows PowerShell zgłasza błąd zakończenia zawierający mniej informacji.
W przypadku błędu, który nie zatrzymuje operacji na następnym rekordzie pochodzącym z potoku (na przykład rekord wygenerowany 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, który nie kończy się, jest błąd, który występuje, jeśli określony proces nie zostanie zatrzymany. Wywołanie metody System.Management.Automation.Cmdlet.WriteError* umożliwia użytkownikowi spójne wykonywanie żądanych akcji i zachowywanie informacji dotyczących określonych akcji, które kończą się niepowodzeniem. Polecenie cmdlet powinno obsługiwać każdy rekord tak niezależnie, jak to możliwe.
Obiekt System.Management.Automation.ErrorRecord, do którego odwołuje się System.Management.Automation.Cmdlet.ThrowTerminatingError* i System.Management.Automation.Cmdlet.WriteError* metody wymagają wyjątku. Podczas określania wyjątku do użycia postępuj zgodnie z wytycznymi projektowymi programu .NET Framework. Jeśli błąd jest semantycznie taki sam jak istniejący wyjątek, użyj tego wyjątku lub pochodzi z tego wyjątku. W przeciwnym razie utwórz nowy wyjątek lub hierarchię wyjątków bezpośrednio z typu System.Exception.
Obiekt System.Management.Automation.ErrorRecord wymaga również kategorii błędów grupujących błędy dla użytkownika. Użytkownik może wyświetlać błędy na podstawie kategorii, ustawiając wartość zmiennej powłoki $ErrorView 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 kod w destruktorze, który powoduje nieobsługiwany wyjątek, program Windows PowerShell nie przechwyci błędu i zakończy proces. Dzieje się tak również, jeśli obiekt wywołuje metody Dispose, które powodują nieobsługiwany wyjątek.
Wdrażanie poleceń cmdlet za pomocą modułu środowiska Windows PowerShell (RC07)
Utwórz moduł programu Windows PowerShell, aby spakować i wdrożyć polecenia cmdlet. Obsługa modułów jest wprowadzana w programie Windows PowerShell 2.0. Zestawy zawierające klasy poleceń cmdlet można używać bezpośrednio jako plików modułów binarnych (jest to bardzo przydatne podczas testowania poleceń cmdlet) lub utworzyć manifest modułu odwołujący się do zestawów poleceń cmdlet. (W przypadku korzystania z modułów można również dodawać istniejące zestawy przystawki). Aby uzyskać więcej informacji na temat modułów, zobacz Pisanie modułu programu Windows PowerShell.
Zobacz też
zdecydowanie zachęcane wytyczne programistyczne
Współpracuj z nami na GitHub
Źródło tej zawartości można znaleźć w witrynie GitHub, gdzie można również tworzyć i przeglądać problemy oraz żądania ściągnięcia. Aby uzyskać więcej informacji, zapoznaj się z naszym przewodnikiem dla twórców.
