Pomocnicze wskazówki dotyczące projektowania

W tej sekcji opisano wytyczne, które należy wziąć pod uwagę w celu zapewnienia dobrego środowiska programowego i środowiska użytkownika. Czasami mogą one mieć zastosowanie, a czasami nie.

Zalecenia dotyczące projektowania

Podczas projektowania polecenia cmdlet należy wziąć pod uwagę poniższe wskazówki. Jeśli znajdziesz wytyczne dotyczące projektowania, które dotyczą Twojej sytuacji, pamiętaj, aby przyjrzeć się wytycznym dotyczącym kodu dla podobnych wytycznych.

Obsługa parametru InputObject (AD01)

Ponieważ Windows PowerShell bezpośrednio z obiektami microsoft .NET Framework, obiekt .NET Framework jest często dostępny dokładnie taki sam jak typ, który użytkownik musi wykonać określonej operacji. InputObject jest standardową nazwą parametru, który przyjmuje taki obiekt jak dane wejściowe. Na przykład przykładowe polecenie cmdlet w samouczku StopProc definiuje parametr typu Proces, który obsługuje dane Stop-Proc wejściowe z InputObject potoku. Użytkownik może uzyskać zestaw obiektów procesu, manipulować nimi w celu wybrania dokładnych obiektów do zatrzymania, a następnie przekazać je bezpośrednio do Stop-Proc polecenia cmdlet.

Obsługa parametru Force (AD02)

Czasami polecenie cmdlet musi chronić użytkownika przed wykonaniem żądanej operacji. Takie polecenie cmdlet powinno obsługiwać parametr Force, aby umożliwić użytkownikowi przesłonięcie tej ochrony, jeśli użytkownik ma uprawnienia do wykonania operacji.

Na przykład polecenie cmdlet Remove-Item zwykle nie usuwa pliku tylko do odczytu. To polecenie cmdlet obsługuje jednak parametr Force, dzięki czemu użytkownik może wymusić usunięcie pliku tylko do odczytu. Jeśli użytkownik ma już uprawnienia do modyfikowania atrybutu tylko do odczytu, a użytkownik usunie plik, użycie parametru Force upraszcza operację. Jeśli jednak użytkownik nie ma uprawnień do usunięcia pliku, parametr Force nie ma żadnego efektu.

Obsługa poświadczeń za pośrednictwem Windows PowerShell (AD03)

Polecenie cmdlet powinno definiować Credential parametr reprezentujący poświadczenia. Ten parametr musi być typu System.Management.Automation.PSCredential i musi być zdefiniowany przy użyciu deklaracji atrybutu Credential. Ta obsługa automatycznie monituje użytkownika o nazwę użytkownika, hasło lub oba te ustawienia, gdy pełne poświadczenia nie zostaną podane bezpośrednio. Aby uzyskać więcej informacji na temat atrybutu Credential, zobacz Credential Attribute Declaration.

Obsługa parametrów kodowania (AD04)

Jeśli polecenie cmdlet odczytuje lub zapisuje tekst do lub z formularza binarnego, takiego jak zapisywanie w pliku lub odczytywanie z pliku w systemie plików, to polecenie cmdlet musi mieć parametr Encoding określający sposób kodowania tekstu w postaci binarnej.

Testowe polecenia cmdlet powinny zwracać wartość logiczną (AD05)

Polecenia cmdlet, które wykonują testy względem swoich zasobów, powinny zwracać do potoku typ System.Boolean, aby można było ich używać w wyrażeniach warunkowych.

Wskazówki dotyczące kodu

Podczas pisania kodu polecenia cmdlet należy wziąć pod uwagę poniższe wskazówki. Jeśli znajdziesz wskazówki dotyczące Twojej sytuacji, pamiętaj, aby przyjrzeć się wytycznym dotyczącym projektowania dla podobnych wytycznych.

Postępuj zgodnie z konwencjami nazewnictwa klas polecenia cmdlet (AC01)

Dzięki standardowym konwencjom nazewnictwa polecenia cmdlet są bardziej wykrywalne i ułatwiają użytkownikowi dokładne zrozumienie ich działania. Ta praktyka jest szczególnie ważna dla innych deweloperów korzystających z Windows PowerShell, ponieważ polecenia cmdlet są typami publicznymi.

Definiowanie polecenia cmdlet w prawidłowej przestrzeni nazw

Zwykle definiuje się klasę dla polecenia cmdlet w przestrzeni nazw .NET Framework , która dołącza ". Polecenia" do przestrzeni nazw, która reprezentuje produkt, w którym jest uruchamiane polecenie cmdlet. Na przykład polecenia cmdlet dołączone do Windows PowerShell są zdefiniowane w przestrzeni Microsoft.PowerShell.Commands nazw .

