Referencia del esquema del manifiesto de recurso de DSC basado en comandos
Sinopsis
El archivo de datos que define un recurso de DSC basado en comandos.
Metadatos
SchemaDialect: https://json-schema.org/draft/2020-12/schema
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
Type: object
Descripción
Cada recurso de DSC basado en comandos debe tener un manifiesto. El archivo de manifiesto debe:
- Sea reconocible en la variable de
PATHentorno. - Debe tener el formato JSON o YAML.
- Siga la convención de
<name>.dsc.resource.<extension>nomenclatura . Las extensiones válidas incluyenjson,ymlyyaml. - Sea válido para el esquema descrito en este documento.
En el resto de este documento se describe el esquema del manifiesto.
Propiedades obligatorias
El manifiesto debe incluir estas propiedades:
Propiedades
$schema
La $schema propiedad indica el URI canónico de este esquema con el que se valida el manifiesto. Esta propiedad es obligatoria. DSC usa este valor para validar el manifiesto con el esquema JSON correcto.
Para cada versión del esquema, hay tres direcciones URL válidas:
.../resource/manifest.jsonDirección URL del esquema no agrupado canónico. Cuando se usa para la validación, el cliente de validación debe recuperar este esquema y cada esquema al que hace referencia.
.../bundled/resource/manifest.jsonDirección URL del esquema agrupado. Cuando se usa para la validación, el cliente de validación solo debe recuperar este esquema.
Este esquema usa el modelo de agrupación introducido para el esquema JSON 2020-12. Aunque DSC todavía puede validar el documento cuando usa este esquema, otras herramientas pueden producir errores o comportarse de maneras inesperadas.
.../bundled/resource/manifest.vscode.jsonDirección URL del esquema de creación mejorado. Este esquema es mucho mayor que los otros esquemas, ya que incluye definiciones adicionales que proporcionan ayuda contextual y fragmentos de código que los demás no incluyen.
Este esquema usa palabras clave que solo reconoce VS Code. Aunque DSC todavía puede validar el documento cuando usa este esquema, otras herramientas pueden producir errores o comportarse de maneras inesperadas.
Type: string
Required: true
Format: URI
ValidValues: [
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json
]
tipo
La type propiedad representa el nombre de tipo completo del recurso. Se usa para especificar el recurso en los documentos de configuración y como valor de la --resource marca cuando se usan los dsc resource * comandos . Para obtener más información sobre los nombres de tipo de recurso, consulte Referencia del esquema de nombre de tipo completo del recurso de DSC.
Type: string
Required: true
Pattern: ^\w+(\.\w+){0,2}\/\w+$
version
La version propiedad debe ser la versión actual del recurso como una cadena de versión semántica (semver) válida. La versión se aplica al recurso, no al software que administra.
Type: string
Required: true
Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
description
La description propiedad define una sinopsis para el propósito del recurso. El valor de esta propiedad debe ser una cadena corta.
Type: string
Required: false
kind
La kind propiedad define cómo debe controlar DSC el recurso. DSC admite tres tipos de recursos de DSC basados en comandos: Resource, Groupy Adapter.
Cuando kind no se define en el manifiesto de recursos, DSC deduce el valor de la propiedad . Si la adapter propiedad se define en el manifiesto de recursos, DSC deduce el valor de kind como Adapter. Si la adapter propiedad no está definida, DSC deduce el valor de kind como Resource.
DSC no puede deducir si un manifiesto es para un recurso de grupo.
Al definir un recurso de grupo, siempre defina explícitamente la kind propiedad en el manifiesto como Group.
Para obtener más información, vea Referencia de esquema de tipo de recurso de DSC.
Type: string
Required: false
ValidValues: [Resource, Adapter, Group]
etiquetas
La tags propiedad define una lista de términos que se pueden buscar para el recurso. El valor de esta propiedad debe ser una matriz de cadenas. Cada etiqueta solo debe contener caracteres alfanuméricos y caracteres de subrayado. No se permiten otros caracteres. Cada etiqueta debe ser única.
Type: array
Required: false
ItemsMustBeUnique: true
ItemsType: string
ItemsPattern: ^\w+$
exportar
La export propiedad define cómo llamar al recurso para obtener el estado actual de cada instancia.
Cuando se define esta propiedad, los usuarios pueden:
- Especifique una instancia del recurso en la configuración de entrada del comando dsc config export para generar un documento de configuración utilizable.
- Especifique el recurso con el comando dsc resource export para generar un documento de configuración que defina cada instancia del recurso.
- Especifique el recurso con el comando dsc resource get y la opción --all para devolver el estado actual para cada instancia del recurso.
El valor de esta propiedad debe ser un objeto . La propiedad del executable objeto, que define el nombre del comando que se va a llamar, es obligatoria. La propiedad args es opcional. Para obtener más información, vea Referencia del esquema de propiedades de exportación del manifiesto de recursos de DSC.
Type: object
Required: true
get
La get propiedad define cómo llamar al recurso para obtener el estado actual de una instancia. Esta propiedad es obligatoria para todos los recursos.
El valor de esta propiedad debe ser un objeto . La propiedad del executable objeto, que define el nombre del comando que se va a llamar, es obligatoria. Las args propiedades y input son opcionales. Para obtener más información, vea DSC Resource manifest get property schema reference (Referencia del esquema de propiedades de obtención del manifiesto de recursos de DSC).
Type: object
Required: true
set
La set propiedad define cómo llamar al recurso para establecer el estado deseado de una instancia. También define cómo procesar la salida del recurso para este método. Cuando no se define esta propiedad, DSC no puede administrar instancias del recurso. Solo puede obtener su estado actual y probar si la instancia está en el estado deseado.
El valor de esta propiedad debe ser un objeto . La executable propiedad , que define el nombre del comando que se va a llamar, es obligatoria. Las argsinputpropiedades , implementsPretesty returns son opcionales. Para obtener más información, vea Referencia del esquema de propiedades del conjunto de manifiestos de recursos de DSC.
Type: object
Required: false
test
La test propiedad define cómo llamar al recurso para probar si una instancia está en el estado deseado. También define cómo procesar la salida del recurso para este método. Cuando esta propiedad no está definida, DSC realiza una prueba sintética básica para instancias del recurso de DSC.
El valor de esta propiedad debe ser un objeto . La propiedad del executable objeto, que define el nombre del comando que se va a llamar, es obligatoria. Las argsinputpropiedades , y returns son opcionales.
Para obtener más información, vea Referencia del esquema de propiedades de prueba del manifiesto de recursos de DSC.
Type: object
Required: false
validate
La validate propiedad define cómo llamar a un recurso de grupo de DSC para validar sus instancias. Esta propiedad es obligatoria para los recursos del grupo de DSC. DSC omite esta propiedad para todos los demás recursos.
El valor de esta propiedad debe ser un objeto . La propiedad del executable objeto, que define el nombre del comando que se va a llamar, es obligatoria. La propiedad args es opcional. Para obtener más información, consulte Referencia del esquema de propiedades de validación del manifiesto de recursos de DSC.
Type: object
Required: false
provider
Cuando se especifica, la provider propiedad define el recurso como proveedor de recursos de DSC.
El valor de esta propiedad debe ser un objeto . Las propiedades y config del list objeto son obligatorias. La list propiedad define cómo llamar al proveedor para devolver los recursos que el proveedor puede administrar. La config propiedad define cómo espera la entrada el proveedor. Para obtener más información, consulte la referencia del esquema de propiedades del proveedor de manifiestos de recursos de DSC.
exitCodes
La exitCodes propiedad define un conjunto de códigos de salida válidos para el recurso y su significado.
Defina esta propiedad como un conjunto de pares clave-valor donde:
- La clave es una cadena que contiene un entero con signo que se asigna a un código de salida conocido para el recurso.
El código de salida debe ser un entero con signo literal. No puede usar formatos alternativos para el código de salida. Por ejemplo, en lugar del valor
0x80070005hexadecimal de "Acceso denegado", especifique el código de salida como-2147024891. - El valor es una cadena que describe el significado semántico de ese código de salida para un lector humano.
DSC interpreta el código 0 de salida como una operación correcta y cualquier otro código de salida como un error.
Sugerencia
Si va a crear el manifiesto de recursos en yaml, asegúrese de encapsular el código de salida entre comillas simples para asegurarse de que el archivo YAML se puede analizar correctamente. Por ejemplo:
exitCodes:
'0': Success
'1': Invalid parameter
'2': Invalid input
'3': Registry error
'4': JSON serialization failed
Type: object
Required: false
PropertyNamePattern: ^[0-9]+#
PropertyValueType: string
esquema
La schema propiedad define cómo obtener el esquema JSON que valida una instancia del recurso. Esta propiedad siempre debe ser un objeto que defina una de las siguientes propiedades:
command- Cuando se especifica lacommandpropiedad, DSC llama al comando definido para obtener el esquema JSON.embedded- Cuando se especifica laembeddedpropiedad, DSC usa el valor definido como esquema JSON.
Para obtener más información, vea Referencia de la propiedad de esquema del manifiesto de recursos de DSC.
Type: object
Required: true
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de