Edit

Manage PowerShell packages with Microsoft DSC

Beginning with version 1.3.0-preview1, the Microsoft.PowerShell.PSResourceGet module ships two Microsoft Desired State Configuration (DSC) v3 resources. You can use the resources to declare which package repositories a machine should have registered and which PowerShell packages should be installed from them. DSC then compares that declaration with the actual state of the machine and installs, updates, or removes packages to match.

The resources are command-based DSC resources. They run in PowerShell 7 and call the same cmdlets you use interactively, such as Register-PSResourceRepository and Install-PSResource.

Available resources

The Microsoft.PowerShell.PSResourceGet/Repository resource manages a registered package repository: name, URI, trust, priority, and API type. This resource supports the get, set, delete, and export operations.

The Microsoft.PowerShell.PSResourceGet/PSResourceList resource manages a list of packages that should, or shouldn't, be installed from one repository. This resource supports the get, set, test, export, and whatIf operations.

For more information about what each operation does, see DSC resource operations.

Choose how to use the resources

You can use the resources in two ways:

  • Invoke a resource directly with the dsc resource commands. Use this approach to inspect the state of a single repository or package list, to try a resource before adding it to a configuration, or to script a one-off change. For more information, see Invoke the PSResourceGet DSC resources directly.
  • Declare the resources in a configuration document and apply the document with the dsc config commands. Use this approach to describe the complete package state of a machine, combine the resources with other DSC resources, and preview changes with --what-if. For more information, see Manage packages with a DSC configuration document.

Any tool that hosts DSC v3 can also use the resources. For example, you can reference the resource types from a WinGet configuration file that uses the dscv3 processor.

Prerequisites

  • PowerShell 7.2 or later. The resources run in pwsh, which must be discoverable through the PATH environment variable. Windows PowerShell 5.1 isn't supported.

  • Microsoft.PowerShell.PSResourceGet 1.3.0-preview1 or later. Install the module from the PowerShell Gallery:

    Install-PSResource -Name Microsoft.PowerShell.PSResourceGet -Prerelease

    For more information, see Install a package manager for PowerShell.

  • Microsoft DSC 3.2 or later. DSC 3.2 added the discovery extension that finds resources packaged in PowerShell modules. For installation instructions, see Install DSC.

How DSC discovers the resources

You don't need to add the module folder to the PATH environment variable. DSC ships an extension, Microsoft.PowerShell/Discover, that searches the folders in the $env:PSModulePath environment variable for DSC resource manifests. Because Install-PSResource installs the module to a folder in $env:PSModulePath, DSC finds the resources as soon as you install the module.

The resource manifests and the script that implements the resources are stored in the root of the module folder:

Microsoft.PowerShell.PSResourceGet/
└── 1.3.0/
    ├── Microsoft.PowerShell.PSResourceGet.psd1
    ├── psresourceget.ps1
    ├── psresourcelist.dsc.resource.json
    └── repository.dsc.resource.json

Verify that DSC can find the resources:

dsc resource list Microsoft.PowerShell.PSResourceGet/*

Type                                               Kind      Version  Capabilities
----------------------------------------------------------------------------------
Microsoft.PowerShell.PSResourceGet/PSResourceList  Resource  0.0.1    gsw-t--e-
Microsoft.PowerShell.PSResourceGet/Repository      Resource  0.0.1    gs---d-e-

The Capabilities column shows g for get, s for set, w for whatIf, t for test, d for delete, and e for export. The preceding output omits the RequireAdapter and Description columns for readability.

If the command doesn't return the resources, check the following:

  • pwsh is discoverable through PATH. DSC only runs the discovery extension when it can find PowerShell 7. It skips the extension without reporting an error.

  • The installed version is 1.3.0-preview1 or later. Earlier versions don't include the resource manifests.

  • The module is installed for PowerShell 7. The extension ignores the Windows PowerShell module folders in $env:PSModulePath. Run the following command to confirm where the module is installed:

    Get-Module Microsoft.PowerShell.PSResourceGet -ListAvailable

To confirm that the extension is available, run dsc extension list. For more information, see dsc extension list.

Note

DSC runs the resources from the module folder that contains the manifest it discovered, not from the version of Microsoft.PowerShell.PSResourceGet imported in your session. When more than one installed version ships the resources, DSC lists the resource type once and doesn't guarantee which version it selects. Uninstall the versions you don't want DSC to use.

How the resources map to cmdlets

Operation on the resource Cmdlets the resource calls
Repository get and export Get-PSResourceRepository
Repository set Register-PSResourceRepository, Set-PSResourceRepository, Unregister-PSResourceRepository
Repository delete Unregister-PSResourceRepository
PSResourceList get, test, and export Get-PSResourceRepository, Get-InstalledPSResource
PSResourceList set Install-PSResource, Uninstall-PSResource

Because the resources call the cmdlets directly, they honor the same settings as an interactive session. For example, a repository that requires credentials must have a persisted credential configured before DSC can install from it. For more information, see How to add credentials to repositories with PSResourceGet.

See also

  • Last updated on