Nadaj klasie polecenia cmdlet nazwę, która będzie odpowiadać nazwie polecenia cmdlet

Podczas nazywania klasy .NET Framework implementuje polecenie cmdlet, nadaj klasie nazwę " ", w której zastąpisz symbole zastępcze i czasownikiem i rzeczownikiem używanym jako nazwa <Verb><Noun><Command> <Verb> polecenia <Noun> cmdlet. Na przykład polecenie cmdlet Get-Process jest implementowane przez klasę o nazwie GetProcessCommand .

Jeśli żadne dane wejściowe potoku nie zastępują metody BeginProcessing (AC02)

Jeśli polecenie cmdlet nie akceptuje danych wejściowych z potoku, przetwarzanie powinno zostać zaimplementowane w metodzie System.Management.Automation.Cmdlet.BeginProcessing. Użycie tej metody umożliwia Windows PowerShell zachowanie kolejności między poleceniami cmdlet. Pierwsze polecenie cmdlet w potoku zawsze zwraca obiekty, zanim pozostałe polecenia cmdlet w potoku uzyskają możliwość rozpoczęcia przetwarzania.

Aby obsłużyć żądania zatrzymania, zastąp metodę StopProcessing (AC03)

Zastąp metodę System.Management.Automation.Cmdlet.StopProcessing, aby polecenie cmdlet obsługiło sygnał stop. Niektóre polecenia cmdlet mogą zająć dużo czasu, a także długi czas między wywołaniami środowiska uruchomieniowego usługi Windows PowerShell, na przykład gdy polecenie cmdlet blokuje wątek w długotrwałych wywołaniach RPC. Obejmuje to polecenia cmdlet, które wywołuje metodę System.Management.Automation.Cmdlet.WriteObject, do metody System.Management.Automation.Cmdlet.WriteError oraz inne mechanizmy opinii, które mogą zająć dużo czasu. W takich przypadkach użytkownik może potrzebować sygnału zatrzymania do tych cmdlet.

Implementowanie interfejsu IDisposable (AC04)

Jeśli polecenie cmdlet zawiera obiekty, które nie są usuwane (zapisywane w potoku) przez metodę System.Management.Automation.Cmdlet.ProcessRecord, polecenie cmdlet może wymagać dodatkowego usunięcia obiektów. Jeśli na przykład polecenie cmdlet otwiera dojście do pliku w metodzie System.Management.Automation.Cmdlet.BeginProcessing i utrzymuje otwarte dojście do użycia przez metodę System.Management.Automation.Cmdlet.ProcessRecord, to dojście należy zamknąć na końcu przetwarzania.

Środowisko Windows PowerShell uruchomieniowe nie zawsze wywołują metodę System.Management.Automation.Cmdlet.EndProcessing. Na przykład metoda System.Management.Automation.Cmdlet.EndProcessing może nie zostać wywołana, jeśli polecenie cmdlet zostanie anulowane w połowie operacji lub jeśli w dowolnej części polecenia cmdlet wystąpi błąd zakończenia. W związku z tym klasa .NET Framework dla polecenia cmdlet wymagającego oczyszczania obiektów powinna implementować kompletny wzorzec interfejsu System.IDisposable, w tym finalizator, tak aby środowisko uruchomieniowe programu Windows PowerShell może wywołać metody System.Management.Automation.Cmdlet.EndProcessing i System.IDisposable.Dispose* na końcu przetwarzania.

Używanie typów parametrów przyjaznych dla serializacji (AC05)

Aby obsługiwać uruchamianie polecenia cmdlet na komputerach zdalnych, należy użyć typów, które można łatwo serializować na komputerze klienckim, a następnie ponownie na komputerze serwera. Następujące typy są przyjazne dla serializacji.

Typy pierwotne:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 i UInt64.

• Boolean, Guid, Byte[], TimeSpan, DateTime, Uri i Version.

• Char, String, XmlDocument.

Wbudowane typy ponownego hydrowania:

• PSPrimitiveDictionary

• SwitchParameter

• PSListModifier

• PSCredential

• IPAddress, MailAddress

• Cultureinfo

• X509Certificate2, X500DistinguishedName

• DirectorySecurity, FileSecurity, RegistrySecurity

Inne typy:

• Securestring

• Kontenery (listy i słowniki powyższego typu)

Używanie funkcji SecureString dla danych poufnych (AC06)

Podczas obsługi poufnych danych zawsze używaj typu danych System.Security.Securestring. Może to obejmować dane wejściowe potoku do parametrów, a także zwracanie poufnych danych do potoku.

Zobacz też

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

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

Pisanie polecenia cmdlet programu Windows PowerShell