(DOCS) Update CLI reference and conceptual docs for v3.0.0 #672

michaeltlombardi · 2025-03-05T22:24:54Z

PR Summary

This changeset updates and adds reference documentation for the 3.0.0 GA release of DSC.

It includes:

Updated CLI reference
Updated and expanded documentation for concepts
Scaffold reference for built-in resources

Deferred to future PRs:

Reference docs for built-in resources
Updates to schema docs

PR Context

docs/getting-started/getting-started.md

docs/concepts/resources/anatomy.md

docs/overview.md

Gijsreyn · 2025-03-19T19:01:49Z

docs/overview.md

+---------------------------------------------------------------
+DesiredStateConfiguration-Preview 9PCX3HX4HZ0Z Unknown msstore
+```
+


Perhaps a small remark for the users telling something like:

[!INFO]
You can use either msstore or winget as the source. When using winget, it leverages the .zip file, whereas msstore uses the .msixbundle.

SteveL-MSFT

Will need more time to go through all the docs

SteveL-MSFT · 2025-04-15T20:44:36Z

docs/concepts/configuration-documents/overview.md

+  type: Microsoft.Windows/Registry
+  result:
+    actualState:
+      keyPath: HKCU\example\key


Enclose in single quotes so that the backslash doesn't need to be escaped

Suggested change

keyPath: HKCU\example\key

keyPath: 'HKCU\example\key'

The backslash doesn't need escaping in YAML for unquoted strings:

@' unquoted: foo\bar\baz double_quoted: "foo\\bar\\baz" single_quoted: 'foo\bar\baz' '@ | ConvertFrom-Yaml | Format-List Name : unquoted Value : foo\bar\baz Name : double_quoted Value : foo\bar\baz Name : single_quoted Value : foo\bar\baz

I guess it's just GitHub's syntax coloring then

docs/concepts/configuration-documents/overview.md

SteveL-MSFT · 2025-04-15T20:50:09Z

docs/concepts/configuration-documents/overview.md

+- Provides metadata about the operation as a whole and for each resource instance.
+
+```sh
+dsc config test --file /example.config.dsc.yaml


Suggested change

dsc config test --file /example.config.dsc.yaml

dsc config test --file ./example.config.dsc.yaml

Is this missing the period? Otherwise it's an absolute path

I don't see this as fixed?

docs/concepts/enhanced-authoring.md

docs/concepts/configuration-documents/overview.md

mgreenegit · 2025-04-16T14:29:46Z

docs/concepts/output-accessibility.md

+### HyperText Markup Language (HTML) format
+
+HTML files can be viewed by web browsers such as **Microsoft Edge**. The following example shows
+how to save the output of a command to an HTML file.
+
+```powershell
+dsc resource list | ConvertFrom-Json | ConvertTo-HTML | Out-File .\myFile.html
+Invoke-Item .\myFile.html
+```
+
+The `Invoke-Item` command opens the file in your default web browser.
+


Suggested change

### HyperText Markup Language (HTML) format

HTML files can be viewed by web browsers such as **Microsoft Edge**. The following example shows

how to save the output of a command to an HTML file.

```powershell

dsc resource list | ConvertFrom-Json | ConvertTo-HTML | Out-File .\myFile.html

Invoke-Item .\myFile.html

```

The `Invoke-Item` command opens the file in your default web browser.

unfortunately we need to remove these until an issue is resolved in PWSH

@theJasonHelmick - how does removing this affect the accessibility concerns?

Maybe we just note that this work in Windows PowerShell and link to the issue / remove the notice when that issue is resolved?

The html written (5.1 or 7) as output does not include language tags so screen readers have to assume system language. We can’t use this, as a result.

mgreenegit

This is such as massive PR, it will be easier to "nit pick" using small PRs after it is published. At a high level, everything looks good to me.

Prior to this change, the docs folder didn't include any conceptual documentation, only reference documents. This change copies existing concept docs into the folder, updates them for GA, and adds new conceptual documentation to make it easier for new users to learn about DSC and start using it.

This change updates the reference docs for: - `Microsoft/OSInfo` resource - `osinfo` CLI tool - `Microsoft.Windows/Registry` resource - `registry` CLI tool These are the only resources currently documented on the live docs site.

SteveL-MSFT · 2025-04-25T04:47:41Z

docs/concepts/resources/anatomy.md

+
+At a minimum, the manifest must define:
+
+- The version of the DSC resource manifest JSON schema it's compatible with.


We should specify that the version is in semver format

SteveL-MSFT · 2025-04-25T04:52:55Z

docs/concepts/resources/capabilities.md

+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


It should be noted that in the case of arrays, the ordering doesn't matter, but the number of elements and the elements themselves have to be the same. In the case of objects, the actual state can be a superset of the desired state.

SteveL-MSFT · 2025-04-25T04:54:20Z

docs/concepts/resources/capabilities.md

+
+## export
+
+A resource with the `export` capability supports enumerating every instance of the resource with


I think it's worth calling out that if no input is provided, expectation is all instances are returned, but if there is input, then that input should be used as a filter.

SteveL-MSFT · 2025-04-25T04:58:23Z

