Compatibilidad con la Ayuda en líneaSupporting Online Help

A partir de PowerShell 3,0, hay dos maneras de admitir la Get-Help característica en línea para los comandos de PowerShell.Beginning in PowerShell 3.0, there are two ways to support the Get-Help Online feature for PowerShell commands. En este tema se explica cómo implementar esta característica para distintos tipos de comandos.This topic explains how to implement this feature for different command types.

Acerca de la ayuda en líneaAbout Online Help

La ayuda en línea siempre ha sido una parte fundamental de PowerShell.Online help has always been a vital part of PowerShell. Aunque el Get-Help cmdlet muestra temas de ayuda en el símbolo del sistema, muchos usuarios prefieren la experiencia de lectura en línea, como la codificación de colores, los hipervínculos y el uso compartido de ideas en el contenido de la comunidad y en los documentos basados en wiki.Although the Get-Help cmdlet displays help topics at the command prompt, many users prefer the experience of reading online, including color-coding, hyperlinks, and sharing ideas in Community Content and wiki-based documents. Lo más importante, antes de la llegada de la ayuda actualizable, la ayuda en línea proporcionó la versión más actualizada de los archivos de ayuda.Most importantly, before the advent of Updatable Help, online help provided the most up-to-date version of the help files.

Con la llegada de la ayuda actualizable en PowerShell 3,0, la ayuda en línea sigue desempeñando un papel fundamental.With the advent of Updatable Help in PowerShell 3.0, online help still plays a vital role. Además de la experiencia de usuario flexible, la ayuda en línea proporciona ayuda a los usuarios que no pueden usar la ayuda actualizable para descargar temas de ayuda.In addition to the flexible user experience, online help provides help to users who do not or cannot use Updatable Help to download help topics.

Funcionamiento de Get-Help en líneaHow Get-Help -Online Works

Para ayudar a los usuarios a encontrar los temas de ayuda en línea para los comandos, el Get-Help comando tiene un parámetro en línea que abre la versión en línea del tema de ayuda para un comando en el explorador de Internet predeterminado del usuario.To help users find the online help topics for commands, the Get-Help command has an Online parameter that opens the online version of help topic for a command in the user's default internet browser.

Por ejemplo, el siguiente comando abre el tema de ayuda en pantalla para el Invoke-Command cmdlet.For example, the following command opens the online help topic for the Invoke-Command cmdlet.

Get-Help Invoke-Command -Online

Para implementar Get-Help -Online , el Get-Help cmdlet busca un identificador uniforme de recursos (URI) para el tema de ayuda de la versión en línea en las siguientes ubicaciones.To implement Get-Help -Online, the Get-Help cmdlet looks for a Uniform Resource Identifier (URI) for the online version help topic in the following locations.

  • El primer vínculo de la sección vínculos relacionados del tema de ayuda para el comando.The first link in the Related Links section of the help topic for the command. El tema de ayuda debe instalarse en el equipo del usuario.The help topic must be installed on the user's computer. Esta característica se presentó en PowerShell 2,0.This feature was introduced in PowerShell 2.0.

  • La propiedad HelpUri de cualquier comando.The HelpUri property of any command. La propiedad HelpUri es accesible incluso cuando el tema de ayuda para el comando no está instalado en el equipo del usuario.The HelpUri property is accessible even when the help topic for the command is not installed on the user's computer. Esta característica se presentó en PowerShell 3,0.This feature was introduced in PowerShell 3.0.

    Get-Help busca un URI en la primera entrada de la sección Links relacionado antes de obtener el valor de la propiedad HelpUri .Get-Help looks for a URI in the first entry in the Related Links section before getting the HelpUri property value. Si el valor de la propiedad es incorrecto o ha cambiado, puede invalidarlo escribiendo un valor diferente en el primer vínculo relacionado.If the property value is incorrect or has changed, you can override it by entering a different value in the first related link. Sin embargo, el primer vínculo relacionado solo funciona cuando los temas de ayuda se instalan en el equipo del usuario.However, the first related link works only when the help topics are installed on the user's computer.

Puede admitir Get-Help -Online cualquier comando agregando un URI válido a la primera entrada de la sección vínculos relacionados del tema de ayuda basado en XML para el comando.You can support Get-Help -Online for any command by adding a valid URI to the first entry in the Related Links section of the XML-based help topic for the command. Esta opción solo es válida en los temas de ayuda basados en XML y solo funciona cuando el tema de ayuda está instalado en el equipo del usuario.This option is valid only in XML-based help topics and works only when the help topic is installed on the user's computer. Cuando se instala el tema de ayuda y se rellena el URI, este valor tiene prioridad sobre la propiedad HelpUri del comando.When the help topic is installed and the URI is populated, this value takes precedence over the HelpUri property of the command.

