Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit8dc0655

Browse files
authored
Merge pull request#672 from michaeltlombardi/docs/main/v3-reference
(DOCS) Update CLI reference and conceptual docs for v3.0.0
2 parents5a2a744 +ae29420 commit8dc0655

File tree

72 files changed

+8460
-814
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

72 files changed

+8460
-814
lines changed
Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
---
2+
description:>-
3+
DSC configuration documents are YAML or JSON data files that define the desired state of a system
4+
declaratively. They're used to retrieve, validate, and enforce the state of multiple resource
5+
instances.
6+
ms.date:03/25/2025
7+
title:DSC configuration documents
8+
---
9+
10+
#DSC configuration documents
11+
12+
<!-- markdownlint-disable MD013-->
13+
14+
In Microsoft's Desired State Configuration (DSC) platform, DSC configuration documents declare the
15+
desired state of a system as data files. Configuration documents define a collection of
16+
[DSC resource][01] instances to describe what the desired state should be, not how to put the
17+
system into that state. The DSC resources handle the_how_ for each instance.
18+
19+
DSC can process configuration documents to:
20+
21+
- Retrieve the current state of the defined resource instances with the`dsc config get` command.
22+
- Validate whether the instances are in the desired state with the`dsc config test` command.
23+
- Enforce the desired state for the instances with the`dsc config set` command.
24+
- Export a new configuration document with every instance of a set of resources with the
25+
`dsc config export` command.
26+
27+
Configuration documents are YAML or JSON files that contain a single object. The object's
28+
properties define how DSC processes the document. The top-level properties for a document are:
29+
30+
-`$schema` (required) - Defines the URI for the JSON Schema the document adheres to. DSC
31+
uses this URI to know how to validate and interpret the document.
32+
-`resources` (required) - Defines the collection of resource instances the document manages.
33+
-`metadata` (optional) - Defines an arbitrary set of annotations for the document. Except for
34+
metadata within the`Microsoft.DSC` property, DSC doesn't validate this data or use it directly.
35+
The annotations can include notes like who authored the document, the last time someone updated
36+
it, or any other information. DSC doesn't use the annotations. The metadata is for documentation
37+
or other tools to use.
38+
39+
DSC applies validation to the`Microsoft.DSC` property. For more information, see the
40+
[DSC Configuration document metadata schema][02] reference.
41+
-`parameters` (optional) - Defines a set of runtime options for the configuration. Resource
42+
instances can reference parameters to reduce duplicate definitions or enable dynamic values.
43+
Parameters can have default values and can be set on any configuration operation.
44+
-`variables` (optional) - Defines a set of reusable values for the configuration. Resource
45+
instances can reference variables to reduce duplicate definitions.
46+
47+
##Defining a configuration document
48+
49+
Minimally, a configuration document defines the`$schema` and`resources` properties. The
50+
`$schema` property must be a valid URI for the DSC configuration document schema. The`resources`
51+
property must define at least one DSC Resource instance.
52+
53+
For example:
54+
55+
```yaml
56+
# example.dsc.config.yaml
57+
$schema:https://aka.ms/dsc/schemas/v3/bundled/config/document.json
58+
resources:
59+
-name:example key value
60+
type:Microsoft.Windows/Registry
61+
properties:
62+
keyPath:HKCU\example\key
63+
valueName:Example
64+
valueData:
65+
String:This is an example.
66+
```
67+
68+
The example document defines a single resource instance named`example key value`. The instance
69+
uses the `Microsoft.Windows/Registry` resource to declare the following desired state:
70+
71+
-The `example\key` registry key should exist in the system's current user hive.
72+
-The `example\key` registry key should have a value called `Example`.
73+
-The `Example` value should be the string `This is an example`.
74+
75+
The example document is _declarative_. It describes the desired state, not how to put the system
76+
into that state. It relies on the `Microsoft.Windows/Registry` resource to handle getting, testing,
77+
and setting the state of the registry key and value.
78+
79+
For more information about the structure and validation of configuration documents, see
80+
[DSC Configuration document schema reference][03].
81+
82+
### Defining resource instances
83+
84+
As shown in the prior example, configuration documents include a collection of resource instances.
85+
Together, the instances describe the desired state of a system. A configuration document can
86+
include any number of resource instances.
87+
88+
A resource instance declaration always includes:
89+
90+
-`name`- A short, human-readable name for the instance that's unique in the document. This name
91+
is used for logging and it helps describe the purpose of the instance.
92+
-`type`- The [fully qualified type name][04] of the resource that DSC should use to manage the
93+
instance.
94+
-`properties`- The desired state for the instance. DSC validates the values against the
95+
resource's instance schema.
96+
97+
Configuration documents can't include the same instance more than once. Declaring the same instance
98+
with different properties leads to enforcement cycling, where each declaration enforces an
99+
incompatible state for the instance on every run.
100+
101+
## Getting the current state of a configuration
102+
103+
The `dsc config get` command retrieves the current state of the resource instances defined in a
104+
configuration document. When you use this command, DSC also:
105+
106+
-Collects any message emitted by the resources during the operation.
107+
-Indicates whether any of the resources raised an error.
108+
-Provides metadata about the operation as a whole and for each resource instance.
109+
110+
```sh
111+
dsc config get --file ./example.config.dsc.yaml
112+
```
113+
114+
```yaml
115+
metadata:
116+
Microsoft.DSC:
117+
version: 3.0.0
118+
operation: get
119+
executionType: actual
120+
startDatetime: 2025-02-24T16:09:40.671454400-06:00
121+
endDatetime: 2025-02-24T16:09:41.850086300-06:00
122+
duration: PT1.1786319S
123+
securityContext: restricted
124+
results:
125+
- metadata:
126+
Microsoft.DSC:
127+
duration: PT0.2751153S
128+
name: example key value
129+
type: Microsoft.Windows/Registry
130+
result:
131+
actualState:
132+
keyPath: HKCU\example\key
133+
_exist: false
134+
messages: []
135+
hadErrors: false
136+
```
137+
138+
## Testing a configuration
139+
140+
The `dsc config test` command compares the current state of the resource instances to their desired
141+
state. The result for each instance includes:
142+
143+
-The desired state for the instance.
144+
-The actual state of the instance.
145+
-Whether the instance is in the desired state.
146+
-The list of properties that are out of the desired state, if any.
147+
148+
When you use this command, DSC also:
149+
150+
-Collects any message emitted by the resources during the operation.
151+
-Indicates whether any of the resources raised an error.
152+
-Provides metadata about the operation as a whole and for each resource instance.
153+
154+
```sh
155+
dsc config test --file ./example.config.dsc.yaml
156+
```
157+
158+
```yaml
159+
metadata:
160+
Microsoft.DSC:
161+
version: 3.0.0
162+
operation: test
163+
executionType: actual
164+
startDatetime: 2025-02-24T16:11:42.798122500-06:00
165+
endDatetime: 2025-02-24T16:11:43.442216400-06:00
166+
duration: PT0.6440939S
167+
securityContext: restricted
168+
results:
169+
- metadata:
170+
Microsoft.DSC:
171+
duration: PT0.2234078S
172+
name: example key value
173+
type: Microsoft.Windows/Registry
174+
result:
175+
desiredState:
176+
keyPath: HKCU\example\key
177+
valueName: Example
178+
valueData:
179+
String: This is an example.
180+
actualState:
181+
keyPath: HKCU\example\key
182+
_exist: false
183+
inDesiredState: false
184+
differingProperties:
185+
- valueName
186+
- valueData
187+
- _exist
188+
messages: []
189+
hadErrors: false
190+
```
191+
192+
## Enforcing a configuration
193+
194+
The `dsc config set` command enforces the resource instances defined in a configuration document to
195+
their desired state. The result for each instance includes:
196+
197+
-The state of the instance before the operation.
198+
-The state of the instance after the operation.
199+
-Which properties the operation changed, if any.
200+
201+
When you use this command, DSC also:
202+
203+
-Collects any message emitted by the resources during the operation.
204+
-Indicates whether any of the resources raised an error.
205+
-Provides metadata about the operation as a whole and for each resource instance.
206+
207+
```sh
208+
dsc config set --file ./example.config.dsc.yaml
209+
```
210+
211+
```yaml
212+
metadata:
213+
Microsoft.DSC:
214+
version: 3.0.0
215+
operation: set
216+
executionType: actual
217+
startDatetime: 2025-02-24T16:13:32.746742600-06:00
218+
endDatetime: 2025-02-24T16:13:33.606785-06:00
219+
duration: PT0.8600424S
220+
securityContext: restricted
221+
results:
222+
- metadata:
223+
Microsoft.DSC:
224+
duration: PT0.4070001S
225+
name: example key value
226+
type: Microsoft.Windows/Registry
227+
result:
228+
beforeState:
229+
keyPath: HKCU\example\key
230+
_exist: false
231+
afterState:
232+
keyPath: HKCU\example\key
233+
valueName: Example
234+
valueData:
235+
String: This is an example.
236+
changedProperties:
237+
- valueName
238+
- valueData
239+
- _exist
240+
messages: []
241+
hadErrors: false
242+
```
243+
244+
## See also
245+
246+
-[DSC Resources][01] to learn about resources.
247+
-[DSC Configuration document schema reference][05]
248+
-[Command line reference for the 'dsc config' command][06]
249+
250+
[01]:../resources/overview.md
251+
[02]:../../reference/schemas/config/metadata.md#microsoftdsc
252+
[03]:../../reference/schemas/config/document.md
253+
[04]:../resources/overview.md#resource-type-names
254+
[05]:../../reference/schemas/config/document.md
255+
[06]:../../reference/cli/config/index.md

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp