Pomocnicze wskazówki dotyczące projektowania

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

Wytyczne dotyczące projektowania

Podczas projektowania poleceń cmdlet należy wziąć pod uwagę następujące wytyczne. 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.

Obsługa parametru InputObject (AD01)

Ponieważ program Windows PowerShell działa bezpośrednio z obiektami programu Microsoft .NET Framework, obiekt .NET Framework jest często dostępny, który dokładnie odpowiada typowi, który użytkownik musi wykonać określoną operację. InputObject to standardowa nazwa parametru, który przyjmuje taki obiekt jako dane wejściowe. Na przykład przykładowe Stop-Proc polecenie cmdlet w samouczku StopProc definiuje InputObject parametr typu Proces, który obsługuje dane wejściowe z potoku. Użytkownik może uzyskać zestaw obiektów procesu, manipulować nimi, aby wybrać dokładne obiekty 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 zastąpienie tej ochrony, jeśli użytkownik ma uprawnienia do wykonania operacji.

Na przykład polecenie cmdlet Remove-Item nie usuwa zwykle pliku tylko do odczytu. To polecenie cmdlet obsługuje jednak parametr Force , aby użytkownik mógł 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 wpływu.

Obsługa poświadczeń za pomocą programu Windows PowerShell (AD03)

Polecenie cmdlet powinno zdefiniować 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 podanie nazwy użytkownika, hasła lub obu tych poleceń, gdy pełne poświadczenie nie zostanie podane bezpośrednio. Aby uzyskać więcej informacji o atrybucie Credential, zobacz Credential Attribute Declaration (Deklaracja atrybutu poświadczeń).

Parametry kodowania obsługi (AD04)

Jeśli polecenie cmdlet odczytuje lub zapisuje tekst do lub z formularza binarnego, takiego jak zapisywanie lub odczytywanie z pliku w systemie plików, polecenie cmdlet musi mieć parametr Kodowanie, który określa, jak tekst jest zakodowany w postaci binarnej.

Polecenia cmdlet testu powinny zwracać wartość logiczną (AD05)

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

Wytyczne dotyczące kodu

Podczas pisania kodu polecenia cmdlet należy wziąć pod uwagę następujące wskazówki. Jeśli znajdziesz wytyczne dotyczące danej sytuacji, zapoznaj się z wytycznymi dotyczącymi projektowania podobnych wytycznych.

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

Postępując zgodnie ze standardowymi konwencjami nazewnictwa, polecenia cmdlet są bardziej wykrywalne i pomagasz użytkownikowi dokładnie zrozumieć, co robią polecenia cmdlet. Ta praktyka jest szczególnie ważna dla innych deweloperów korzystających z programu Windows PowerShell, ponieważ polecenia cmdlet są typami publicznymi.

Definiowanie polecenia cmdlet w prawidłowej przestrzeni nazw

Zwykle należy zdefiniować klasę dla polecenia cmdlet w przestrzeni nazw programu .NET Framework, która dołącza .Commands się do przestrzeni nazw reprezentującej produkt, w którym jest uruchamiane polecenie cmdlet. Na przykład polecenia cmdlet dołączone do programu Windows PowerShell są definiowane w Microsoft.PowerShell.Commands przestrzeni nazw.

Nadaj klasie poleceń cmdlet nazwę zgodną z nazwą polecenia cmdlet

Po nazwie klasy .NET Framework, która implementuje polecenie cmdlet, nadaj klasie <Verb><Noun>Commandnazwę , gdzie zastąpisz <Verb> symbole zastępcze i <Noun> czasownikiem i rzeczownikiem używanym dla nazwy polecenia cmdlet. Na przykład polecenie cmdlet Get-Process jest implementowane przez klasę o nazwie GetProcessCommand.

Jeśli brak danych wejściowych potoku zastępuje metodę 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 programowi Windows PowerShell zachowanie kolejności między poleceniami cmdlet. Pierwsze polecenie cmdlet w potoku zawsze zwraca swoje obiekty przed rozpoczęciem przetwarzania pozostałych poleceń cmdlet w potoku.

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

Zastąpij metodę System.Management.Automation.Cmdlet.StopProcessing , aby polecenie cmdlet obsługiwało sygnał zatrzymania. Wykonanie operacji przez niektóre polecenia cmdlet trwa długo i umożliwia długie przekazywanie między wywołaniami środowiska uruchomieniowego programu Windows PowerShell, na przykład gdy polecenie cmdlet blokuje wątek w długotrwałych wywołaniach wywołań RPC. Obejmuje to polecenia cmdlet, które tworzą wywołania metody System.Management.Automation.Cmdlet.WriteObject , do metody System.Management.Automation.Cmdlet.WriteError oraz do innych mechanizmów przesyłania opinii, które mogą zająć dużo czasu. W takich przypadkach użytkownik może potrzebować wysłania sygnału zatrzymania do tych poleceń cmdlet.

Implementowanie interfejsu IDisposable (AC04)

Jeśli polecenie cmdlet zawiera obiekty, które nie są usuwane (zapisane w potoku) przez metodę System.Management.Automation.Cmdlet.ProcessRecord , polecenie cmdlet może wymagać dodatkowego usuwania 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 , ten uchwyt musi zostać zamknięty na końcu przetwarzania.

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

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

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

Typy pierwotne:

• Byte, SByte, Decimal, Single, Double, Int16, Int32, Int64, Uint16, UInt32 i UInt64.
• Wartość logiczna, Guid, Byte[], TimeSpan, DateTime, Uri i Version.
• Char, String, XmlDocument.

Wbudowane typy ponownego wypełniania:

• PSPrimitiveDictionary
• Parametr przełącznika
• Moduł PSListModifier
• PsCredential
• IPAddress, MailAddress
• Informacje o kulturze
• X509Certificate2, X500DistinguishedName
• DirectorySecurity, FileSecurity, RegistrySecurity

Inne typy:

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

Używanie funkcji SecureString dla danych poufnych (AC06)

W przypadku obsługi danych poufnych należy zawsze używać typu danych System.Security.SecureString . Może to obejmować dane wejściowe potoku do parametrów, a także zwracanie poufnych danych do potoku.

Mimo że platforma .NET zaleca używanie funkcji SecureString do tworzenia nowych rozwiązań, program PowerShell nadal obsługuje klasę SecureString w celu zapewnienia zgodności z poprzednimi wersjami. Korzystanie z protokołu SecureString jest nadal bezpieczniejsze niż używanie ciągu zwykłego tekstu. Program PowerShell nadal korzysta z typu SecureString , aby uniknąć przypadkowego ujawnienia zawartości konsoli lub w dziennikach. Ostrożnie używaj protokołu SecureString , ponieważ można go łatwo przekonwertować na zwykły ciąg tekstowy. Aby zapoznać się z pełną dyskusją na temat używania protokołu SecureString, zobacz dokumentację klasy System.Security.SecureString.

Zobacz też

wymagane wytyczne programistyczne

zdecydowanie zachęcane wytyczne programistyczne

Tworzenie polecenia cmdlet programu Windows PowerShell