Anatomía de un recurso de DSC basado en comandos

  • Artículo

Los recursos de DSC proporcionan una interfaz estandarizada para administrar la configuración de un sistema. Un recurso define las propiedades que puede administrar e implementar el código necesario para obtener una instancia del recurso.

Los recursos de DSC basados en comandos se definen con al menos dos archivos:

  1. Un manifiesto de recurso de DSC que indica a DSC cómo interactuar con el recurso.
  2. Uno o varios archivos ejecutables y sus dependencias para administrar instancias del recurso.

Manifiestos de recursos de DSC

Los manifiestos de recursos de DSC se definen como archivos JSON. Para que DSC reconozca un archivo JSON como manifiesto, el archivo debe cumplir los criterios siguientes:

  1. El archivo debe ser reconocible en la PATH variable de entorno.
  2. El nombre de archivo debe terminar con .dsc.resource.json.

Cuando DSC busca en el sistema local recursos de DSC disponibles basados en comandos, busca en cada carpeta de los PATH archivos que usan la convención de nomenclatura del manifiesto de recursos de DSC. A continuación, DSC analiza cada uno de esos archivos detectados y los valida con el esquema JSON del manifiesto de recursos de DSC.

Si el archivo JSON se valida con el esquema, DSC puede usar el recurso de DSC.

Como mínimo, el manifiesto debe definir:

  • La versión del esquema JSON del manifiesto de recursos de DSC con la que es compatible.
  • Nombre completo del recurso, como Microsoft.Windows/Registry. La sintaxis de nombre completa es <owner>[.<group>][.<area>]/<name>. Los componentes de grupo y área del nombre completo permiten organizar los recursos en espacios de nombres.
  • Cómo DSC puede llamar al comando para obtener el estado actual de una instancia de recurso.
  • Una manera de validar una instancia. Este puede ser uno de los siguientes:
    • Un esquema JSON que describe una instancia
    • Un comando DSC debe llamar a para obtener el esquema en tiempo de ejecución.
    • Comando para validar los recursos de DSC anidados. Esta última opción solo se aplica a los recursos del grupo de DSC y a los recursos del proveedor de DSC.

El manifiesto puede definir opcionalmente:

  • Cómo DSC puede llamar al comando para probar si una instancia está en el estado deseado.
  • Cómo DSC puede llamar al comando para establecer una instancia en el estado deseado.
  • Significado de los códigos de salida distintos de cero devueltos por el comando .
  • Cómo DSC puede llamar al comando para administrar otros recursos de DSC, cuando el recurso es un recurso de grupo de DSC o un recurso de proveedor de DSC.
  • Metadatos sobre el recurso, como su autor y una breve descripción.

Si el manifiesto no define cómo probar una instancia del recurso, DSC realiza una prueba sintética para las instancias de recursos. La prueba sintética de DSC siempre obtiene el estado real de una instancia y realiza una comparación estricta con distinción entre mayúsculas y minúsculas de las propiedades de la instancia con el estado deseado. La prueba sintética omite las propiedades con el prefijo de subrayado (_) o signo de dólar ($). Si alguna de las propiedades no es exactamente la misma que el estado deseado definido, DSC notifica la instancia como no compatible.

Si el manifiesto no define cómo establecer una instancia del recurso de DSC, DSC no puede usar el recurso para aplicar el estado deseado.

El manifiesto no necesita especificar el mismo archivo ejecutable para cada operación. La definición de cada operación es independiente.

Ejecutables de recursos de DSC

Los recursos de DSC basados en comandos siempre requieren un archivo ejecutable para que DSC se ejecute. No es necesario agrupar el manifiesto de recursos de DSC con el ejecutable. El archivo ejecutable puede ser cualquier archivo ejecutable, como una aplicación binaria o un script de shell. Un recurso puede usar archivos ejecutables diferentes para diferentes operaciones.

Para que DSC use un archivo ejecutable, debe ser reconocible en la PATH variable de entorno. DSC llama al ejecutable una vez por operación, utilizando el código de salida devuelto por el ejecutable para determinar si el comando se realizó correctamente. DSC trata el código 0 de salida como correcto y todos los demás códigos de salida como un error.

Entradas

DSC envía la entrada a los recursos de DSC basados en comandos como un blob de datos JSON a través de stdin o como un conjunto de marcas y valores de argumento. El control de entrada se define por operación en el manifiesto de recursos de DSC.

Cuando DSC envía la entrada como JSON a través de stdin, el blob de datos es la representación JSON del estado deseado de una instancia. Esta es la opción más sólida para un recurso, ya que permite que el recurso admita propiedades complejas con objetos anidados.

Cuando DSC envía la entrada como argumentos, genera un par de argumentos para cada una de las propiedades especificadas. El primer argumento es el nombre de la propiedad con --el prefijo , como --duration. El segundo argumento es el valor de la propiedad. No se garantiza el orden de los pares de argumentos. Este método de entrada no admite propiedades complejas.

Salidas

El archivo ejecutable de un recurso de DSC basado en comandos debe devolver datos JSON a stdout cuando DSC lo llama. La codificación de salida debe ser UTF-8. Cuando el recurso devuelve el estado de una instancia, DSC valida los datos JSON con el esquema de instancia del recurso.

Para los recursos del proveedor de DSC, DSC espera que el ejecutable pase a través de los estados de instancia de los recursos que administra como una sola matriz JSON o como una serie de líneas JSON.

Los recursos de DSC basados en comandos pueden notificar información de registro a DSC emitiendo líneas JSON a stderr. Cada entrada de registro debe ser un objeto JSON que incluya dos claves:

  1. La message clave define la cadena legible para la entrada de registro.
  2. La level clave define si el mensaje representa un Error, o WarningInformation.

DSC recopila mensajes de recursos y los muestra en los resultados de una operación de configuración. Cuando DSC invoca un recurso directamente fuera de una configuración, no recopila los mensajes. En su lugar, solo se emiten a stderr.

Contenido relacionado