From 6e9d856d94207f83748807c5178311b53d058279 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Mon, 23 Mar 2026 01:14:50 +0100 Subject: [PATCH 1/2] Update adapter docs --- docs/concepts/output-accessibility.md | 4 +- docs/concepts/resources/overview.md | 2 +- docs/get-started/index.md | 542 ------------------ docs/overview.md | 6 +- docs/reference/cli/resource/list.md | 4 +- .../examples/configure-a-machine.md | 89 +++ .../powershell/examples/invoke-a-resource.md | 117 ++++ .../Microsoft/adapter/powershell/index.md | 187 ++++++ .../examples/manage-a-windows-service.md | 161 ++++++ .../adapter/windowspowershell/index.md | 211 +++++++ docs/reference/resources/overview.md | 13 +- dsc/examples/groups.dsc.yaml | 2 +- dsc/examples/multiline.dsc.yaml | 4 +- dsc/examples/parallel.dsc.yaml | 47 -- dsc/examples/timezone.dsc.yaml | 12 +- dsc/examples/winget.dsc.yaml | 26 +- dsc/examples/winps_script.dsc.yaml | 36 +- 17 files changed, 822 insertions(+), 641 deletions(-) delete mode 100644 docs/get-started/index.md create mode 100644 docs/reference/resources/Microsoft/adapter/powershell/examples/configure-a-machine.md create mode 100644 docs/reference/resources/Microsoft/adapter/powershell/examples/invoke-a-resource.md create mode 100644 docs/reference/resources/Microsoft/adapter/powershell/index.md create mode 100644 docs/reference/resources/Microsoft/adapter/windowspowershell/examples/manage-a-windows-service.md create mode 100644 docs/reference/resources/Microsoft/adapter/windowspowershell/index.md delete mode 100644 dsc/examples/parallel.dsc.yaml diff --git a/docs/concepts/output-accessibility.md b/docs/concepts/output-accessibility.md index 946129666..e18510705 100644 --- a/docs/concepts/output-accessibility.md +++ b/docs/concepts/output-accessibility.md @@ -43,7 +43,7 @@ dsc resource list | ConvertFrom-Json | Out-GridView The following example shows how to display a list of DSC adapted resources in a GridView control. ```powershell -dsc resource list -a Microsoft.Windows/WindowsPowerShell | +dsc resource list -a Microsoft.Adapter/WindowsPowerShell | ConvertFrom-Json | Out-GridView ``` @@ -83,7 +83,7 @@ Each of the following commands improves the output in a different way: experience for screen readers. ```powershell -dsc resource list -a Microsoft.Windows/WindowsPowerShell | +dsc resource list -a Microsoft.Adapter/WindowsPowerShell | ConvertFrom-Json | Where-Object {$_.type -like "*process*" } | Select-Object -Property Type, Kind, Version | diff --git a/docs/concepts/resources/overview.md b/docs/concepts/resources/overview.md index d42f5fe77..4e8f5eaf8 100644 --- a/docs/concepts/resources/overview.md +++ b/docs/concepts/resources/overview.md @@ -29,7 +29,7 @@ DSC supports several kinds of resources: resource instances and processes them. Group resources can apply special handling to their nested resource instances, like changing the user the resources run as. - An _adapter resource_ is a group resource that enables the use of noncommand resources with DSC. - For example, the `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` adapter + For example, the `Microsoft.Adapter/PowerShell` and `Microsoft.Adapter/WindowsPowerShell` adapter resources enable the use of PowerShell DSC (PSDSC) resources in DSC, invoking the resources in PowerShell and Windows PowerShell respectively. diff --git a/docs/get-started/index.md b/docs/get-started/index.md deleted file mode 100644 index 9118bb73f..000000000 --- a/docs/get-started/index.md +++ /dev/null @@ -1,542 +0,0 @@ ---- -description: >- - Learn how to use Microsoft's Desired State Configuration platform to manage the state of a - machine as code. -ms.date: 03/25/2025 -title: Get started with DSC ---- - -# Get started with DSC - -Microsoft's Desired State Configuration (DSC) is a declarative configuration platform. You can use -DSC resources to query, audit, and set the state of a specific component on a system. You can use -DSC configuration documents to describe how a system should be configured using one or more -resources. This document describes how you can discover the resources available on a machine, -invoke those resources directly, and manage a configuration. - -## Prerequisites - -- [Install DSC][01] version `3.0.0` on a Windows machine. -- A terminal emulator, like [Windows Terminal][02]. - -## Discover resources - -You can use the `dsc resource list` command to enumerate the available DSC resources on a machine. -DSC discovers resources by searching the folders in your `PATH` environment variable for files that -have any of the following suffixes: - -- `.dsc.resource.json` -- `.dsc.resource.yaml` -- `.dsc.resource.yml` - -Files with the `.dsc.resource.` suffix are DSC resource manifests. They describe both -the settings they enable you to manage and how DSC can invoke them as a command. - -Open a terminal and run the following command: - -```powershell -dsc resource list -``` - -DSC outputs a table showing the available resources and summary information about each resource. - -```Output -Type Kind Version Capabilities RequireAdapter Description ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- -Microsoft.DSC.Debug/Echo Resource 1.0.0 gs--t--- -Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs------ Takes a single-command line to execute on DSC set operation -Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration. -Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group. -Microsoft.DSC/Include Importer 0.1.0 gs--t--- Allows including a configuration file with optional parameter file. -Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources. -Microsoft.Windows/RebootPending Resource 0.1.0 g------- Returns info about pending reboot. -Microsoft.Windows/Registry Resource 0.1.0 gs-w-d-- Manage Windows Registry keys and values -Microsoft.Windows/WMI Adapter 0.1.0 g------- Resource adapter to WMI resources. -Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs--t--- Resource adapter to classic DSC Powershell resources in Windows PowerShell. -Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system. -Microsoft/Process Resource 0.1.0 gs--t-e- Returns information about running processes. -``` - -Together, the columns describe each resource: - -- The **Type** column defines the fully qualified type name for a resource. This name identifies the - resource on a system and in a configuration document. -- The **Kind** column indicates how you can use the resource. - - `Adapter` indicates that the resource is an adapter resource and enables you to configure - components that don't define a DSC resource manifest, like PowerShell DSC (PSDSC) resources. - - `Group` indicates that the resource is a group resource and changes how DSC processes a list of - resource instances. Group resources don't directly manage state on a system. - - `Importer` indicates that the resource is an importer resource that retrieves a configuration - document from an external source to insert into the current configuration document. - - `Resource` indicates that the resource is typical - not an adapter, group, or importer resource. -- The **Version** column indicates the latest discovered version of the resource on the system. -- The **Capabilities** column indicates how the resource is implemented and what you can expect - when using it. The table displays the capabilities as flags in the following order, using a `-` - instead of the appropriate letter if the resource doesn't have a specific capability: - - - `g` indicates that the resource has the `get` capability. - - `s` indicates that the resource has the `set` capability. - - `x` indicates that the resource has the `setHandlesExist` capability. - - `w` indicates that the resource has the `whatIf` capability. - - `t` indicates that the resource has the `test` capability. - - `d` indicates that the resource has the `delete` capability. - - `e` indicates that the resource has the `export` capability. - - `r` indicates that the resource has the `resolve` capability. - -- The **RequireAdapter** column indicates which adapter resource, if any, the resource requires. -- The **Description** column defines a synopsis for the resource. - -By default, the `dsc resource list` command only returns command resources, which always have a -resource manifest. You can use the `--adapter` option to return the resources for one or more -adapted resources. - -Run the following command to return the available adapted resources instead of command resources: - -```powershell -$adaptedResources = dsc resource list --adapter * | ConvertFrom-Json - -$adaptedResources | - Group-Object -NoElement -Property requireAdapter | - Format-Table -AutoSize -``` - -```Output -Count Name ------ ---- - 27 Microsoft.Windows/WindowsPowerShell - 961 Microsoft.Windows/WMI -``` - -The output of `dsc resource list` is saved to the `$resources` variable as an array of PowerShell -objects. When you first ran the `dsc resource list` command, the output in the terminal was a table -view. By default, when DSC detects output redirection, it formats the output as JSON. Converting the -JSON into a PowerShell object with the `ConvertFrom-Json` cmdlet enables you to treat the output -like any other PowerShell object. - -The `Group-Object` cmdlet summarizes the available adapted resources, grouped by the adapter that -they require. The specific count for adapted resources depends on the machine you're using and the -installed PowerShell modules that export any PSDSC resources. - -Run the following command to display only the resources available with the -`Microsoft.Windows/WindowsPowerShell` adapter. - -```powershell -$adaptedResources | - Where-Object -Property requireAdapter -eq Microsoft.Windows/WindowsPowerShell | - Format-Table -Property type, kind, version, capabilities, description -``` - -```Output -type kind version capabilities description ----- ---- ------- ------------ ----------- -PSDesiredStateConfiguration/Archive resource 1.1 {get, set, test} -PSDesiredStateConfiguration/Environment resource 1.1 {get, set, test} -PSDesiredStateConfiguration/File resource 1.0.0 {get, set, test} -PSDesiredStateConfiguration/Group resource 1.1 {get, set, test} -PSDesiredStateConfiguration/GroupSet resource 1.1 {get, set, test} -PSDesiredStateConfiguration/Log resource 1.1 {get, set, test} -PSDesiredStateConfiguration/Package resource 1.1 {get, set, test} -PSDesiredStateConfiguration/ProcessSet resource 1.1 {get, set, test} -PSDesiredStateConfiguration/Registry resource 1.1 {get, set, test} -PSDesiredStateConfiguration/Script resource 1.1 {get, set, test} -PSDesiredStateConfiguration/Service resource 1.1 {get, set, test} -PSDesiredStateConfiguration/ServiceSet resource 1.1 {get, set, test} -PSDesiredStateConfiguration/SignatureValidation resource 1.0.0 {get, set, test} -PSDesiredStateConfiguration/User resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WaitForAll resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WaitForAny resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WaitForSome resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WindowsFeature resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WindowsFeatureSet resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WindowsOptionalFeature resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WindowsOptionalFeatureSet resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WindowsPackageCab resource 1.1 {get, set, test} -PSDesiredStateConfiguration/WindowsProcess resource 1.1 {get, set, test} -PackageManagement/PackageManagement resource 1.4.8.1 {get, set, test} PackageManagement (a.k.a. OneGet) is a new way to discover and install software packa… -PackageManagement/PackageManagementSource resource 1.4.8.1 {get, set, test} PackageManagement (a.k.a. OneGet) is a new way to discover and install software packa… -PowerShellGet/PSModule resource 2.2.5 {get, set, test} PowerShell module with commands for discovering, installing, updating and publishing … -PowerShellGet/PSRepository resource 2.2.5 {get, set, test} PowerShell module with commands for discovering, installing, updating and publishing … -``` - -For more information about the command, see [dsc resource list][03]. - -## Invoke a resource - -You can use DSC to directly invoke a resource. When you invoke a resource, you're performing a -specific operation on an _instance_ of the resource. A resource instance is a specific item the -resource represents. The following examples use the `Microsoft.Windows/Registry` resource to invoke -DSC operations. - -First, use the `dsc resource list` command to see what capabilities the `Registry` resource has. - -```powershell -$resource = dsc resource list Microsoft.Windows/Registry | ConvertFrom-Json -$resource.capabilities -``` - -```Output -get -set -whatIf -delete -``` - -Together, these capabilities tell us that you can use the `Registry` command resource to: - -- The `get` capability indicates that you can invoke the **Get** operation to retrieve the current - state of an instance. -- The `set` capability indicates that you can invoke the **Set** operation to modify the state of - an instance. -- The `whatIf` capability indicates that you can invoke the **Set** operation in what-if mode to - see how the resource would change the instance without actually modifying the system. -- The `delete` capability indicates that you can invoke the **Delete** operation to remove an - instance from the system. - -### Get the current state of a resource - -You can use the `dsc resource get` command to retrieve the current state of an instance. Run the -following command to define the data that represents a registry value: - -```powershell -$instance = @{ - keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion' - valueName = 'SystemRoot' -} | ConvertTo-Json -``` - -For this example: - -- The `keyPath` property to indicate the path to the registry key that should contain the value you - want to manage. `keyPath` is a _required_ property for the `Registry` resource - you always need - to specify it. -- The `valueName` property identifies which registry value to manage for the registry key. -- The `_exist` canonical property indicates whether the registry value should exist. In this - example, the value is `true`, which indicates that the instance should exist. - -Run the following command to get the current state of the registry key: - -```powershell -dsc resource get --resource $resource.type --input $instance -``` - -```yaml -actualState: - keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion - valueName: SystemRoot - valueData: - String: C:\WINDOWS -``` - -The output shows that the value is set to the string `C:\WINDOWS`. - -### Test whether a resource is in the desired state - -Retrieving the current state of a resource is useful, but in practice you more often want to know -whether an instance is in the desired state. The `dsc resource test` command not only tells you -whether an instance is out of state, but how it's out state. - -> [!NOTE] -> Remember that the `Registry` resource doesn't have the `test` capability. Fortunately, that -> doesn't mean that you can't use the **Test** operation for a resource. When a resource doesn't -> have the `test` capability, it is indicating that the resource depends on DSC's synthetic test -> capabilities. DSC itself calls the **Get** operation for the resource and compares it to the -> desired state. - -Run the following commands to define the desired state of a registry key that doesn't exist and test -it. - -```powershell -$desired = @{ - keyPath = 'HKCU\dsc\example\key' - _exist = $true -} | ConvertTo-Json -dsc resource test --resource $resource.type --input $desired -``` - -```yaml -desiredState: - keyPath: HKCU\dsc\example\key - _exist: true -actualState: - keyPath: HKCU\dsc\example\key - _exist: false -inDesiredState: false -differingProperties: -- _exist -``` - -The output for the command shows you the desired state, actual state, and how they differ. In this -case, the registry key doesn't exist - the `_exist` property is `false` when the desired state is -`true`. - -### Set the desired state of a resource - -You can also directly invoke a resource to set the state for an instance if the resource has the -`set` capability. - -Run the following command to create the registry key: - -```powershell - -dsc resource set --resource $resource.type --input $desired -``` - -```yaml -beforeState: - keyPath: HKCU\dsc\example\key - _exist: false -afterState: - keyPath: HKCU\dsc\example\key -changedProperties: -- _exist -``` - -The output indicates that the resource created the missing instance. - -## Manage a configuration - -Invoking resources directly is useful, but tedious for defining the desired state of a system. You -can define a DSC configuration document to describe a set of resource instances together. - -Copy the following code block and save it in a file named `example.dsc.config.yaml`. - -```yaml -$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json -resources: -- name: Example registry key - type: Microsoft.Windows/Registry - properties: - keyPath: HKCU\dsc\example\key - _exist: true -- name: PSDSC resources - type: Microsoft.Windows/WindowsPowerShell - properties: - resources: - - name: DSC_EXAMPLE env variable - type: PSDesiredStateConfiguration/Environment - properties: - Name: DSC_EXAMPLE - Ensure: Present - Value: Set by DSC -``` - -The configuration document specifies two resource instances at the top level: - -- The `Microsoft.Windows/Registry` resource to ensure that a registry key exists. -- The `Microsoft.Windows/WindowsPowerShell` adapter resource to define PowerShell DSC (PSDSC) - resources. - -The `WindowsPowerShell` adapter instance defines a single property, `resources`, as an array of -resource instances. In this configuration, it defines two instances: - -- The first instance uses the `PSRepository` PSDSC resource from the **PowerShellGet** module to - make sure the PowerShell Gallery is available for use as a repository. -- The second instance uses the `PSModule` PSDSC resource from the same module to make sure that the - **Microsoft.WinGet.Client** module is installed. - - > [!NOTE] - > When invoking resources from `WindowsPowerShell` adapter, Windows Remote Management (WinRM) needs to be configured properly on the system. For more information about configuring WinRM, see [Setting Up a WinRM Endpoint](/windows/win32/winrm/installation-and-configuration-for-windows-remote-management#to-configure-winrm-with-default-settings). - -Open a terminal with elevated permissions. PSDSC resources in Windows PowerShell need to run as -administrator. In the elevated terminal, change directory to the folder where you saved the -configuration document as `example.dsc.config.yaml`. Then run the following command. - -```powershell -dsc config test --file ./example.dsc.config.yaml -``` - -```yaml -metadata: - Microsoft.DSC: - version: 3.0.0 - operation: test - executionType: actual - startDatetime: 2025-03-03T17:11:25.726475600-06:00 - endDatetime: 2025-03-03T17:11:32.567311800-06:00 - duration: PT6.8408362S - securityContext: elevated -results: -- metadata: - Microsoft.DSC: - duration: PT0.1818183S - name: Example registry key - type: Microsoft.Windows/Registry - result: - desiredState: - keyPath: HKCU\dsc\example\key - _exist: true - actualState: - keyPath: HKCU\dsc\example\key - inDesiredState: true - differingProperties: [] -- metadata: - Microsoft.DSC: - duration: PT3.0461988S - name: PSDSC resources - type: Microsoft.Windows/WindowsPowerShell - result: - desiredState: - resources: - - name: DSC_EXAMPLE env variable - type: PSDesiredStateConfiguration/Environment - properties: - Name: DSC_EXAMPLE - Ensure: Present - Value: Set by DSC - metadata: - Microsoft.DSC: - context: configuration - actualState: - result: - - name: DSC_EXAMPLE env variable - type: PSDesiredStateConfiguration/Environment - properties: - InDesiredState: false - inDesiredState: false - differingProperties: - - resources - - metadata -messages: [] -hadErrors: false -``` - -The output shows that: - -- The `Registry` instance is in the desired state. Earlier in this article, you created the key by - invoking the **Set** operation directly. - -- The adapted `Environment` PSDSC resource reports that the `DSC_EXAMPLE` environment variable is - _not_ in the desired state. - -Run the following command to enforce the desired state on the system. - -```powershell -dsc config set --file ./example.dsc.config.yaml -``` - -```yaml -metadata: - Microsoft.DSC: - version: 3.0.0 - operation: set - executionType: actual - startDatetime: 2025-03-03T17:14:15.841393700-06:00 - endDatetime: 2025-03-03T17:14:29.136469500-06:00 - duration: PT13.2950758S - securityContext: elevated -results: -- metadata: - Microsoft.DSC: - duration: PT0.2633556S - name: Example registry key - type: Microsoft.Windows/Registry - result: - beforeState: - keyPath: HKCU\dsc\example\key - _exist: true - afterState: - keyPath: HKCU\dsc\example\key - changedProperties: null -- metadata: - Microsoft.DSC: - duration: PT8.6601181S - name: PSDSC resources - type: Microsoft.Windows/WindowsPowerShell - result: - beforeState: - result: - - name: DSC_EXAMPLE env variable - type: PSDesiredStateConfiguration/Environment - properties: - ResourceId: null - PsDscRunAsCredential: null - PSComputerName: localhost - ModuleVersion: '1.1' - Value: null - Path: null - ConfigurationName: null - Name: DSC_EXAMPLE - ModuleName: PSDesiredStateConfiguration - SourceInfo: null - DependsOn: null - Ensure: Absent - afterState: - result: - - name: DSC_EXAMPLE env variable - type: PSDesiredStateConfiguration/Environment - properties: - RebootRequired: false - changedProperties: - - result -messages: [] -hadErrors: false -``` - -To review the actual state of the system, run the `dsc config get` command: - -```powershell -dsc config get --file ./example.dsc.config.yaml -``` - -```yaml -metadata: - Microsoft.DSC: - version: 3.0.0 - operation: get - executionType: actual - startDatetime: 2025-03-03T17:16:39.507848200-06:00 - endDatetime: 2025-03-03T17:16:47.734256600-06:00 - duration: PT8.2264084S - securityContext: elevated -results: -- metadata: - Microsoft.DSC: - duration: PT0.1739569S - name: Example registry key - type: Microsoft.Windows/Registry - result: - actualState: - keyPath: HKCU\dsc\example\key -- metadata: - Microsoft.DSC: - duration: PT3.9958946S - name: PSDSC resources - type: Microsoft.Windows/WindowsPowerShell - result: - actualState: - result: - - name: DSC_EXAMPLE env variable - type: PSDesiredStateConfiguration/Environment - properties: - ResourceId: null - PsDscRunAsCredential: null - PSComputerName: localhost - ModuleVersion: '1.1' - Value: Set by DSC - Path: null - ConfigurationName: null - Name: DSC_EXAMPLE - ModuleName: PSDesiredStateConfiguration - SourceInfo: null - DependsOn: null - Ensure: Present -messages: [] -hadErrors: false -``` - -## Related content - -- [Glossary: Desired State Configuration][04] -- [DSC configuration documents][05] -- [DSC Resources][06] -- [DSC command reference][07] - - - -[01]: ../overview.md#installation -[02]: /windows/terminal/ -[03]: ../reference/cli/resource/list.md -[04]: ../glossary.md -[05]: ../concepts/configuration-documents/overview.md -[06]: ../concepts/resources/overview.md -[07]: ../reference/cli/index.md diff --git a/docs/overview.md b/docs/overview.md index 5f43cbecb..e029ab0fb 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -53,13 +53,13 @@ DSC differs from PowerShell Desired State Configuration (PSDSC) in a few importa - DSC doesn't _depend_ on PowerShell, Windows PowerShell, or the [PSDesiredStateConfiguration][01] PowerShell module. DSC provides full compatibility with PSDSC resources through the - `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` _adapter resources_. + `Microsoft.Adapter/PowerShell` and `Microsoft.Adapter/WindowsPowerShell` _adapter resources_. - With the `Microsoft.DSC/PowerShell` adapter resource, you can use any PSDSC resource implemented + With the `Microsoft.Adapter/PowerShell` adapter resource, you can use any PSDSC resource implemented as a PowerShell class. The resource handles discovering, validating, and invoking PSDSC resources in PowerShell. The resource is included in the DSC install package for every platform. - With the `Microsoft.Windows/WindowsPowerShell` adapter resource, you can use any PSDSC resource + With the `Microsoft.Adapter/WindowsPowerShell` adapter resource, you can use any PSDSC resource compatible with Windows PowerShell. The resource handles discovering, validating, and invoking PSDSC resources in Windows PowerShell. The resource is included in the DSC install packages for Windows only. diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md index 684a37acb..5a60c3db0 100644 --- a/docs/reference/cli/resource/list.md +++ b/docs/reference/cli/resource/list.md @@ -145,14 +145,14 @@ adds the returned list of adapted resources to the discovered resource list. DSC further filters specified with the command after this enumeration. ```sh -dsc resource list --adapter Microsoft.Windows/WindowsPowerShell +dsc resource list --adapter Microsoft.Adapter/WindowsPowerShell ``` This next command specifies the resource name filter `*Windows*`, limiting the list of returned resources: ```sh -dsc resource list --adapter Microsoft.Windows/WindowsPowerShell *Windows* +dsc resource list --adapter Microsoft.Adapter/WindowsPowerShell *Windows* ``` ## Arguments diff --git a/docs/reference/resources/Microsoft/adapter/powershell/examples/configure-a-machine.md b/docs/reference/resources/Microsoft/adapter/powershell/examples/configure-a-machine.md new file mode 100644 index 000000000..8d0fca2a3 --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/powershell/examples/configure-a-machine.md @@ -0,0 +1,89 @@ +--- +description: > + Example showing how to configure a machine using multiple class-based PowerShell DSC resources + with the Microsoft.Adapter/PowerShell adapter in a DSC configuration document. + +ms.date: 03/23/2026 +ms.topic: reference +title: Configure a machine with the PowerShell adapter +--- + +This example shows how to use the `Microsoft.Adapter/PowerShell` adapter to configure a machine +using multiple class-based PowerShell DSC resources in a single configuration document. These +examples use the `Microsoft.WinGet.DSC/WinGetPackage` resource from the **Microsoft.WinGet.DSC** +module to ensure several packages are installed. + +> [!NOTE] +> Run this example with `dsc.exe` version 3.2.0 or later and the **Microsoft.WinGet.DSC** +> PowerShell module installed. Install the module with: +> `Install-PSResource Microsoft.WinGet.DSC` + +## Configuration document + +The following configuration document defines multiple `Microsoft.WinGet.DSC/WinGetPackage` +instances. Each instance sets `directives.requireAdapter` to `Microsoft.Adapter/PowerShell`. + +Save the following YAML as `dev-tools.dsc.yaml`: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + ensureTools: + type: string + defaultValue: Present + allowedValues: + - Present + - Absent +resources: +- name: PowerShell 7 + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: Microsoft.PowerShell + Ensure: "[parameters('ensureTools')]" +- name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: Microsoft.WindowsTerminal + Ensure: "[parameters('ensureTools')]" +- name: Visual Studio Code + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: Microsoft.VisualStudioCode + Ensure: "[parameters('ensureTools')]" +``` + +## Test the configuration + +Run the configuration test to check whether the packages are installed: + +```powershell +dsc config test --file dev-tools.dsc.yaml +``` + +DSC reports the results for each instance, showing which packages need to be installed. + +## Apply the configuration + +Run the configuration set to install any packages that aren't already present: + +```powershell +dsc config set --file dev-tools.dsc.yaml +``` + +## Remove the packages + +To uninstall the packages, override the `ensureTools` parameter when applying the configuration: + +```powershell +dsc config set --file dev-tools.dsc.yaml --parameters '{"ensureTools": "Absent"}' +``` + + +[01]: ../../../../../../cli/config/test.md +[02]: ../../../../../../cli/config/set.md diff --git a/docs/reference/resources/Microsoft/adapter/powershell/examples/invoke-a-resource.md b/docs/reference/resources/Microsoft/adapter/powershell/examples/invoke-a-resource.md new file mode 100644 index 000000000..0e52a7474 --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/powershell/examples/invoke-a-resource.md @@ -0,0 +1,117 @@ +--- +description: > + Example showing how to invoke a class-based PowerShell DSC resource using + Microsoft.Adapter/PowerShell in a DSC configuration document. +ms.date: 03/23/2026 +ms.topic: reference +title: Invoke a resource with the PowerShell adapter +--- + +This example shows how to use the `Microsoft.Adapter/PowerShell` adapter to invoke a class-based +PowerShell DSC resource. These examples use the `Microsoft.WinGet.DSC/WinGetPackage` resource from +the **Microsoft.WinGet.DSC** module to check whether Windows Terminal is installed. + +> [!NOTE] +> Run this example with `dsc.exe` version 3.2.0 or later and the **Microsoft.WinGet.DSC** +> PowerShell module installed. Install the module with: +> `Install-PSResource Microsoft.WinGet.DSC` + +## Test whether a WinGet package is installed + +The following configuration document defines a single `Microsoft.WinGet.DSC/WinGetPackage` +instance that uses `directives.requireAdapter` to route the resource through the +`Microsoft.Adapter/PowerShell` adapter. + +Save the following YAML as `winget-test.dsc.yaml`: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: Microsoft.WindowsTerminal + Ensure: Present +``` + +Run the configuration test operation to check whether Windows Terminal is installed: + +```powershell +dsc config test --file winget-test.dsc.yaml +``` + +When the package isn't installed, DSC returns the following result: + +```yaml +metadata: + Microsoft.DSC: + version: 3.2.0 + operation: test + executionType: actual + startDatetime: '2026-03-23T00:00:00.000000000+00:00' + endDatetime: '2026-03-23T00:00:01.000000000+00:00' + duration: PT1S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT0.5S + name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + result: + desiredState: + Id: Microsoft.WindowsTerminal + Ensure: Present + actualState: + Id: Microsoft.WindowsTerminal + Ensure: Absent + inDesiredState: false + differingProperties: + - Ensure +messages: [] +hadErrors: false +``` + +The `inDesiredState` field is `false` and `differingProperties` shows that `Ensure` differs between +the desired state and the actual state. + +## Install a WinGet package + +Use the `dsc config set` command to configure the system to the desired state: + +```powershell +dsc config set --file winget-test.dsc.yaml +``` + +When the resource installs the package, DSC returns the following result: + +```yaml +metadata: + Microsoft.DSC: + version: 3.2.0 + operation: set + executionType: actual + startDatetime: '2026-03-23T00:00:00.000000000+00:00' + endDatetime: '2026-03-23T00:00:05.000000000+00:00' + duration: PT5S + securityContext: restricted +results: +- metadata: + Microsoft.DSC: + duration: PT4S + name: Windows Terminal + type: Microsoft.WinGet.DSC/WinGetPackage + result: + beforeState: + Id: Microsoft.WindowsTerminal + Ensure: Absent + afterState: + Id: Microsoft.WindowsTerminal + Ensure: Present + changedProperties: + - Ensure +messages: [] +hadErrors: false +``` diff --git a/docs/reference/resources/Microsoft/adapter/powershell/index.md b/docs/reference/resources/Microsoft/adapter/powershell/index.md new file mode 100644 index 000000000..2eb622235 --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/powershell/index.md @@ -0,0 +1,187 @@ +--- +description: Microsoft.Adapter/PowerShell resource adapter reference documentation +ms.date: 03/23/2026 +ms.topic: reference +title: Microsoft.Adapter/PowerShell +--- + +# Microsoft.Adapter/PowerShell + +## Synopsis + +Adapter for resources implemented as PowerShell DSC classes. + +## Metadata + +```yaml +Version: 0.1.0 +Kind: adapter +Tags: [linux, windows, macos, pwsh, powershell] +Executable: pwsh +MinimumDSCVersion: 3.2.0 +``` + +## Instance definition syntax + +> [!NOTE] +> The `directives.requireAdapter` syntax is available in DSC 3.2 and later. + +```yaml +resources: +- name: + type: / + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: # adapted resource properties +``` + +## Description + +The `Microsoft.Adapter/PowerShell` adapter resource enables you to use PowerShell Desired State +Configuration (PSDSC) resources in DSC. The adapter discovers and invokes PSDSC resources +implemented as PowerShell classes. + +The adapter manages the PSDSC resources in PowerShell (pwsh), not Windows PowerShell. To use +MOF-based PSDSC resources or PSDSC resources that require Windows PowerShell, use the +[Microsoft.Adapter/WindowsPowerShell](../windowspowershell/index.md) adapter. + +This adapter doesn't use the **PSDesiredStateConfiguration** module. You don't need to install the +**PSDesiredStateConfiguration** module to use PSDSC resources in DSC through this adapter. + +> [!NOTE] +> This adapter replaces the deprecated [Microsoft.DSC/PowerShell](../../DSC/PowerShell/index.md) +> adapter. In earlier versions of DSC, adapted resources were nested inside a parent adapter +> resource using the `properties.resources` array. Starting in DSC 3.2, each adapted resource is +> listed directly in the configuration document's `resources` array with `directives.requireAdapter` +> set to `Microsoft.Adapter/PowerShell`. + +### PowerShell resource adapter cache + +The process for discovering the PowerShell resources available to the adapter can be +time-consuming. To improve performance, the adapter caches PowerShell resources and modules during +discovery. If the cache doesn't exist during discovery, the adapter creates it. + +The location of the cache depends on your operating system. The following table defines the path +for each platform. + +| Platform | Path | +| :------: | :----------------------------------------| +| Linux | `$HOME/.dsc/PSAdapterCache.json` | +| macOS | `$HOME/.dsc/PSAdapterCache.json` | +| Windows | `%LOCALAPPDATA%\dsc\PSAdapterCache.json` | + +The adapter versions the cache. The current version is `2`. If the version of the cache on a +machine differs from the current version, the adapter refreshes the cache. + +The adapter checks whether the cache is stale on each run and refreshes it if: + +- The `PSModulePath` environmental variable is updated. +- Any module is added or removed from the `PSModulePath`. +- Any related file in a cached PSDSC resource module has been updated since the cache was written. + The adapter watches the `LastWriteTime` property of module files with the following extensions: + `.ps1`, `.psd1`, and `.psm1`. + +You can directly call the adapter script to clear the cache with the **Operation** parameter value +set to `ClearCache`: + +```powershell +$adapterScript = dsc resource list -a Microsoft.Adapter/PowerShell | + ConvertFrom-Json | + Select-Object -ExpandProperty directory | + Join-Path -ChildPath 'psDscAdapter' -AdditionalChildPath 'powershell.resource.ps1' + +& $adapterScript -Operation ClearCache +``` + +## Requirements + +- Using this adapter requires a supported version of PowerShell. DSC invokes the adapter as a + PowerShell script. For more information about installing PowerShell, see + [Install PowerShell on Windows, Linux, and macOS](/powershell/scripting/install/installing-powershell). + +## Examples + +- [Invoke a resource with the PowerShell adapter][02] +- [Configure a machine with the PowerShell adapter][03] + +## Adapted resource instances + +Adapted resource instances are listed directly in the configuration document's `resources` array. +Set `directives.requireAdapter` to `Microsoft.Adapter/PowerShell` to indicate that DSC should use +this adapter to invoke the instance. This feature requires DSC 3.2 or later. + +Every adapted instance must be an object that defines the [name](#adapted-instance-name), +[type](#adapted-instance-type), and [properties](#adapted-instance-properties) for the +instance. + +### Adapted instance name + +The `name` property of the adapted resource instance defines the short, human-readable name for the +instance. The adapted instance name must be a non-empty string containing only letters, numbers, +and spaces. This property must be unique within the configuration document's `resources` array. + +```yaml +PropertyName: name +Type: string +Required: true +MinimumLength: 1 +Pattern: ^[a-zA-Z0-9 ]+$ +``` + +### Adapted instance type + +The `type` property identifies the adapted instance's PSDSC resource. The value for this property +must be the valid fully qualified type name for the resource. + +This adapter uses the following syntax for determining the fully qualified type name of a PSDSC +resource implemented as a PowerShell class: + +```Syntax +/ +``` + +For example, if a PowerShell module named **TailspinToys** has a class-based PSDSC resource named +`TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`. + +For more information about type names in DSC, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### Adapted instance properties + +The `properties` of an adapted resource instance define its desired state. The value of this +property must be an object. The specified properties are validated at runtime when the adapter +tries to invoke the adapted PSDSC resource instance. This adapter doesn't support static linting +for adapted instance properties in a configuration document. + +Each name for each property must be a configurable property of the PSDSC resource. The property +name isn't case sensitive. The value for each property must be valid for that property. If you +specify an invalid property name or value, the adapter raises an error when it tries to invoke the +resource. + +```yaml +Type: object +Required: true +``` + +## Exit codes + +The resource uses the following exit codes to report success and errors: + +- `0` - Success +- `1` - Error + +## See also + +- [Microsoft.Adapter/WindowsPowerShell](../windowspowershell/index.md) +- [Microsoft.DSC/PowerShell](../../DSC/PowerShell/index.md) (deprecated) + + +[01]: ../../../../concepts/type-names.md +[02]: examples/invoke-a-resource.md +[03]: examples/configure-a-machine.md diff --git a/docs/reference/resources/Microsoft/adapter/windowspowershell/examples/manage-a-windows-service.md b/docs/reference/resources/Microsoft/adapter/windowspowershell/examples/manage-a-windows-service.md new file mode 100644 index 000000000..9e00bef2d --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/windowspowershell/examples/manage-a-windows-service.md @@ -0,0 +1,161 @@ +--- +description: > + Example showing how to manage a Windows service using the PSDesiredStateConfiguration module + with the Microsoft.Adapter/WindowsPowerShell adapter in a DSC configuration document. + +ms.date: 03/23/2026 +ms.topic: reference +title: Manage a Windows service +--- + +This example shows how to use the `Microsoft.Adapter/WindowsPowerShell` adapter with the +`PSDesiredStateConfiguration/Service` resource to manage a Windows service. These examples manage +the `Spooler` print spooler service. + +> [!NOTE] +> Run this example in an elevated PowerShell session with `dsc.exe` version 3.2.0 or later. + +## Test whether a service is running + +The following configuration document defines a single `PSDesiredStateConfiguration/Service` +instance that uses `directives.requireAdapter` to route the resource through the +`Microsoft.Adapter/WindowsPowerShell` adapter. + +Save the following YAML as `spooler.dsc.yaml`: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +metadata: + Microsoft.DSC: + securityContext: elevated +resources: +- name: Spooler service + type: PSDesiredStateConfiguration/Service + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: + Name: Spooler + StartupType: Automatic +``` + +Run the configuration test to check whether the service has the desired startup type: + +```powershell +dsc config test --file spooler.dsc.yaml +``` + +When the service has a different startup type, DSC returns the following result: + +```yaml +metadata: + Microsoft.DSC: + version: 3.2.0 + operation: test + executionType: actual + startDatetime: '2026-03-23T00:00:00.000000000+00:00' + endDatetime: '2026-03-23T00:00:01.000000000+00:00' + duration: PT1S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT0.5S + name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + desiredState: + Name: Spooler + StartupType: Automatic + actualState: + InDesiredState: false + inDesiredState: false + differingProperties: + - StartupType +messages: [] +hadErrors: false +``` + +The `inDesiredState` field is `false` and `differingProperties` shows that `StartupType` differs. + +## Ensure a service is running with automatic startup + +Use the `dsc config set` command to configure the service: + +```powershell +dsc config set --file spooler.dsc.yaml +``` + +When the resource configures the service, DSC returns the following result: + +```yaml +metadata: + Microsoft.DSC: + version: 3.2.0 + operation: set + executionType: actual + startDatetime: '2026-03-23T00:00:00.000000000+00:00' + endDatetime: '2026-03-23T00:00:02.000000000+00:00' + duration: PT2S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT1S + name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + beforeState: + Name: Spooler + StartupType: Manual + State: Running + afterState: + Name: Spooler + StartupType: Automatic + State: Running + changedProperties: + - StartupType +messages: [] +hadErrors: false +``` + +Run the test again to confirm the service is now configured correctly: + +```powershell +dsc config test --file spooler.dsc.yaml +``` + +```yaml +results: +- name: Spooler service + type: PSDesiredStateConfiguration/Service + result: + desiredState: + Name: Spooler + StartupType: Automatic + actualState: + InDesiredState: true + inDesiredState: true + differingProperties: [] +``` + +## Stop a service + +To stop the service and set startup type to manual, update the configuration document: + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +metadata: + Microsoft.DSC: + securityContext: elevated +resources: +- name: Spooler service stopped + type: PSDesiredStateConfiguration/Service + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: + Name: Spooler + State: Stopped + StartupType: Manual +``` + +Apply the configuration with `dsc config set` to stop the service. diff --git a/docs/reference/resources/Microsoft/adapter/windowspowershell/index.md b/docs/reference/resources/Microsoft/adapter/windowspowershell/index.md new file mode 100644 index 000000000..9ec0bcba1 --- /dev/null +++ b/docs/reference/resources/Microsoft/adapter/windowspowershell/index.md @@ -0,0 +1,211 @@ +--- +description: Microsoft.Adapter/WindowsPowerShell resource adapter reference documentation +ms.date: 03/23/2026 +ms.topic: reference +title: Microsoft.Adapter/WindowsPowerShell +--- + +# Microsoft.Adapter/WindowsPowerShell + +## Synopsis + +Adapter for resources implemented as binary, script, or PowerShell classes in Windows PowerShell. + +## Metadata + +```yaml +Version: 0.1.0 +Kind: adapter +Tags: [windows, powershell] +Executable: powershell +``` + +## Instance definition syntax + +> [!NOTE] +> The `directives.requireAdapter` syntax is available in DSC 3.2 and later. + +```yaml +resources: +- name: + type: / + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: # adapted resource properties +``` + +## Description + +The `Microsoft.Adapter/WindowsPowerShell` adapter resource enables you to use PowerShell Desired +State Configuration (PSDSC) resources in DSC. The resource can: + +- Execute script-based DSC resources +- Run class-based DSC resource methods +- Execute binary DSC resources + +The adapter manages the PSDSC resources in Windows PowerShell (powershell.exe), not PowerShell +(pwsh). To use class-based PSDSC resources in PowerShell, use the +[Microsoft.Adapter/PowerShell](../powershell/index.md) adapter. + +This adapter uses the **PSDesiredStateConfiguration** module v1.1. This module is built-in when +you install Windows and is located in +`%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules`. + +> [!NOTE] +> This adapter replaces the deprecated +> [Microsoft.Windows/WindowsPowerShell](../../Windows/WindowsPowerShell/index.md) adapter. In +> earlier versions of DSC, adapted resources were nested inside a parent adapter resource using +> the `properties.resources` array. Starting in DSC 3.2, each adapted resource is listed directly +> in the configuration document's `resources` array with `directives.requireAdapter` set to +> `Microsoft.Adapter/WindowsPowerShell`. + +### PowerShell resource adapter cache + +The process for discovering the Windows PowerShell resources available to the adapter can be +time-consuming. To improve performance, the adapter caches Windows PowerShell resources and modules +during discovery. If the cache doesn't exist during discovery, the adapter creates it. + +The following table defines the cache path for the Windows platform. + +| Platform | Path | +| :------: | :---------------------------------------------- | +| Windows | `%LOCALAPPDATA%\dsc\WindowsPSAdapterCache.json` | + +The adapter versions the cache. The current version is `1`. If the version of the cache on a +machine differs from the current version, the adapter refreshes the cache. + +The adapter checks whether the cache is stale on each run and refreshes it if: + +- The `PSModulePath` environmental variable is updated. +- Any module is added or removed from the `PSModulePath`. +- Any related file in a cached PSDSC resource module has been updated since the cache was written. + The adapter watches the `LastWriteTime` property of module files with the following extensions: + `.ps1`, `.psd1`, and `.psm1`. + +You can directly call the adapter script to clear the cache with the **Operation** parameter value +set to `ClearCache`: + +```powershell +$adapterScript = dsc resource list Microsoft.Adapter/WindowsPowerShell | + ConvertFrom-Json | + Select-Object -ExpandProperty directory | + Join-Path -ChildPath 'psDscAdapter\powershell.resource.ps1' + +& $adapterScript -Operation ClearCache +``` + +## Requirements + +- This adapter is only available on Windows. +- The process context must have appropriate permissions for the DSC resources to be executed. +- PowerShell modules exposing DSC resources should be installed in one of the following locations: + - `%PROGRAMFILES%\WindowsPowerShell\Modules` + - `%SystemRoot%\System32\WindowsPowerShell\v1.0\Modules` + +## Capabilities + +The resource adapter has the following capabilities: + +- `get` - Retrieve the actual state of a DSC resource instance. +- `set` - Enforce the desired state for a DSC resource instance. +- `test` - Determine whether a DSC resource instance is in the desired state. +- `export` - Discover and enumerate DSC resource instances available on the system. +- `list` - List available Windows PowerShell DSC resources that can be used with `dsc.exe`. + +> [!NOTE] +> The `export` capability is only available with class-based DSC resources. Script-based and +> binary DSC resources don't support the export operation. + +## Examples + +- [Manage a Windows service with the WindowsPowerShell adapter][02] + +## Adapted resource instances + +Adapted resource instances are listed directly in the configuration document's `resources` array. +Set `directives.requireAdapter` to `Microsoft.Adapter/WindowsPowerShell` to indicate that DSC +should use this adapter to invoke the instance. This feature requires DSC 3.2 or later. + +Every adapted instance must be an object that defines the [name](#adapted-instance-name), +[type](#adapted-instance-type), and [properties](#adapted-instance-properties) for the instance. + +### Adapted instance name + +The `name` property of the adapted resource instance defines the short, human-readable name for the +instance. The adapted instance name must be a non-empty string containing only letters, numbers, +and spaces. This property must be unique within the configuration document's `resources` array. + +```yaml +PropertyName: name +Type: string +Required: true +MinimumLength: 1 +Pattern: ^[a-zA-Z0-9 ]+$ +``` + +### Adapted instance type + +The `type` property identifies the adapted instance's PSDSC resource. The value for this property +must be the valid fully qualified type name for the resource. + +This adapter uses the following syntax for determining the fully qualified type name of a PSDSC +resource: + +```Syntax +/ +``` + +For example, if a PowerShell module named **TailspinToys** has a script-based PSDSC resource named +`TSToy`, the fully qualified type name for that resource is `TailspinToys/TSToy`. + +For more information about type names in DSC, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### Adapted instance properties + +The `properties` of an adapted resource instance define its desired state. The value of this +property must be an object. The specified properties are validated at runtime when the adapter +tries to invoke the adapted PSDSC resource instance. This adapter doesn't support static linting +for adapted instance properties in a configuration document. + +Each name for each property must be a configurable property of the PSDSC resource. The property +name isn't case sensitive. The value for each property must be valid for that property. If you +specify an invalid property name or value, the adapter raises an error when it tries to invoke the +resource. + +```yaml +Type: object +Required: true +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed because the underlying DSC resource method or +`Invoke-DscResource` call did not succeed. When the resource returns this exit code, it also emits +an error message with details about the failure. + +## See also + +- [Microsoft.Adapter/PowerShell](../powershell/index.md) +- [Microsoft.Windows/WindowsPowerShell](../../Windows/WindowsPowerShell/index.md) (deprecated) + + +[01]: ../../../../concepts/type-names.md +[02]: examples/manage-a-windows-service.md diff --git a/docs/reference/resources/overview.md b/docs/reference/resources/overview.md index 050999f1b..7e3e7e5eb 100644 --- a/docs/reference/resources/overview.md +++ b/docs/reference/resources/overview.md @@ -9,6 +9,8 @@ This document lists the available resources and links to the reference documenta - [Microsoft.DSC/Assertion](./microsoft/dsc/assertion/resource.md) - [Microsoft.DSC/Group](./microsoft/dsc/group/resource.md) - [Microsoft.DSC/Include](./microsoft/dsc/include/resource.md) +- [Microsoft.Adapter/PowerShell](./microsoft/adapter/powershell/index.md) +- [Microsoft.Adapter/WindowsPowerShell](./microsoft/adapter/windowspowershell/index.md) - [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/resource.md) - [Microsoft.DSC.Debug/Echo](./microsoft/dsc/debug/echo/resource.md) - [Microsoft.DSC.Transitional/RunCommandOnSet](./microsoft/dsc/transitional/runcomandonset/resource.md) @@ -31,10 +33,17 @@ change the state of the machine directly: You can use the following built-in resources to leverage resources that don't define a DSC Resource Manifest: -- [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/resource.md) -- [Microsoft.Windows/WindowsPowerSHell](./microsoft/windows/windowspowershell/resource.md) +- [Microsoft.Adapter/PowerShell](./microsoft/adapter/powershell/index.md) +- [Microsoft.Adapter/WindowsPowerShell](./microsoft/adapter/windowspowershell/index.md) +- [Microsoft.DSC/PowerShell](./microsoft/dsc/powershell/index.md) +- [Microsoft.Windows/WindowsPowerShell](./microsoft/windows/windowspowershell/index.md) - [Microsoft.Windows/WMI](./microsoft/windows/wmi/resource.md) +> [!WARNING] +> `Microsoft.DSC/PowerShell` and `Microsoft.Windows/WindowsPowerShell` will be deprecated in a +> future release. Use `Microsoft.Adapter/PowerShell` and `Microsoft.Adapter/WindowsPowerShell` +> instead. + ## Built-in configurable resources The following built-in resources to change the state of a machine directly: diff --git a/dsc/examples/groups.dsc.yaml b/dsc/examples/groups.dsc.yaml index 0e5d2085e..a0e96f2a3 100644 --- a/dsc/examples/groups.dsc.yaml +++ b/dsc/examples/groups.dsc.yaml @@ -2,7 +2,7 @@ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json metadata: Microsoft.DSC: - requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins + securityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins resources: - name: Last Group type: Microsoft.DSC/Group diff --git a/dsc/examples/multiline.dsc.yaml b/dsc/examples/multiline.dsc.yaml index 41122ee95..aa2cb78d5 100644 --- a/dsc/examples/multiline.dsc.yaml +++ b/dsc/examples/multiline.dsc.yaml @@ -1,13 +1,13 @@ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: -- name: test multi-line +- name: test multiline type: Microsoft.DSC.Debug/Echo properties: output: | This is a 'multi-line' string. -- name: test single-quote escaping +- name: test single quote escaping type: Microsoft.DSC.Debug/Echo properties: output: "[concat('This is a single-quote: ', '''')]" diff --git a/dsc/examples/parallel.dsc.yaml b/dsc/examples/parallel.dsc.yaml deleted file mode 100644 index b88ea83bc..000000000 --- a/dsc/examples/parallel.dsc.yaml +++ /dev/null @@ -1,47 +0,0 @@ -# Example on how concurrency would be defined in the configuration. -$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json -metadata: - _timeoutSeconds: 600 # example of setting timeout for orchestration, should be namespaced? -resources: -- name: myParallelGroup - type: DSC/ParallelGroup # each resource in this group would run in parallel - properties: - resources: - - name: os - type: Microsoft/OSInfo - properties: {} - - name: windows product name - type: Microsoft.Windows/Registry - properties: - keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion - valueName: ProductName - - name: system root - type: Microsoft.Windows/Registry - properties: - keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion - valueName: SystemRoot -- name: myGroup - type: Microsoft.DSC/Group # each resource in this group would run in sequence - properties: - resources: - - name: current user registry - type: Microsoft.Windows/Registry - properties: - keyPath: HKCU\example - _ensure: present - - name: current user registry 2 - type: Microsoft.Windows/Registry - properties: - keyPath: HKCU\example2 - _ensure: present - - name: mygroup - type: Microsoft.DSC/Group - properties: - resources: - - name: myreg - type: Microsoft.Windows.Registry - properties: - keyPath: HKCU\example2 - _ensure: absent - dependsOn: - - '[DSC/ParallelGroup]myParallelGroup' diff --git a/dsc/examples/timezone.dsc.yaml b/dsc/examples/timezone.dsc.yaml index b09fdf137..40ee0946e 100644 --- a/dsc/examples/timezone.dsc.yaml +++ b/dsc/examples/timezone.dsc.yaml @@ -3,12 +3,10 @@ $schema: https://aka.ms/dsc/schemas/v3.0.0/bundled/config/document.json resources: - - type: Microsoft.Windows/WindowsPowerShell + - type: ComputerManagementDsc/TimeZone name: Set Timezone + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell properties: - resources: - - name: Set Timezone - type: ComputerManagementDsc/TimeZone - properties: - IsSingleInstance: Yes - TimeZone: New Zealand Standard Time + IsSingleInstance: Yes + TimeZone: New Zealand Standard Time diff --git a/dsc/examples/winget.dsc.yaml b/dsc/examples/winget.dsc.yaml index 8e3357e7f..40f93a5e7 100644 --- a/dsc/examples/winget.dsc.yaml +++ b/dsc/examples/winget.dsc.yaml @@ -1,4 +1,4 @@ -# The `Microsoft.Winget.DSC` resources needs to be installed: install-psresource Microsoft.Winget.DSC -Prerelease +# The `Microsoft.Winget.DSC` resources needs to be installed: Install-PSResource Microsoft.Winget.DSC $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json parameters: @@ -9,16 +9,16 @@ parameters: - Present - Absent resources: -- name: Use class PowerShell resources - type: Microsoft.DSC/PowerShell +- name: PowerShell 7 Preview + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell properties: - resources: - - name: PowerShell 7 Preview - type: Microsoft.WinGet.DSC/WinGetPackage - properties: - Id: Microsoft.PowerShell.Preview - - name: Calc from Windows Store - type: Microsoft.WinGet.DSC/WinGetPackage - properties: - Id: "9WZDNCRFHVN5" - Ensure: "[parameters('ensureCalc')]" + Id: Microsoft.PowerShell.Preview +- name: Calc from Windows Store + type: Microsoft.WinGet.DSC/WinGetPackage + directives: + requireAdapter: Microsoft.Adapter/PowerShell + properties: + Id: "9WZDNCRFHVN5" + Ensure: "[parameters('ensureCalc')]" diff --git a/dsc/examples/winps_script.dsc.yaml b/dsc/examples/winps_script.dsc.yaml index 34a34359a..1b6147838 100644 --- a/dsc/examples/winps_script.dsc.yaml +++ b/dsc/examples/winps_script.dsc.yaml @@ -3,23 +3,21 @@ metadata: Microsoft.DSC: securityContext: elevated resources: - - type: Microsoft.Windows/WindowsPowerShell + - type: PSDesiredStateConfiguration/Script name: Run WinPS script - properties: - resources: - - name: Run script - type: PSDesiredStateConfiguration/Script - properties: - GetScript: | - $text = @" - get - "@ - # Returning result must be this type of hashtable - @{Result=$text} - TestScript: | - # TestScript must return a boolean - $true - SetScript: | - $text = @" - set - "@ + directives: + requireAdapter: Microsoft.Adapter/WindowsPowerShell + properties: + GetScript: | + $text = @" + get + "@ + # Returning result must be this type of hashtable + @{Result=$text} + TestScript: | + # TestScript must return a boolean + $true + SetScript: | + $text = @" + set + "@ From 51ccc6e6c2525eaefa3eb322c20d952f4e2bca02 Mon Sep 17 00:00:00 2001 From: "G.Reijn" Date: Mon, 23 Mar 2026 01:49:32 +0100 Subject: [PATCH 2/2] Revert group change --- dsc/examples/groups.dsc.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dsc/examples/groups.dsc.yaml b/dsc/examples/groups.dsc.yaml index a0e96f2a3..a2ab9c107 100644 --- a/dsc/examples/groups.dsc.yaml +++ b/dsc/examples/groups.dsc.yaml @@ -2,7 +2,7 @@ $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json metadata: Microsoft.DSC: - securityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins + requiredSecurityContext: current # this is the default and just used as an example indicating this config works for admins and non-admins resources: - name: Last Group type: Microsoft.DSC/Group @@ -38,4 +38,4 @@ resources: - name: Nested First type: Microsoft.DSC.Debug/Echo properties: - output: Nested First + output: Nested First \ No newline at end of file