Compatibilidad con la Ayuda en línea

  • Artículo
  • Tiempo de lectura: 4 minutos

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

Acerca de la Ayuda en línea

La ayuda en línea siempre ha sido una parte fundamental de PowerShell. Aunque el cmdlet muestra temas de ayuda en el símbolo del sistema, muchos usuarios prefieren la experiencia de lectura en línea, incluida la codificación de colores, hipervínculos y el uso compartido de ideas en contenido de Community y documentos basados en Get-Help wikis. Lo más importante es que antes de la llegada de la Ayuda actualizable, la ayuda en línea proporcionaba la versión más actualizada 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 fundamental. 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.

Funcionamiento Get-Help -Online

Para ayudar a los usuarios a encontrar los temas de ayuda en línea de los comandos, el comando 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 Get-Help del usuario.

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

Get-Help Invoke-Command -Online

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

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

  • Propiedad HelpUri de cualquier comando. La propiedad HelpUri 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-Helpbusca 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 si escribe otro valor 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 cualquier comando agregando un URI válido a la primera entrada de la sección Vínculos relacionados del tema de ayuda basado Get-Help -Online en XML para el comando. 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. 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 maml:uri elemento bajo el primer elemento del elemento maml:relatedLinks/maml:navigationLink maml:relatedLinks .

En el xml siguiente se muestra la ubicación correcta del URI. El Online version: texto del elemento es un procedimiento maml:linkText 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>

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

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

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

Agregar una propiedad HelpUri a una función avanzada

Para las 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 New-Calendar función.

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

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

En el código siguiente se muestra el atributo HelpUri del Start-Debug comando CIM.

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

Agregar un atributo HelpUri a un flujo de trabajo

Para los flujos de trabajo escritos en el lenguaje de PowerShell, agregue . Directiva de comentario ExternalHelp para el código de flujo de trabajo. El valor de la directiva 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.

En el código siguiente se muestra . Directiva ExternalHelp en un archivo de flujo de trabajo.

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