Para admitir esta característica, el URI debe aparecer en el maml:uri elemento bajo el primer maml:relatedLinks/maml:navigationLink elemento del maml:relatedLinks elemento.To support this feature, the URI must appear in the maml:uri element under the first maml:relatedLinks/maml:navigationLink element in the maml:relatedLinks element.

El siguiente XML muestra la ubicación correcta del URI.The following XML shows the correct placement of the URI. El Online version: texto del maml:linkText elemento es un procedimiento recomendado, pero no es necesario.The Online version: text in the maml:linkText element is a best practice, but it is not required.

<maml:relatedLinks>
    <maml:navigationLink>
        <maml:linkText>Online version:</maml:linkText>
        <maml:uri>https://go.microsoft.com/fwlink/?LinkID=113279</maml:uri>
    </maml:navigationLink>
    <maml:navigationLink>
        <maml:linkText>about_History</maml:linkText>
        <maml:uri/>
    </maml:navigationLink>
</maml:relatedLinks>

Agregar la propiedad HelpUri a un comandoAdding the HelpUri property to a command

En esta sección se muestra cómo agregar la propiedad HelpUri a los comandos de tipos diferentes.This section shows how to add the HelpUri property to commands of different types.

Agregar una propiedad HelpUri a un cmdletAdding a HelpUri Property to a Cmdlet

Para los cmdlets escritos en C#, agregue un atributo HelpUri a la clase de cmdlet .For cmdlets written in C#, add a HelpUri attribute to the Cmdlet class. El valor del atributo debe ser un URI que comience por http o https .The value of the attribute must be a URI that begins with http or https.

En el código siguiente se muestra el atributo HelpUri de la Get-History clase cmdlet.The following code shows the HelpUri attribute of the Get-History cmdlet class.

[Cmdlet(VerbsCommon.Get, "History", HelpUri = "https://go.microsoft.com/fwlink/?LinkID=001122")]

Agregar una propiedad HelpUri a una función avanzadaAdding a HelpUri Property to an Advanced Function

En el caso de las funciones avanzadas, agregue una propiedad HelpUri al atributo CmdletBinding .For advanced functions, add a HelpUri property to the CmdletBinding attribute. El valor de la propiedad debe ser un URI que comience por "http" o "https".The value of the property must be a URI that begins with "http" or "https".

En el código siguiente se muestra el atributo HelpUri de la New-Calendar función.The following code shows the HelpUri attribute of the New-Calendar function

function New-Calendar {
    [CmdletBinding(SupportsShouldProcess=$true,
    HelpURI="https://go.microsoft.com/fwlink/?LinkID=01122")]

Agregar un atributo HelpUri a un comando CIMAdding a HelpUri Attribute to a CIM Command

En el caso de los comandos CIM, agregue un atributo HelpUri al elemento CmdletMetadata en el archivo CDXML.For CIM commands, add a HelpUri attribute to the CmdletMetadata element in the CDXML file. El valor del atributo debe ser un URI que comience por http o https .The value of the attribute must be a URI that begins with http or https.

En el código siguiente se muestra el atributo HelpUri del Start-Debug comando CIMThe following code shows the HelpUri attribute of the Start-Debug CIM command

<CmdletMetadata Verb="Debug" HelpUri="https://go.microsoft.com/fwlink/?LinkID=001122"/>

Agregar un atributo HelpUri a un flujo de trabajoAdding a HelpUri Attribute to a Workflow

En el caso de los flujos de trabajo que se escriben en el lenguaje de PowerShell, agregue un . ExternalHelp : Directiva de comentario al código del flujo de trabajo.For workflows that are written in the PowerShell language, add an .ExternalHelp comment directive to the workflow code. El valor de la Directiva debe ser un URI que comience por http o https .The value of the directive must be a URI that begins with http or https.

Nota

La propiedad HelpUri no es compatible con los flujos de trabajo basados en XAML en PowerShell.The HelpUri property is not supported for XAML-based workflows in PowerShell.

En el código siguiente se muestra el. Directiva ExternalHelp en un archivo de flujo de trabajo.The following code shows the .ExternalHelp directive in a workflow file.

# .ExternalHelp "https://go.microsoft.com/fwlink/?LinkID=138338"