Recomendaciones y reglas de PSScriptAnalyzer

Las siguientes instrucciones proceden de un esfuerzo combinado del equipo de PowerShell y de la comunidad. Las directrices se organizan por tipo. Dentro de cada tipo, hay una lista de reglas. Las reglas se agrupan mediante la Gravedad definida en la implementación de la regla de PSScriptAnalyzer. El nivel de gravedad etiquetado TBD significa "Por determinar." Los elementos etiquetados como por definir son recomendaciones que actualmente no tienen reglas definidas.

Reglas de diseño de cmdlets

Gravedad: Error

No hay reglas definidas.

Gravedad: Advertencia

• Usar solo verbos aprobados useApprovedVerbs
• Nombres de cmdlets con caracteres no utilizables AvoidReservedCharInCmdlet
• Nombres de parámetro que no se pueden usar AvoidReservedParams
• Solicitudes de confirmación de soporte técnico useShouldProcessForStateChangingFunctions y UseSupportsShouldProcess
• Debe llamar a ShouldProcess cuando el atributo ShouldProcess esté presente y viceversa UseShouldProcess
• Los nombres deben ser singulares UseSingularNouns
• Faltan campos de manifiesto de módulo missingModuleManifestField
  • Versión
  • Author
  • Descripción
  • licenseUri (para la Galería de PowerShell)
• Los parámetros del modificador no deben tener como valor predeterminado true AvoidDefaultValueSwitchParameter

Gravedad: información

No hay reglas definidas.

Gravedad: TBD

• Compatibilidad con parámetro Force para sesiones interactivas. Si el cmdlet se usa de forma interactiva, proporcione siempre un parámetro Force para invalidar las acciones interactivas, como mensajes o líneas de entrada. El parámetro Force es importante porque permite que tu cmdlet se use en scripts y hosts no interactivos.
• Objetos de salida del documento
• El módulo debe ser cargable
• No hay errores de sintaxis
• Las dependencias sin resolver son un error
• Derivar de las clases cmdlet o PSCmdlet
• Especificar el atributo de cmdlet
• Invalidar un método de procesamiento de entrada
• Especificar el atributo OutputType
• Escritura de registros únicos en la canalización
• Hacer que los cmdlets no distinguen mayúsculas de minúsculas y conservan mayúsculas y minúsculas

Funciones de script

Gravedad: Error

No hay reglas definidas.

Gravedad: Advertencia

• Evite usar alias AvoidUsingCmdletAliases
• Evite usar cmdlets WMI en desuso AvoidUsingWMICmdlet
• Evite usar bloques de de vacíos AvoidUsingEmptyCatchBlock
• Invocación de cmdlets existentes con parámetros correctos UseCmdlet Incorrectamente
• Los cmdlets deben tener ShouldProcess/ShouldContinue y parámetro Force si se usan determinados verbos modificados por el sistema (Update, Set, Remove, New): UseShouldProcessForStateChangingFunctions
• Evite usar parámetros posicionales AvoidUsingPositionalParameters
• Evite usar variables globales AvoidGlobalVars
• Las variables declaradas deben usarse después de su asignación useDeclaredVarsMoreThanAssignments
• Evite usar Invoke-ExpressionAvoidUsingInvokeExpression

Gravedad: información

No hay reglas definidas.

Gravedad: TBD

• Evitar el uso de Clear-Host
• Evitar el uso de rutas de acceso de archivos UNC
• Control de errores
  • Uso de -ErrorAction Stop al llamar a cmdlets
  • Usar $ErrorActionPreference set to Stop o Continue al llamar a noncmdlets
  • Evitar el uso de marcas para controlar errores
  • Evitar el uso de $?
  • Evitar pruebas de una variable nula como condición de error
  • Copiar $Error[0] a su propia variable
• Evitar el uso de canalizaciones en scripts
• Si se declara un tipo de valor devuelto, el cmdlet debe devolver ese tipo. Si se devuelve un tipo, se debe declarar un tipo de valor devuelto.

Estilo de scripting

Gravedad: Error

No hay reglas definidas.

Gravedad: Advertencia

• Evite usar Write-Host a menos que escribir en el host sea todo lo que desea hacer AvoidUsingWriteHost

Gravedad: información

• Escribir ayuda basada en comentarios ProvideCommentHelp

Gravedad: TBD

• Proporcionar ejemplos de uso
• Use la sección Notas para obtener más información sobre cómo funciona la herramienta.
• Todos los comandos exportados deben tener ayuda (incluida la documentación de parámetros)
• Documentar la versión de PowerShell para la que se escribió el script
• Sangría del código
• Evitar acentos versos

Seguridad de scripts

Gravedad: Error

• Evite usar contraseñas de texto sin formato AvoidUsingPlainTextForPassword
• Evite -Username y parámetros de -Password (use psCredential en su lugar): UsePSCredentialType
• Evite codificar de forma dura un argumento de parámetro de -ComputerName (divulgación de información): AvoidUsingComputerNameHardcoded
• Evite usar ConvertTo-SecureString con texto no cifrado (divulgación de información): AvoidUsingConvertToSecureStringWithPlainText

Gravedad: Advertencia

• Evite usar $Password = 'string' (divulgación de información). avoidUsingUsernameAndPasswordParams

Gravedad: información

No hay reglas definidas.

Gravedad: TBD

• Evita inicializar la clave de API y las variables de credenciales (divulgación de información)

Reglas relacionadas con DSC

Gravedad: Error

• Usar métodos estándar de DSC StandardDSCFunctionsInResource
• Use parámetros obligatorios idénticos para todos los métodos DSC UseIdenticalMandatoryParametersForDSC
• Use parámetros idénticos para los métodos Set y Test DSC UseIdenticalParametersForDSC

Gravedad: Advertencia

No hay reglas definidas.

Gravedad: información

• Las tres recomendaciones siguientes se tratan en la regla ReturnCorrectTypesForDSCFunctions
  • Evite devolver cualquier objeto de una función Set-TargetResource o Set (basada en clases)
  • Devuelve un valor booleano de una función Test-TargetResource o Test (basada en clases)
  • Devolver un objeto de una función Get-TargetResource o Get (basada en clases)
• Los recursos de DSC deben tener pruebas de DSC DSCTestsPresent
• Los recursos de DSC deben tener ejemplos de DSC DSCExamplesPresent

Gravedad: TBD

• Para Windows PowerShell v4, los módulos de recursos deberían tener un .psd1 archivo y schema.mof para cada recurso
• Los módulos de recursos deben tener un archivo de .psd1 (siempre) y schema.mof (para recursos que no son de clase), consulte problema n.º 116
• El módulo de recursos debería tener una carpeta DscResources que contenga los recursos - véase el número #130
• Los MOF deben tener una descripción para cada elemento: vea problema n.º 131
• Usar ShouldProcess para un método Set DSC

Referencias

• directrices de desarrollo de cmdlets
• lista de comprobación de pruebas y diseño de recursos de DSC de PowerShell
• Las directrices de DSC también se pueden encontrar en el repositorio de recursos de DSC.
  • Directrices de estilo de recursos de DSC de & procedimientos recomendados
  • de nomenclatura de recursos de DSC
  • crear un módulo de recursos de DSC de alta calidad
• la guía de estilos y procedimientos recomendados de PowerShell no oficiales