Compartir a través de

Compatibilidad con la Ayuda en línea

  • Artículo

Nota:

La creación manual de ayuda basada en XML es muy difícil. El módulo PlatyPS le permite escribir ayuda en Markdown y, a continuación, convertirlo a ayuda basada en XML. Esto facilita mucho la escritura y el mantenimiento de la ayuda. platyPS también puede crear los paquetes de ayuda actualizables automáticamente. Para obtener más información, consulte ayuda basada en XML mediante PlatyPS.

A partir de PowerShell 3.0, hay dos maneras de admitir la característica Get-Help Online para comandos de PowerShell. En este tema se explica cómo implementar esta característica para distintos tipos de comandos.

Acerca de la Ayuda en línea

La ayuda en línea siempre ha sido una parte vital de PowerShell. Aunque el cmdlet Get-Help muestra temas de ayuda en el símbolo del sistema, muchos usuarios prefieren la experiencia de leer en línea, como codificación de colores, hipervínculos y compartir ideas en contenido de la comunidad y documentos basados en wiki. Lo más importante es que antes de la llegada de la Ayuda actualizable, la ayuda en línea proporcionó la versión más up-to-date de los archivos de ayuda.

Con la llegada de la Ayuda actualizable en PowerShell 3.0, la ayuda en línea sigue desempeñando un papel vital. Además de la experiencia de usuario flexible, la ayuda en línea proporciona ayuda a los usuarios que no usan o no pueden usar la Ayuda actualizable para descargar temas de ayuda.

Cómo funciona Get-Help -Online

Para ayudar a los usuarios a encontrar los temas de ayuda en línea de los comandos, el comando Get-Help tiene un parámetro Online que abre la versión en línea del tema de ayuda para un comando en el explorador de Internet predeterminado del usuario.

Por ejemplo, el siguiente comando abre el tema de ayuda en línea del cmdlet Invoke-Command.

Get-Help Invoke-Command -Online

Para implementar Get-Help -Online, el cmdlet Get-Help busca un identificador uniforme de recursos (URI) para el tema de ayuda de la versión en línea en las siguientes ubicaciones.

  • El primer vínculo de la sección Vínculos relacionados del tema de ayuda para el comando. El tema de ayuda debe instalarse en el equipo del usuario. Esta característica se introdujo en PowerShell 2.0.

  • La propiedad HelpUri de cualquier comando. La propiedad helpUri de es accesible incluso cuando el tema de ayuda del comando no está instalado en el equipo del usuario. Esta característica se introdujo en PowerShell 3.0.

    Get-Help busca un URI en la primera entrada de la sección Vínculos relacionados antes de obtener el valor de la propiedad HelpUri . Si el valor de la propiedad es incorrecto o ha cambiado, puede invalidarlo escribiendo un valor diferente en el primer vínculo relacionado. Sin embargo, el primer vínculo relacionado solo funciona cuando los temas de ayuda están instalados en el equipo del usuario.

Puede admitir Get-Help -Online para 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. Esta opción solo es válida en temas de ayuda basados en XML y solo funciona cuando el tema de ayuda está instalado en el equipo del usuario. Cuando se instala el tema de ayuda y se rellena el URI, este valor tiene prioridad sobre la propiedad HelpUri del comando.

Para admitir esta característica, el URI debe aparecer en el elemento maml:uri en el primer elemento maml:relatedLinks/maml:navigationLink del elemento maml:relatedLinks.

El siguiente XML muestra la ubicación correcta del URI. El Online version: texto del elemento maml:linkText es un procedimiento recomendado, pero no es necesario.

<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>

Adición de la propiedad HelpUri a un comando

En esta sección se muestra cómo agregar la propiedad HelpUri a comandos de distintos tipos.

Agregar una propiedad HelpUri a un cmdlet

Para los cmdlets escritos en C#, agregue un atributo HelpUri a la clase Cmdlet. El valor del atributo debe ser un URI que comience por http o https.

En el código siguiente se muestra el atributo HelpUri de la clase de cmdlet Get-History.

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

Adición de una propiedad HelpUri a una función avanzada

Para funciones avanzadas, agregue una propiedad HelpUri al atributo CmdletBinding. El valor de la propiedad debe ser un URI que comience por "http" o "https".

En el código siguiente se muestra el atributo helpUri de la función New-Calendar

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

Adición de un atributo HelpUri a un comando cim

Para los comandos CIM, agregue un atributo HelpUri al elemento CmdletMetadata en el archivo CDXML. El valor del atributo debe ser un URI que comience por http o https.

El código siguiente muestra el atributo HelpUri del comando CIM de Start-Debug

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

Adición de un atributo HelpUri a un flujo de trabajo

En el caso de los flujos de trabajo escritos en el lenguaje de PowerShell, agregue una palabra clave de comentario .EXTERNALHELP al código de flujo de trabajo. El valor de la palabra clave debe ser un URI que comience por http o https.

Nota:

La propiedad HelpUri no se admite para flujos de trabajo basados en XAML en PowerShell.

El código siguiente muestra la palabra clave .EXTERNALHELP en un archivo de flujo de trabajo.

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