From c579c844268ada5214bd2ca86e88a672980d514d Mon Sep 17 00:00:00 2001 From: Mikey Lombardi Date: Tue, 30 Sep 2025 12:27:33 -0500 Subject: [PATCH] (DOCS) Add synthetic export to conceptual docs Prior to this change, the conceptual documentation didn't reference the synthetic export functionality. This change only updates the conceptual documentation. It doesn't modify the reference documentation or schema source. Those changes will need to be separately addressed. --- docs/concepts/resources/capabilities.md | 64 ++++++++++++++++++------- docs/concepts/resources/operations.md | 32 +++++++------ docs/concepts/resources/overview.md | 19 +++++--- 3 files changed, 76 insertions(+), 39 deletions(-) diff --git a/docs/concepts/resources/capabilities.md b/docs/concepts/resources/capabilities.md index cb4b4b761..0a952508c 100644 --- a/docs/concepts/resources/capabilities.md +++ b/docs/concepts/resources/capabilities.md @@ -76,7 +76,7 @@ resource. DSC performs the synthetic test by: 1. Invoking the **Get** operation on the resource to retrieve the actual state of the instance. 1. Synthetically testing each property for the desired state of an instance against the actual state returned. The synthetic test: - + - Uses strict, case-sensitive equivalence for strings. - Uses simple equivalence for numerical, boolean, and null values. - For arrays, item order doesn't matter. Arrays are considered equivalent if both the desired @@ -134,32 +134,59 @@ manifest. A resource with the `export` capability supports enumerating every instance of the resource with the **Export** operation. -You can use resources with this capability with the following commands: +You can use resources with the `export` capability with the following commands: -- [dsc config export][15] to return a configuration document - representing the actual state for every instance of each resource defined in the input document. -- [dsc resource export][16] to return a configuration document - representing the actual state for every instance of the input resource. -- `dsc resource get` with the [--all][17] option to return - the actual state of every instance of the input resource. +- [dsc config export][15] to return a configuration document representing the actual state for + every instance of each resource defined in the input document. +- [dsc resource export][16] to return a configuration document representing the actual state for + every instance of the input resource. +- `dsc resource get` with the [--all][17] option to return the actual state of every instance of + the input resource. A command resource has this capability when it defines the [export][18] property in its resource manifest. +### Synthetic export + +When a resource doesn't have the `export` capability, DSC uses a synthetic export for instances of +the resource. DSC performs the synthetic export by: + +1. Invoking the **Get** operation on the resource to retrieve the actual state of the instance. + + Unlike non-synthetic export operations, users _must_ provide a filter for the resource if the + resource instance JSON schema defines any [required properties][19]. +1. Exporting an instance of the resource with: + + - The `properties` field populated by the actual state returned by the **Get** operation. + - The `name` field populated by a string with the format `-0`. The + `` is the last segment of the resource type name, like `Registry` for + `Microsoft.Windows/Registry`. + +Synthetic export only ever returns a single instance and always requires a filtering instance. You +can use resources that rely on synthetic exporting with the following commands: + +- [dsc config export][15] to return a configuration document representing the actual state for + every instance of each resource defined in the input document. For resources that rely on + synthetic export, you _must_ define a filtering instance in the input document. The resource + can only export a single instance per filtering instance. +- [dsc resource export][16] to return a configuration document representing the actual state for + the required filtering instance. If you invoke this command without providing a filtering + instance, the operation fails. + ## resolve A resource with the `resolve` capability supports resolving nested resource instances from an -external source. This capability is primarily used by [importer resources][19] to enable users to +external source. This capability is primarily used by [importer resources][20] to enable users to compose configuration documents. -A command resource has this capability when it defines the [resolve][20] property in its resource +A command resource has this capability when it defines the [resolve][21] property in its resource manifest. ## See also -- [DSC resource operations][21] -- [DSC resource kinds][22] -- [DSC resource properties][23] +- [DSC resource operations][22] +- [DSC resource kinds][23] +- [DSC resource properties][24] [01]: operations.md#get-operation @@ -180,8 +207,9 @@ manifest. [16]: ../../reference/cli/resource/export.md [17]: ../../reference/cli/resource/get.md#--all [18]: ../../reference/schemas/resource/manifest/export.md -[19]: ../resources/kinds.md#importer-resources -[20]: ../../reference/schemas/resource/manifest/resolve.md -[21]: operations.md -[22]: kinds.md -[23]: ../../concepts/resources/properties.md +[19]: ./properties.md#required-resource-properties +[20]: ../resources/kinds.md#importer-resources +[21]: ../../reference/schemas/resource/manifest/resolve.md +[22]: operations.md +[23]: kinds.md +[24]: ../../concepts/resources/properties.md diff --git a/docs/concepts/resources/operations.md b/docs/concepts/resources/operations.md index 22d9c4284..8af17ca20 100644 --- a/docs/concepts/resources/operations.md +++ b/docs/concepts/resources/operations.md @@ -67,7 +67,8 @@ DSC invokes the **Delete** operation when you use the following commands: The **Export** operation retrieves the actual state for every instance of the resource on a system. The result is a configuration document that includes the exported instances. -This operation is only available for resources with the [export capability][05]. +If a resource doesn't have the [`export` capability][05], DSC synthetically exports the resource. +For more information, see [Synthetic export][06]. DSC invokes the **Export** operation when you use the following commands: @@ -83,7 +84,7 @@ DSC invokes the **Export** operation when you use the following commands: The **List** operation retrieves the available adapted resources for a specific DSC adapter resource. -This operation is only available for [adapter resources][06]. +This operation is only available for [adapter resources][07]. ## Validate operation @@ -101,15 +102,15 @@ invoke an adapted resource. The **Resolve** operation processes an importer resource instance to return a configuration document. -This operation is only available for resources with the [resolve capability][07]. This operation -is primarily useful for [importer resources][08]. +This operation is only available for resources with the [resolve capability][08]. This operation +is primarily useful for [importer resources][09]. ## See also -- [DSC resource capabilities][09] -- [DSC resource kinds][10] -- [DSC resource properties][11] -- [DSC command reference][12] +- [DSC resource capabilities][10] +- [DSC resource kinds][11] +- [DSC resource properties][12] +- [DSC command reference][13] [01]: ./capabilities.md#get @@ -117,10 +118,11 @@ is primarily useful for [importer resources][08]. [03]: ./capabilities.md#set [04]: ./capabilities.md#delete [05]: ./capabilities.md#export -[06]: ./kinds.md#adapter-resources -[07]: ./capabilities.md#resolve -[08]: ./kinds.md#importer-resources -[09]: ./capabilities.md -[10]: ./kinds.md -[11]: ./properties.md -[12]: ../../reference/cli/index.md +[06]: ./capabilities.md#synthetic-export +[07]: ./kinds.md#adapter-resources +[08]: ./capabilities.md#resolve +[09]: ./kinds.md#importer-resources +[10]: ./capabilities.md +[11]: ./kinds.md +[12]: ./properties.md +[13]: ../../reference/cli/index.md diff --git a/docs/concepts/resources/overview.md b/docs/concepts/resources/overview.md index 64d70a2a4..d42f5fe77 100644 --- a/docs/concepts/resources/overview.md +++ b/docs/concepts/resources/overview.md @@ -264,6 +264,12 @@ Use the `dsc resource export` command to invoke the operation. When you invoke t operation, DSC returns an array of resources instance definitions you can copy into a configuration document. +You can specify an input instance for the **Export** operation to filter the exported instances. If +a resource doesn't implement **Export**, you can still invoke the `dsc resource export` command. +When you invoke the **Export** operation for a resource that doesn't implement **Export**, DSC +provides a _synthetic export_. When using DSC's synthetic export feature, you must provide a +filtering instance of the resource. For more information, see [Synthetic export][04]. + ## Declaring resource instances DSC configuration documents enable managing more than one resource or resource instance at a time. @@ -298,14 +304,15 @@ resources: ## See also -- [Anatomy of a DSC command resource][04] to learn about authoring resources in your language +- [Anatomy of a DSC command resource][05] to learn about authoring resources in your language of choice. -- [DSC configuration documents][05] to learn about using resources in a configuration document. -- [Command line reference for the 'dsc resource' command][06] +- [DSC configuration documents][06] to learn about using resources in a configuration document. +- [Command line reference for the 'dsc resource' command][07] [01]: ../../reference/schemas/definitions/resourceType.md [02]: ../../reference/schemas/resource/properties/overview.md [03]: ../../reference/cli/resource/list.md -[04]: ./anatomy.md -[05]: ../configuration-documents/overview.md -[06]: ../../reference/cli/resource/index.md +[04]: capabilities.md#synthetic-export +[05]: ./anatomy.md +[06]: ../configuration-documents/overview.md +[07]: ../../reference/cli/resource/index.md