Jak dodać nazwę polecenia cmdlet i streszczenie do tematu pomocy dotyczącego polecenia cmdletHow to Add the Cmdlet Name and Synopsis to a Cmdlet Help Topic

W tej sekcji opisano, jak dodać zawartość, która jest wyświetlana w sekcjach Nazwa i streszczenie w pomocy polecenia cmdlet.This section describes how to add content that is displayed in the NAME and SYNOPSIS sections of the cmdlet help. W pliku pomocy ta zawartość jest dodawana do węzła poleceń dla każdego polecenia cmdlet.In the Help file, this content is added to the Command node for each cmdlet.

Uwaga

Aby uzyskać pełny wgląd w plik pomocy, otwórz jeden z dll-Help.xml plików znajdujących się w katalogu instalacyjnym programu PowerShell.For a complete view of a Help file, open one of the dll-Help.xml files located in the PowerShell installation directory. Na przykład Microsoft.PowerShell.Commands.Management.dll-Help.xml plik zawiera zawartość dla kilku poleceń cmdlet programu PowerShell.For example, the Microsoft.PowerShell.Commands.Management.dll-Help.xml file contains content for several of the PowerShell cmdlets.

Aby dodać nazwę polecenia cmdlet i streszczenieTo Add the Cmdlet Name and a Synopsis

  • W pomocy polecenia cmdlet można wyświetlić dwa opisy poleceń cmdlet.The cmdlet Help can display two descriptions for the cmdlet. Pierwszy opis to krótki opis, który jest określany jako streszczenie.The first description is a short description that is referred to as the synopsis. Drugi opis to bardziej szczegółowy opis, który został omówiony w temacie Dodawanie szczegółowego opisu do tematu pomocy poleceń cmdlet.The second description is a more detailed description that is discussed in Adding the Detailed Description to a Cmdlet Help Topic. Oba te opisy powinny być zapisywane w pojedynczym akapicie.Both these descriptions should be written as a single paragraph.

  • W polu streszczenia nie powtarzaj nazwy polecenia cmdlet.In the synopsis do not repeat the cmdlet name. Informowanie użytkownika o Get-Server pobieraniu serwera przez polecenie cmdlet jest krótkie, ale nie w formie informacyjnej.Informing the user that the Get-Server cmdlet gets a server is brief, but not informative. Zamiast tego należy użyć synonimów i dodać szczegóły do opisu.Instead, use synonyms and add details to the description.

    Przykład: "pobiera obiekt, który reprezentuje komputer lokalny lub zdalny".Example: "Gets an object that represents a local or remote computer."

  • Użyj prostych zleceń, takich jak "Get", "Create" i "Change" w postaci streszczenia.Use simple verbs like "get", "create", and "change" in the synopsis. Należy unikać używania "Set", ponieważ jest to niejasne i ozdobnych słów, takich jak "Modify".Avoid using "set" because it is vague, and fancy words such as "modify."

    Przykład: "pobiera informacje o podpisie Authenticode w pliku".Example: "Gets information about the Authenticode signature in a file."

  • Napisz w aktywnym głosie.Write in active voice. Na przykład "Użyj obiektu TimeSpan..." jest znacznie wyraźniejsze niż "obiekt TimeSpan może być używany do..."For example, "Use the TimeSpan object..." is much clearer than "the TimeSpan object can be used to..."

  • Należy unikać czasownika "Display" podczas opisywania poleceń cmdlet, które pobierają obiekty.Avoid the verb "display" when describing cmdlets that get objects. Mimo że program Windows PowerShell wyświetla dane poleceń cmdlet, ważne jest, aby wprowadzić użytkowników do koncepcji, która zwraca .NET Framework obiektów, których dane mogą nie być wyświetlane.Although Windows PowerShell displays cmdlet data, it is important to introduce users to the concept that the cmdlet returns .NET Framework objects whose data may not be displayed. W przypadku wyróżniania ekranu użytkownik może nie pamiętać, że polecenie cmdlet mogło zwrócić wiele innych przydatnych właściwości i metod, które nie są wyświetlane.If you emphasize the display, the user might not realize that the cmdlet may have returned many other useful properties and methods that are not displayed.

Zobacz teżSee Also

Windows PowerShell SDKWindows PowerShell SDK