Asignación de un nombre a los archivos de ayudaNaming Help Files

En este tema se explica cómo asignar un nombre a un archivo de ayuda basado en XML para que el cmdlet Get-Help pueda encontrarlo.This topic explains how to name an XML-based help file so that the Get-Help cmdlet can find it. Los requisitos de nombre difieren para cada tipo de comando.The name requirements differ for each command type.

Archivos de ayuda de cmdletCmdlet Help Files

El archivo de ayuda de un cmdlet de C# se debe denominar para el ensamblado en el que se define el cmdlet.The help file for a C# cmdlet must be named for the assembly in which the cmdlet is defined. Use el siguiente formato de nombre de archivo:Use the following filename format:

<AssemblyName>.dll-help.xml

El formato del nombre del ensamblado es necesario incluso cuando el ensamblado es un módulo anidado.The assembly name format is required even when the assembly is a nested module.

Por ejemplo, el cmdlet Get-WinEvent se define en el ensamblado Microsoft.PowerShell.Diagnostics.dll.For example, the Get-WinEvent cmdlet is defined in the Microsoft.PowerShell.Diagnostics.dll assembly. El Get-Help cmdlet busca un tema de ayuda para el Get-WinEvent cmdlet solo en el Microsoft.PowerShell.Diagnostics.dll-help.xml archivo en el directorio del módulo.The Get-Help cmdlet looks for a help topic for the Get-WinEvent cmdlet only in the Microsoft.PowerShell.Diagnostics.dll-help.xml file in the module directory.

Archivos de ayuda del proveedorProvider Help files

El archivo de ayuda de un proveedor de PowerShell se debe denominar para el ensamblado en el que se define el proveedor.The help file for a PowerShell provider must be named for the assembly in which the provider is defined. Use el siguiente formato de nombre de archivo:Use the following filename format:

<AssemblyName>.dll-help.xml

El formato del nombre del ensamblado es necesario incluso cuando el ensamblado es un módulo anidado.The assembly name format is required even when the assembly is a nested module.

Por ejemplo, el proveedor de certificados se define en el Microsoft.PowerShell.Security.dll ensamblado.For example, the Certificate provider is defined in the Microsoft.PowerShell.Security.dll assembly. El Get-Help cmdlet busca un tema de ayuda para el proveedor de certificados solo en el Microsoft.PowerShell.Security.dll-help.xml archivo en el directorio del módulo.The Get-Help cmdlet looks for a help topic for the Certificate provider only in the Microsoft.PowerShell.Security.dll-help.xml file in the module directory.

Archivos de ayuda de funciónFunction Help Files

Las funciones se pueden documentar mediante la ayuda basada en comentarios o documentada en un archivo de ayuda XML.Functions can be documented by using comment-based help or documented in an XML help file. Cuando la función está documentada en un archivo XML, la función debe tener una .ExternalHelp palabra clave comment que asocie la función con el archivo XML.When the function is documented in an XML file, the function must have an .ExternalHelp comment keyword that associates the function with the XML file. De lo contrario, el Get-Help cmdlet no puede encontrar el archivo de ayuda.Otherwise, the Get-Help cmdlet cannot find the help file.

No hay ningún requisito técnico para el nombre de un archivo de ayuda de función.There are no technical requirements for the name of a function help file. Sin embargo, se recomienda asignar un nombre al archivo de ayuda para el módulo de script en el que se define la función.However, a best practice is to name the help file for the script module in which the function is defined. Por ejemplo, la función siguiente se define en el MyModule.psm1 archivo.For example, the following function is defined in the MyModule.psm1 file.

#.ExternalHelp MyModule.psm1-help.xml
function Test-Function { ... }

Archivos de ayuda de comandos CIMCIM Command Help Files

El archivo de ayuda de un comando CIM debe tener el nombre del archivo CDXML en el que se define el comando CIM.The help file for a CIM command must be named for the CDXML file in which the CIM command is defined. Use el siguiente formato de nombre de archivo:Use the following filename format:

<FileName>.cdxml-help.xml

Los comandos CIM se definen en los archivos CDXML que se pueden incluir en los módulos como módulos anidados.CIM commands are defined in CDXML files that can be included in modules as nested modules. Cuando el comando CIM se importa en la sesión como una función, PowerShell agrega una .ExternalHelp palabra clave comment a la definición de función que asocia la función a un archivo de ayuda XML denominado para el archivo CDXML en el que se define el comando CIM.When the CIM command is imported into the session as a function, PowerShell adds an .ExternalHelp comment keyword to the function definition that associates the function with an XML help file that is named for the CDXML file in which the CIM command is defined.

Archivos de ayuda del flujo de trabajo de scriptScript Workflow Help Files

Los flujos de trabajo de script que se incluyen en los módulos se pueden documentar en archivos de ayuda basados en XML.Script workflows that are included in modules can be documented in XML-based help files. No hay ningún requisito técnico para el nombre del archivo de ayuda.There are no technical requirements for the name of the help file. Sin embargo, se recomienda asignar un nombre al archivo de ayuda para el módulo de script en el que se define el flujo de trabajo de script.However, a best practice is to name the help file for the script module in which the script workflow is defined. Por ejemplo:For example:

<ScriptModule>.psm1-help.xml

A diferencia de otros comandos scripts, los flujos de trabajo de scripts no requieren una .ExternalHelp palabra clave comment para asociarlos con un archivo de ayuda.Unlike other scripted commands, script workflows do not require an .ExternalHelp comment keyword to associate them with a help file. En su lugar, PowerShell busca en los subdirectorios específicos de la referencia cultural de la interfaz de usuario del directorio de módulos para los archivos de ayuda basados en XML y busca ayuda para el flujo de trabajo de script en todos los archivos.Instead, PowerShell searches the UI-Culture-specific subdirectories of the module directory for XML-based help files and looks for help for the script workflow in all the files. .ExternalHelpse omite la palabra clave comment..ExternalHelp comment keyword are ignored.

Dado que .ExternalHelp se omite la palabra clave comment, el Get-Help cmdlet puede buscar ayuda para flujos de trabajo de script solo cuando se incluyen en los módulos.Because the .ExternalHelp comment keyword is ignored, the Get-Help cmdlet can find help for script workflows only when they are included in modules.