Windows PowerShell: Ayuda mediante comentarios
Puede agregar sus propios comentarios a sus scripts y crear así su propio sistema de ayuda y tutoría.
Don Jones
Una de las cosas pespunteadas de Windows PowerShell es su sistema de ayuda. La ayuda archivos incluyen descripciones generales de sintaxis, explicaciones detalladas, ejemplos y así sucesivamente.
Dado que un shell de línea de comandos no puede ofrecer características de detectabilidad como los menús contextuales, barras de herramientas, cintas y así sucesivamente, el archivo de ayuda está en función de su propio como un descubrimiento. Se puede utilizar con comodines, por ejemplo, para descubrir nuevos comandos. Entonces puede leer su ayuda para aprender a usarlos.
Como producir sus propios comandos como secuencias de comandos y funciones, haría bien para mantener su trabajo tan pulido como los cmdlets de Windows PowerShell nativos. Usted siempre debe esforzarse para hacer su trabajo lo más consistente posible con el resto de la cáscara. Parte de esa consistencia y polaco está en cómo preparar y proporcionar ayuda.
Podría producir el mismo tipo exacto de los archivos de ayuda basado en XML que utiliza Windows PowerShell, sí. Hay más discusión sobre este tema en mi libro autoeditado, "secuencias de comandos de Windows PowerShell y fabricación de herramientas. Sin embargo, la mayoría de ustedes no necesita la flexibilidad de los archivos de ayuda ofrecen, como la capacidad para proporcionar ayuda en varios idiomas.
Usted puede tomar una ruta mucho más fácil. Simplemente puede utilizar la ayuda basada en el comentario.
Ayuda basada en la observación de reglas
Hay unas reglas de ayuda basado en el comentario que debo cubrir derecha frontal:
- Generalmente, usted desea incluir los bloques de comentario especial en el < bloque # comentarios #> marcadores. También es legal simplemente comentar cada línea iniciando con el carácter de comentario #.
- Ayuda basada en la observación debe ser lo primero en el archivo de comandos. Es preferible incluir la ayuda dentro de la función y no antes. Ayuda a mantener el comentario "parte" de la función y asegura que Windows PowerShell no confunda para otra cosa. También es legal poner ayuda basada en la observación de la secuencia de comandos al final del archivo, pero no me gusta hacerlo, porque algunos de los otros beneficios de la utilización de ayuda basado en el comentario disminuye.
- Si usted está proporcionando ayuda para una función, el bloque de comentario ayuda puede venir inmediatamente antes o inmediatamente después el nombre de la función y la apertura de la llave.
- Cuando usted pone múltiples funciones en un script, por ejemplo, un módulo de script, puede proporcionar ayuda para el archivo poniendo el bloque de comentario en la parte superior. Asegúrese de agregar al menos unas líneas en blanco después de ese bloque de comentario, para que cualquier ayuda de funciones específicas posterior se apart correctamente.
- Si se escribe incorrectamente cualquiera de las palabras clave de ayuda basado en el comentario, Windows PowerShell podría ignorar todo el bloque. Así que tenga cuidado con la ortografía, pues cuenta.
Sintaxis de ayuda basado en el comentario
Ayuda basada en la observación consiste en una o más secciones. Cada sección comienza con una palabra clave puntos, seguida por una o más líneas de texto. Por ejemplo:
<# .SYNOPSIS The synopsis goes here. This can be one line, or many. .DESCRIPTION The description is usually a longer, more detailed explanation of what the script or function does. Take as many lines as you need. .PARAMETER computername Here, the dotted keyword is followed by a single parameter name. Don't precede that with a hyphen. The following lines describe the purpose of the parameter: .PARAMETER filePath Provide a PARAMETER section for each parameter that your script or function accepts. .EXAMPLE There's no need to number your examples. .EXAMPLE PowerShell will number them for you when it displays your help text to a user. #>
Este ejemplo incluye los cuatro palabras con puntos más comúnmente utilizados. Usted notará que estos empiezan con un punto o periodo. Windows PowerShell no entre mayúsculas y minúsculas acerca de aquellos, aunque la documentación enumera en todas mayúsculas (por lo que tiendo a hacer lo mismo). Usando mayúsculas también hace que las secciones destacan un poco más cuando estás leyendo el código en un editor de secuencias de comandos.
Otra sección aseado que puede utilizar es el enlace. Con esto, puede incluir una dirección URL, comenzando con la dirección http://, a una versión en línea de su ayuda. Por ejemplo, publicar su ayuda en un sitio de intranet, permite alguien obtener más detalle, posiblemente más ejemplos, averiguar cómo comunicarse con usted y así sucesivamente.
Windows PowerShell genera automáticamente contenido de la ayuda adicional por mirar su script o función. Deriva el nombre, la sintaxis básica (incluyendo los tipos de datos y nombres de parámetro) y otra información. No detecta cualquier valor predeterminado que puede haber codificado en un parámetro:
Param($computername = 'localhost')
Por lo tanto, debe tomar cuidado para documentar los valores predeterminados en la ayuda para el parámetro de sí mismo, o incluso en la descripción.
Basado en el comentario awesomeness
Otra ventaja de ayuda basado en el comentario es que proporciona dos tipos de ayuda. Uno es para la gente que ayuda contra sus scripts y funciones. El otro es para alguien leyendo las secuencias de comandos.
En otras palabras, ayuda comentario bien escrito también puede doblar como documentación en línea que probablemente prefiere poner en cualquiera de las secuencias de comandos.
.jpg)
Don Jones es un receptor de Microsoft MVP Award y autor de "Aprender Windows PowerShell en un mes de comidas" (publicaciones de Manning, 2011), un libro diseñado para ayudar a cualquier administrador en vigencia con Windows PowerShell. Jones también ofrece formación pública y en el sitio Windows PowerShell. Contactar con él a través de ConcentratedTech.com o bit.ly/AskDon.