(DOCS) Update CLI reference and conceptual docs for v3.0.0 #672
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
michaeltlombardi
force-pushed
the
docs/main/v3-reference
branch
from
8322bb9 to
84a9cd8
Compare
michaeltlombardi
changed the title
Gijsreyn
reviewed
Mar 18, 2025
3 tasks
michaeltlombardi
force-pushed
the
docs/main/v3-reference
branch
from
69f79fe to
18a2eee
Compare
Gijsreyn
reviewed
Mar 19, 2025
Gijsreyn
reviewed
Mar 19, 2025
Gijsreyn
reviewed
Mar 19, 2025
Gijsreyn
reviewed
Mar 19, 2025
| --------------------------------------------------------------- | ||
| DesiredStateConfiguration-Preview 9PCX3HX4HZ0Z Unknown msstore | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Perhaps a small remark for the users telling something like:
[!INFO]
You can use eithermsstoreorwingetas the source. When usingwinget, it leverages the.zipfile, whereasmsstoreuses the.msixbundle.
michaeltlombardi
force-pushed
the
docs/main/v3-reference
branch
from
18a2eee to
690ae7e
Compare
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.
michaeltlombardi
force-pushed
the
docs/main/v3-reference
branch
from
690ae7e to
de65bee
Compare
SteveL-MSFT
requested changes
Apr 15, 2025
| type: Microsoft.Windows/Registry | ||
| result: | ||
| actualState: | ||
| keyPath: HKCU\example\key |
There was a problem hiding this comment.
Enclose in single quotes so that the backslash doesn't need to be escaped
Suggested change
| keyPath: HKCU\example\key | |
| keyPath: 'HKCU\example\key' |
| - Export a new configuration document with every instance of a set of resources with the | ||
| `dsc config export` command. | ||
|
|
||
| Configuration documents are YAML or JSON files that contain a single object. The object's |
There was a problem hiding this comment.
Does it help to mention relationship to ARM templates since those have more docs and examples?
There was a problem hiding this comment.
And given the very positive reaction to Bicep at PS Summit, this makes it sound like we only support the two languages, when we actually support a third, as an abstraction of the JSON.
| - Provides metadata about the operation as a whole and for each resource instance. | ||
|
|
||
| ```sh | ||
| dsc config test --file /example.config.dsc.yaml |
There was a problem hiding this comment.
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
| ```json | ||
| "json.schemas": [ | ||
| { | ||
| "fileMatch": ["**/*.dsc.resource.json", ], |
There was a problem hiding this comment.
Suggested change
| "fileMatch": ["**/*.dsc.resource.json", ], | |
| "fileMatch": ["**/*.dsc.resource.json"], |
mgreenegit
reviewed
Apr 16, 2025
| - Export a new configuration document with every instance of a set of resources with the | ||
| `dsc config export` command. | ||
|
|
||
| Configuration documents are YAML or JSON files that contain a single object. The object's |
There was a problem hiding this comment.
Suggested change
| Configuration documents are YAML or JSON files that contain a single object. The object's | |
| Configuration documents contain a single object formatted as YAML, JSON, or Bicep (which compiles to JSON). The object's |
mgreenegit
reviewed
Apr 16, 2025
| `dsc config export` command. | ||
|
|
||
| Configuration documents are YAML or JSON files that contain a single object. The object's | ||
| properties define how DSC processes the document. The top-level properties for a document are: |
There was a problem hiding this comment.
Suggested change
| properties define how DSC processes the document. The top-level properties for a document are: | |
| properties define how DSC processes the document. It is intentional that DSC configuration documents | |
| should be familiar to authors accustomed to working with | |
| [Azure Resource Manager deployment templates](./azure/azure-resource-manager/templates/). | |
| The top-level properties for a document are: |
mgreenegit
reviewed
Apr 16, 2025
Comment on lines
+65
to
+76
| ### 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. | ||
|
|
There was a problem hiding this comment.
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
mgreenegit
approved these changes
Apr 16, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
PR Summary
This changeset updates and adds reference documentation for the
3.0.0GA release of DSC.It includes:
Deferred to future PRs:
PR Context