docs/concepts/resources/properties.md

+If you specify an invalid property name or an invalid value for a property, DSC raises an error
+describing how the data is invalid.
+
+Unless otherwise noted, for any given property:


Should we specify here that property names with leading underscore is reserved for canonical DSC properties that adhere to DSC defined syntax and semantics

michaeltlombardi force-pushed the docs/main/v3-reference branch from 8322bb9 to 84a9cd8 Compare March 17, 2025 22:12

michaeltlombardi changed the title ~~(DOCS) Update reference docs for v3.0.0~~ (DOCS) Update CLI reference and conceptual docs for v3.0.0 Mar 17, 2025

michaeltlombardi marked this pull request as ready for review March 17, 2025 22:15

Gijsreyn reviewed Mar 18, 2025

View reviewed changes

docs/getting-started/getting-started.md Outdated Show resolved Hide resolved

Gijsreyn mentioned this pull request Mar 18, 2025

Feedback on PowerShell DSC MicrosoftDocs/PowerShell-Docs#11890

Closed

3 tasks

michaeltlombardi force-pushed the docs/main/v3-reference branch from 69f79fe to 18a2eee Compare March 18, 2025 14:45

Gijsreyn reviewed Mar 19, 2025

View reviewed changes

docs/concepts/resources/anatomy.md Outdated Show resolved Hide resolved

Gijsreyn reviewed Mar 19, 2025

View reviewed changes

docs/concepts/resources/anatomy.md Outdated Show resolved Hide resolved

Gijsreyn reviewed Mar 19, 2025

View reviewed changes

docs/overview.md Show resolved Hide resolved

Gijsreyn reviewed Mar 19, 2025

View reviewed changes

michaeltlombardi force-pushed the docs/main/v3-reference branch from 18a2eee to 690ae7e Compare March 26, 2025 15:06

michaeltlombardi force-pushed the docs/main/v3-reference branch from 690ae7e to de65bee Compare April 2, 2025 15:35

michaeltlombardi requested a review from SteveL-MSFT April 15, 2025 14:55

SteveL-MSFT requested changes Apr 15, 2025

View reviewed changes

SteveL-MSFT requested review from theJasonHelmick and mgreenegit April 15, 2025 20:56

mgreenegit reviewed Apr 16, 2025

View reviewed changes

docs/concepts/configuration-documents/overview.md Show resolved Hide resolved

mgreenegit reviewed Apr 16, 2025

View reviewed changes

docs/concepts/configuration-documents/overview.md Show resolved Hide resolved

mgreenegit reviewed Apr 16, 2025

View reviewed changes

mgreenegit approved these changes Apr 16, 2025

View reviewed changes

michaeltlombardi added 5 commits April 23, 2025 15:43

(DOCS) Scaffold reference docs for built-in resources

7a45aab

(DOCS) Update CLI reference for v3.0.0

00234d7

(DOCS) Update reference for OSInfo/Registry

a24863a

This change updates the reference docs for: - `Microsoft/OSInfo` resource - `osinfo` CLI tool - `Microsoft.Windows/Registry` resource - `registry` CLI tool These are the only resources currently documented on the live docs site.

(DOCS) Sync updates from docs review on Learn platform

4f7cbac

michaeltlombardi force-pushed the docs/main/v3-reference branch from 2073abd to 4f7cbac Compare April 23, 2025 20:44

michaeltlombardi requested a review from SteveL-MSFT April 23, 2025 20:47

SteveL-MSFT requested changes Apr 25, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

(DOCS) Update CLI reference and conceptual docs for v3.0.0 #672

(DOCS) Update CLI reference and conceptual docs for v3.0.0 #672

michaeltlombardi commented Mar 5, 2025 •

edited

Loading

Gijsreyn Mar 19, 2025

SteveL-MSFT left a comment

SteveL-MSFT Apr 15, 2025

michaeltlombardi Apr 23, 2025

SteveL-MSFT Apr 25, 2025

SteveL-MSFT Apr 15, 2025

SteveL-MSFT Apr 25, 2025

mgreenegit Apr 16, 2025

michaeltlombardi Apr 23, 2025

mgreenegit Apr 25, 2025

mgreenegit left a comment

SteveL-MSFT Apr 25, 2025

SteveL-MSFT Apr 25, 2025

SteveL-MSFT Apr 25, 2025

SteveL-MSFT Apr 25, 2025

	dsc config test --file /example.config.dsc.yaml
	dsc config test --file ./example.config.dsc.yaml


		At a minimum, the manifest must define:

		- The version of the DSC resource manifest JSON schema it's compatible with.


		## export

		A resource with the `export` capability supports enumerating every instance of the resource with

(DOCS) Update CLI reference and conceptual docs for v3.0.0 #672

Are you sure you want to change the base?

(DOCS) Update CLI reference and conceptual docs for v3.0.0 #672

Conversation

michaeltlombardi commented Mar 5, 2025 • edited Loading

PR Summary

PR Context

Choose a reason for hiding this comment

SteveL-MSFT left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mgreenegit left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michaeltlombardi commented Mar 5, 2025 •

edited

Loading