From 19d54243a77c22ef8bc7339ef025bf2f5a1a6db4 Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Sat, 12 Sep 2026 14:37:30 +0200 Subject: [PATCH 1/5] docs: Add DSC documentation for PSResourceGet --- .../dsc/how-to/configuration-documents.md | 515 ++++++++++++++++++ .../dsc/how-to/invoke-resources.md | 447 +++++++++++++++ .../powershellget/dsc/overview.md | 149 +++++ .../dsc/reference/psresourcelist.md | 453 +++++++++++++++ .../powershellget/dsc/reference/repository.md | 294 ++++++++++ .../docs-conceptual/powershellget/toc.yml | 16 + 6 files changed, 1874 insertions(+) create mode 100644 powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md create mode 100644 powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md create mode 100644 powershell-gallery/docs-conceptual/powershellget/dsc/overview.md create mode 100644 powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md create mode 100644 powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md new file mode 100644 index 0000000..e655c23 --- /dev/null +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md @@ -0,0 +1,515 @@ +--- +description: >- + Learn how to declare package repositories and PowerShell packages in a Microsoft DSC configuration + document and apply, test, preview, and export it with the dsc config commands. +ms.date: 09/12/2026 +ms.topic: how-to +title: Manage packages with a DSC configuration document +--- +# Manage packages with a DSC configuration document + +A DSC configuration document describes the desired state of a machine as a list of resource +instances. When you apply the document, the DSC engine invokes each resource in order, resolves +dependencies between instances, and reports the result for the document as a whole. This article +shows how to describe the repositories and packages a machine needs in a configuration document +and how to work with that document using the `dsc config` commands. + +## Prerequisites + +- Complete the steps in [Make the resources discoverable][01] so that `dsc resource list` + returns both resources. +- A text editor for YAML files. Visual Studio Code with the YAML extension validates the document + against the DSC schema while you type. + +## Write the configuration document + +The following document registers a private repository, installs packages from it, and installs +tooling from the PowerShell Gallery. Save it as `packages.dsc.yaml`. + +```yaml +# packages.dsc.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Contoso feed + type: Microsoft.PowerShell.PSResourceGet/Repository + properties: + name: ContosoModules + uri: https://pkgs.contoso.com/nuget/v3/index.json + trusted: true + priority: 40 + repositoryType: V3 + + - name: Contoso modules + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + dependsOn: + - "[resourceId('Microsoft.PowerShell.PSResourceGet/Repository', 'Contoso feed')]" + properties: + repositoryName: ContosoModules + resources: + - name: Contoso.Deployment + version: '[3.2.0, 4.0.0)' + - name: Contoso.Legacy + _exist: false + + - name: Tooling from the PowerShell Gallery + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + properties: + repositoryName: PSGallery + trustedRepository: true + resources: + - name: PSScriptAnalyzer + version: '[1.24.0]' + - name: Pester + version: '[5.0.0, )' + scope: AllUsers + - name: Microsoft.WinGet.Client + preRelease: true +``` + +The document shows several patterns: + +- **Register before you install.** The `dependsOn` entry tells DSC to process the **Repository** + instance before the **PSResourceList** instance that installs from it. Without the dependency, + DSC processes instances in document order, which works here but isn't guaranteed if you + reorder the document. For more information, see + [Configuration document resource dependencies][02]. +- **One list per repository.** Each **PSResourceList** instance manages the packages from a single + repository. Use one instance for each repository you install from. +- **Trust at the repository or at the list.** The Contoso repository is registered as trusted, so + its list doesn't need `trustedRepository`. The PowerShell Gallery keeps its default untrusted + setting, so the list that installs from it sets `trustedRepository` to `true`. +- **Pin, range, or latest.** `PSScriptAnalyzer` is pinned to an exact version, `Pester` accepts + any version from 5.0.0 onward, and `Microsoft.WinGet.Client` takes the latest + version including prereleases. For more information, see the [version][03] property. +- **Remove what shouldn't be there.** `Contoso.Legacy` has `_exist: false`, so DSC uninstalls it + if it's found. + +> [!NOTE] +> The `Pester` entry installs to the `AllUsers` scope, so `dsc` must run in an elevated process to +> apply this document. Remove the `scope` line to keep the whole document per user. + +## Test the document + +Use `dsc config test` to compare the document with the machine without changing anything. The +output reports the state of every instance and whether the document as a whole is in the desired +state. + +```powershell +dsc config test --file ./packages.dsc.yaml +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.1.0 + operation: test + executionType: actual + startDatetime: 2026-09-12T10:15:03.123456700+02:00 + endDatetime: 2026-09-12T10:15:09.987654300+02:00 + duration: PT6.864197600S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT1.2S + name: Contoso feed + type: Microsoft.PowerShell.PSResourceGet/Repository + result: + desiredState: + name: ContosoModules + uri: https://pkgs.contoso.com/nuget/v3/index.json + trusted: true + priority: 40 + repositoryType: V3 + actualState: + name: ContosoModules + uri: null + trusted: false + priority: 0 + repositoryType: Unknown + _exist: false + inDesiredState: false + differingProperties: + - uri + - trusted + - priority + - repositoryType +- metadata: + Microsoft.DSC: + duration: PT2.4S + name: Contoso modules + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + result: + desiredState: + repositoryName: ContosoModules + resources: + - name: Contoso.Deployment + version: '[3.2.0, 4.0.0)' + - name: Contoso.Legacy + _exist: false + actualState: + repositoryName: ContosoModules + resources: + - name: Contoso.Deployment + version: '[3.2.0, 4.0.0)' + scope: CurrentUser + repositoryName: ContosoModules + preRelease: false + _exist: true + _inDesiredState: false + - name: Contoso.Legacy + version: null + scope: CurrentUser + repositoryName: ContosoModules + preRelease: false + _exist: false + _inDesiredState: false + trustedRepository: false + _inDesiredState: false + inDesiredState: false + differingProperties: + - resources +- metadata: + Microsoft.DSC: + duration: PT3.1S + name: Tooling from the PowerShell Gallery + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + result: + desiredState: + repositoryName: PSGallery + trustedRepository: true + resources: + - name: PSScriptAnalyzer + version: '[1.24.0]' + - name: Pester + version: '[5.0.0, )' + scope: AllUsers + - name: Microsoft.WinGet.Client + preRelease: true + actualState: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: '[1.24.0]' + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + _inDesiredState: false + - name: Pester + version: '[5.0.0, )' + scope: AllUsers + repositoryName: PSGallery + preRelease: false + _exist: true + _inDesiredState: false + - name: Microsoft.WinGet.Client + version: null + scope: CurrentUser + repositoryName: PSGallery + preRelease: true + _exist: true + _inDesiredState: false + trustedRepository: false + _inDesiredState: false + inDesiredState: false + differingProperties: + - resources +messages: [] +hadErrors: false +``` + +> [!NOTE] +> When a **PSResourceList** instance isn't in the desired state, the `actualState` the resource +> returns for the **Test** operation echoes the entries you defined, with default values filled in, +> rather than the installed packages. The per-entry `_inDesiredState` value is always `false`. Use +> `dsc config get` to see which versions are installed. For more information, see the +> [_inDesiredState][11] property. + +The output is long. Convert the JSON output to objects to list only the instances that aren't in +the desired state: + +```powershell +$result = dsc config test --file ./packages.dsc.yaml -o json | ConvertFrom-Json + +$result.results | + Where-Object { -not $_.result.inDesiredState } | + Select-Object -Property name, type +``` + +```Output +name type +---- ---- +Contoso feed Microsoft.PowerShell.PSResourceGet/Repository +Contoso modules Microsoft.PowerShell.PSResourceGet/PSResourceList +Tooling from the PowerShell Gallery Microsoft.PowerShell.PSResourceGet/PSResourceList +``` + +## Preview the changes + +Before you apply a document, use the `--what-if` option to see what would change. The +**PSResourceList** resource implements what-if support, so the projected state includes a +`_metadata.whatIf` message for every package it would install or uninstall. Packages that are +already in the desired state are returned without metadata. Nothing is installed or removed. + +```powershell +dsc config set --file ./packages.dsc.yaml --what-if +``` + +```yaml +metadata: + Microsoft.DSC: + version: 3.1.0 + operation: set + executionType: whatIf + startDatetime: 2026-09-12T10:16:40.123456700+02:00 + endDatetime: 2026-09-12T10:16:47.987654300+02:00 + duration: PT7.864197600S + securityContext: elevated +results: +- metadata: + Microsoft.DSC: + duration: PT1.2S + name: Contoso feed + type: Microsoft.PowerShell.PSResourceGet/Repository + result: + beforeState: + name: ContosoModules + uri: null + trusted: false + priority: 0 + repositoryType: Unknown + _exist: false + afterState: + name: ContosoModules + uri: https://pkgs.contoso.com/nuget/v3/index.json + trusted: true + priority: 40 + repositoryType: V3 + changedProperties: + - uri + - trusted + - priority + - repositoryType +- metadata: + Microsoft.DSC: + duration: PT2.4S + name: Contoso modules + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + result: + beforeState: + repositoryName: ContosoModules + resources: + - name: Contoso.Deployment + version: null + scope: CurrentUser + repositoryName: null + preRelease: false + _exist: false + - name: Contoso.Legacy + version: null + scope: CurrentUser + repositoryName: null + preRelease: false + _exist: false + afterState: + repositoryName: ContosoModules + resources: + - name: Contoso.Deployment + version: '[3.2.0, 4.0.0)' + scope: CurrentUser + repositoryName: ContosoModules + preRelease: false + _exist: true + _metadata: + whatIf: + - Would install resource 'Contoso.Deployment' version '[3.2.0, 4.0.0)' + - name: Contoso.Legacy + version: null + scope: CurrentUser + repositoryName: null + preRelease: false + _exist: false + changedProperties: + - resources +- metadata: + Microsoft.DSC: + duration: PT3.1S + name: Tooling from the PowerShell Gallery + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + result: + beforeState: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: 1.24.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Pester + version: 5.7.1 + scope: AllUsers + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Microsoft.WinGet.Client + version: null + scope: CurrentUser + repositoryName: null + preRelease: false + _exist: false + afterState: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: 1.24.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Pester + version: 5.7.1 + scope: AllUsers + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Microsoft.WinGet.Client + version: latest + scope: CurrentUser + repositoryName: PSGallery + preRelease: true + _exist: true + _metadata: + whatIf: + - Would install resource 'Microsoft.WinGet.Client' version 'latest' + changedProperties: + - resources +messages: [] +hadErrors: false +``` + +The `Contoso.Legacy` entry isn't installed, so the resource returns it unchanged and without +metadata. If it were installed, the projected entry would have `_exist: false` and a +`Would uninstall resource 'Contoso.Legacy'` message. + +The **Repository** resource doesn't implement what-if support. For it, DSC synthesizes the result +from the **Get** operation and the desired state, which is why the entry has no `_metadata`. + +> [!NOTE] +> What-if support for the **PSResourceList** resource requires a version of DSC that recognizes the +> what-if definition in the resource manifest. On older versions of DSC, the engine synthesizes the +> result from the **Test** operation instead. The synthesized result still shows which instances +> would change, but doesn't include the `_metadata.whatIf` messages. + +## Apply the document + +Use `dsc config set` to enforce the document. DSC invokes the **Set** operation for every instance +that isn't in the desired state and reports the state before and after each change. + +```powershell +dsc config set --file ./packages.dsc.yaml +``` + +The command is idempotent. Run it again and the resources report no changes, because every +instance is already in the desired state. Run `dsc config test` at any time to detect drift, for +example after someone installs or removes a package interactively. + +If a **PSResourceList** instance fails to install a package, DSC stops processing the document and +reports the error. The `hadErrors` property in the output is `true`, and the `messages` property +contains the error the resource wrote. Fix the cause and apply the document again. Packages that +were installed before the failure stay installed and aren't reinstalled. For more information, see +the [PSResourceList exit codes][04]. + +## Capture the state of a machine + +Use `dsc config export` to build a configuration document from the machine you're on. The document +lists every registered repository and every installed package, grouped by repository. Use it as a +starting point for a document you can apply to other machines. + +```yaml +# export.dsc.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: + - name: Repositories + type: Microsoft.PowerShell.PSResourceGet/Repository + - name: Packages + type: Microsoft.PowerShell.PSResourceGet/PSResourceList +``` + +```powershell +dsc config export --file ./export.dsc.yaml | Out-File -FilePath ./machine.dsc.yaml +``` + +Before you apply the exported document elsewhere, review it: + +- Remove packages that shouldn't be managed, such as modules that ship with PowerShell. +- Decide how strict each `version` should be. The export records bare versions, which the + resource treats as minimum versions when it tests the machine and as exact versions when it + installs. Pin with `[]` or widen to a range as needed. +- Add `trustedRepository: true` to lists that install from untrusted repositories, or set + `trusted: true` on the corresponding **Repository** instance. + +## Use parameters for values that change per machine + +Configuration documents support parameters. Use them to keep repository URIs or package versions +out of the document body so that the same document works across environments. + +```yaml +# packages-parameterized.dsc.yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +parameters: + feedUri: + type: string + analyzerVersion: + type: string + defaultValue: '[1.24.0]' +resources: + - name: Contoso feed + type: Microsoft.PowerShell.PSResourceGet/Repository + properties: + name: ContosoModules + uri: "[parameters('feedUri')]" + trusted: true + - name: Tooling from the PowerShell Gallery + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + properties: + repositoryName: PSGallery + trustedRepository: true + resources: + - name: PSScriptAnalyzer + version: "[parameters('analyzerVersion')]" +``` + +```powershell +$parameters = @{ + parameters = @{ + feedUri = 'https://pkgs.contoso.com/nuget/v3/index.json' + } +} | ConvertTo-Json -Compress + +dsc config --parameters $parameters set --file ./packages-parameterized.dsc.yaml +``` + +For more information, see [DSC configuration document parameters][05]. + +## See also + +- [Invoke the PSResourceGet DSC resources directly][06] +- [Manage PowerShell packages with Microsoft DSC][07] +- [Microsoft.PowerShell.PSResourceGet/Repository][08] +- [Microsoft.PowerShell.PSResourceGet/PSResourceList][09] +- [dsc config command reference][10] + + +[01]: ../overview.md#make-the-resources-discoverable +[02]: /powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#dependson +[03]: ../reference/psresourcelist.md#version +[04]: ../reference/psresourcelist.md#exit-codes +[05]: /powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true +[06]: invoke-resources.md +[07]: ../overview.md +[08]: ../reference/repository.md +[09]: ../reference/psresourcelist.md +[10]: /powershell/dsc/reference/cli/config/index?view=dsc-3.0&preserve-view=true +[11]: ../reference/psresourcelist.md#_indesiredstate diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md new file mode 100644 index 0000000..2b6a0ee --- /dev/null +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md @@ -0,0 +1,447 @@ +--- +description: >- + Learn how to invoke the Microsoft.PowerShell.PSResourceGet DSC resources one at a time with the + dsc resource commands to inspect, test, change, and export repositories and packages. +ms.date: 09/12/2026 +ms.topic: how-to +title: Invoke the PSResourceGet DSC resources directly +--- +# Invoke the PSResourceGet DSC resources directly + +The `dsc resource` commands invoke a single DSC resource with the desired state you pass on the +command line. Use them to inspect what's on a machine, to check whether a machine already matches +what you want, or to make a change without writing a configuration document. This article shows +each operation the [Repository][01] and [PSResourceList][02] resources support. + +## Prerequisites + +- Complete the steps in [Make the resources discoverable][03] so that `dsc resource list` + returns both resources. +- Run the commands in PowerShell 7. The examples build the input JSON with hashtables and + `ConvertTo-Json`, which keeps the quoting readable. + +## Inspect a resource + +Use `dsc resource schema` to see the properties a resource accepts. The output is the JSON Schema +that DSC validates your input against. + +```powershell +dsc resource schema --resource Microsoft.PowerShell.PSResourceGet/PSResourceList +``` + +## Work with repositories + +### Get the state of a repository + +Pass the name of the repository to the **Get** operation. The resource returns the registered +settings, or `_exist: false` when no repository with that name is registered. + +```powershell +$type = 'Microsoft.PowerShell.PSResourceGet/Repository' +$instance = @{ name = 'PSGallery' } | ConvertTo-Json -Compress + +dsc resource get --resource $type --input $instance +``` + +```yaml +actualState: + name: PSGallery + uri: https://www.powershellgallery.com/api/v2 + trusted: false + priority: 50 + repositoryType: V2 + _exist: true +``` + +> [!NOTE] +> The **Get** operation requires input. Running the command without `--input` or `--file` exits +> with a non-zero code and an error that explains the `name` property is required. + +### Register or update a repository + +The **Set** operation registers the repository if it doesn't exist and updates it if it does. Only +the properties you define are changed. + +```powershell +$type = 'Microsoft.PowerShell.PSResourceGet/Repository' +$instance = @{ + name = 'ContosoModules' + uri = 'https://pkgs.contoso.com/nuget/v3/index.json' + trusted = $true + priority = 40 + repositoryType = 'V3' +} | ConvertTo-Json -Compress + +dsc resource set --resource $type --input $instance +``` + +```yaml +beforeState: + name: ContosoModules + uri: null + trusted: false + priority: 0 + repositoryType: Unknown + _exist: false +afterState: + name: ContosoModules + uri: https://pkgs.contoso.com/nuget/v3/index.json + trusted: true + priority: 40 + repositoryType: V3 + _exist: true +changedProperties: +- uri +- trusted +- priority +- repositoryType +- _exist +``` + +To change a single setting, such as trusting a repository you already registered, define `name`, +`uri`, and the property you want to change. + +```powershell +$type = 'Microsoft.PowerShell.PSResourceGet/Repository' +$instance = @{ + name = 'PSGallery' + uri = 'https://www.powershellgallery.com/api/v2' + trusted = $true +} | ConvertTo-Json -Compress + +dsc resource set --resource $type --input $instance +``` + +### Unregister a repository + +Use the **Delete** operation, or the **Set** operation with `_exist: false`, to unregister a +repository. Both operations succeed when the repository is already unregistered. + +```powershell +$type = 'Microsoft.PowerShell.PSResourceGet/Repository' +$instance = @{ name = 'ContosoModules'; _exist = $false } | ConvertTo-Json -Compress + +dsc resource delete --resource $type --input $instance +``` + +### Export the registered repositories + +The **Export** operation returns a configuration document that declares every registered +repository. Save the output to capture the repository setup of a machine so you can apply it to +another one. + +```powershell +dsc resource export --resource Microsoft.PowerShell.PSResourceGet/Repository | + Out-File -FilePath ./repositories.dsc.yaml +``` + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.PowerShell.PSResourceGet/Repository-0 + type: Microsoft.PowerShell.PSResourceGet/Repository + properties: + name: PSGallery + uri: https://www.powershellgallery.com/api/v2 + trusted: false + priority: 50 + repositoryType: V2 + _exist: true +- name: Microsoft.PowerShell.PSResourceGet/Repository-1 + type: Microsoft.PowerShell.PSResourceGet/Repository + properties: + name: MAR + uri: https://mcr.microsoft.com + trusted: true + priority: 40 + repositoryType: ContainerRegistry + _exist: true +``` + +## Work with packages + +Every **PSResourceList** operation takes the name of one repository and a list of packages. The +examples use the PowerShell Gallery, which is registered as `PSGallery` by default. + +### Get the installed state of packages + +The **Get** operation returns one entry for each package you list, in the same order. Installed +packages are returned with their installed version and scope. Packages that aren't installed are +returned with `_exist: false`. + +```powershell +$type = 'Microsoft.PowerShell.PSResourceGet/PSResourceList' +$instance = @{ + repositoryName = 'PSGallery' + resources = @( + @{ name = 'PSScriptAnalyzer' } + @{ name = 'Pester'; version = '[5.0.0, )' } + @{ name = 'Microsoft.PowerShell.PlatyPS' } + ) +} | ConvertTo-Json -Compress -Depth 3 + +dsc resource get --resource $type --input $instance +``` + +```yaml +actualState: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: 1.24.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Pester + version: 5.7.1 + scope: AllUsers + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Microsoft.PowerShell.PlatyPS + version: null + scope: CurrentUser + repositoryName: null + preRelease: false + _exist: false +``` + +When a package is installed but no installed version satisfies the `version` you asked for, the +resource returns the version it found and sets `_exist` to `false`. That tells you the package +needs to be updated rather than installed. For more information about how the resource interprets +`version`, see the [version][04] property. + +### Test whether packages are in the desired state + +The **Test** operation compares the list with the installed packages and reports the result in +`inDesiredState`. It doesn't change the machine. + +```powershell +$type = 'Microsoft.PowerShell.PSResourceGet/PSResourceList' +$instance = @{ + repositoryName = 'PSGallery' + resources = @( + @{ name = 'PSScriptAnalyzer'; version = '[1.24.0]' } + @{ name = 'Pester'; version = '[5.0.0, )' } + ) +} | ConvertTo-Json -Compress -Depth 3 + +dsc resource test --resource $type --input $instance +``` + +```yaml +desiredState: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: '[1.24.0]' + - name: Pester + version: '[5.0.0, )' +actualState: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: 1.24.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + _inDesiredState: false + - name: Pester + version: 5.7.1 + scope: AllUsers + repositoryName: PSGallery + preRelease: false + _exist: true + _inDesiredState: false + trustedRepository: false + _inDesiredState: true +inDesiredState: true +differingProperties: [] +``` + +Only the top-level `_inDesiredState` value is meaningful. The resource returns the property for +every entry as well, but always as `false`. When the list isn't in the desired state, the +`actualState` echoes the entries you defined rather than the installed packages. Use the **Get** +operation when you need the installed versions. For more information, see the +[_inDesiredState][08] property. + +### Install packages + +The **Set** operation installs every package in the list that isn't installed, or whose installed +version doesn't satisfy `version`. The PowerShell Gallery isn't trusted by default, so the example +sets `trustedRepository` to `true`. Without it, the operation fails with exit code `3`. + +```powershell +$type = 'Microsoft.PowerShell.PSResourceGet/PSResourceList' +$instance = @{ + repositoryName = 'PSGallery' + trustedRepository = $true + resources = @( + @{ name = 'PSScriptAnalyzer'; version = '[1.24.0]' } + @{ name = 'Microsoft.PowerShell.PlatyPS'; version = '[1.0.0, 2.0.0)' } + @{ name = 'Microsoft.WinGet.Client'; preRelease = $true } + ) +} | ConvertTo-Json -Compress -Depth 3 + +dsc resource set --resource $type --input $instance +``` + +```yaml +beforeState: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: 1.24.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Microsoft.PowerShell.PlatyPS + version: null + scope: CurrentUser + repositoryName: null + preRelease: false + _exist: false + - name: Microsoft.WinGet.Client + version: null + scope: CurrentUser + repositoryName: null + preRelease: false + _exist: false +afterState: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: 1.24.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Microsoft.PowerShell.PlatyPS + version: 1.0.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Microsoft.WinGet.Client + version: 1.11.400-beta + scope: CurrentUser + repositoryName: PSGallery + preRelease: true + _exist: true +changedProperties: +- resources +``` + +Packages that are already in the desired state, like `PSScriptAnalyzer` in the example, aren't +reinstalled. To install a package for every user on the machine, add `scope = 'AllUsers'` to its +entry and run `dsc` in an elevated process. + +### Uninstall packages + +Set `_exist` to `false` for a package to uninstall it. You can mix packages to install and packages +to uninstall in the same list. + +```powershell +$type = 'Microsoft.PowerShell.PSResourceGet/PSResourceList' +$instance = @{ + repositoryName = 'PSGallery' + resources = @( + @{ name = 'Microsoft.PowerShell.PlatyPS'; _exist = $false } + ) +} | ConvertTo-Json -Compress -Depth 3 + +dsc resource set --resource $type --input $instance +``` + +```yaml +beforeState: + repositoryName: PSGallery + resources: + - name: Microsoft.PowerShell.PlatyPS + version: 1.0.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true +afterState: + repositoryName: PSGallery + resources: + - name: Microsoft.PowerShell.PlatyPS + version: null + scope: CurrentUser + repositoryName: null + preRelease: false + _exist: false +changedProperties: +- resources +``` + +### Export the installed packages + +The **Export** operation returns a configuration document with one **PSResourceList** instance for +each repository that packages were installed from. The export includes packages installed for the +current user and for all users. + +```powershell +dsc resource export --resource Microsoft.PowerShell.PSResourceGet/PSResourceList | + Out-File -FilePath ./packages.dsc.yaml +``` + +```yaml +$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json +resources: +- name: Microsoft.PowerShell.PSResourceGet/PSResourceList-0 + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + properties: + repositoryName: PSGallery + resources: + - name: PSScriptAnalyzer + version: 1.24.0 + scope: CurrentUser + repositoryName: PSGallery + preRelease: false + _exist: true + - name: Pester + version: 5.7.1 + scope: AllUsers + repositoryName: PSGallery + preRelease: false + _exist: true +``` + +The exported versions are bare versions. Before you apply an exported document to another machine, +review the `version` values and decide whether to pin them with the `[]` syntax or to +relax them to a range. For more information, see the [version][04] property. + +## Troubleshoot + +- **DSC reports that the resource type isn't found.** The module folder isn't on `PATH` or + `DSC_RESOURCE_PATH` for the process that runs `dsc`. For more information, see + [Make the resources discoverable][03]. +- **The operation exits with code 2, 3, or 4.** The **PSResourceList** resource couldn't install + packages. The exit code identifies the cause: the repository isn't registered, the repository + isn't trusted, or `Install-PSResource` failed. For more information, see the + [PSResourceList exit codes][05]. +- **You need more detail about what the resource did.** Add `--trace-level debug` to the `dsc` + command. The resource writes debug and trace messages for every step, including the cmdlets it + calls and the version comparison it performs. + +## See also + +- [Manage packages with a DSC configuration document][06] +- [Manage PowerShell packages with Microsoft DSC][07] +- [dsc resource command reference][09] + + +[01]: ../reference/repository.md +[02]: ../reference/psresourcelist.md +[03]: ../overview.md#make-the-resources-discoverable +[04]: ../reference/psresourcelist.md#version +[05]: ../reference/psresourcelist.md#exit-codes +[06]: configuration-documents.md +[07]: ../overview.md +[08]: ../reference/psresourcelist.md#_indesiredstate +[09]: /powershell/dsc/reference/cli/resource/index?view=dsc-3.0&preserve-view=true diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md b/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md new file mode 100644 index 0000000..db7e2ef --- /dev/null +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md @@ -0,0 +1,149 @@ +--- +description: >- + Learn about the Microsoft Desired State Configuration (DSC) v3 resources that ship with + Microsoft.PowerShell.PSResourceGet, what they can manage, and how to make them available to DSC. +ms.date: 09/12/2026 +ms.topic: overview +title: Manage PowerShell packages with Microsoft DSC +--- +# 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)][01] 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 + +| Resource type | Manages | +|:-------------------------------------------------|:--------------------------------------------------------------| +| [Microsoft.PowerShell.PSResourceGet/Repository][02] | A registered package repository: name, URI, trust, priority, and API type | +| [Microsoft.PowerShell.PSResourceGet/PSResourceList][03] | A list of packages that should, or shouldn't, be installed from one repository | + +The **Repository** resource supports the `get`, `set`, `delete`, and `export` operations. The +**PSResourceList** resource supports the `get`, `set`, `test`, `export`, and `whatIf` operations. +For more information about what each operation does, see [DSC resource operations][04]. + +## 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][05]. +- **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][06]. + +Any tool that hosts DSC v3 can also use the resources. For example, you can reference the resource +types from a [WinGet configuration file][07] 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: + + ```powershell + Install-PSResource -Name Microsoft.PowerShell.PSResourceGet -Prerelease + ``` + + For more information, see [Install a package manager for PowerShell][08]. +- **Microsoft DSC 3.0 or later.** For installation instructions, see [Install DSC][09]. + +## Make the resources discoverable + +DSC discovers command-based resources by searching the folders in the `PATH` environment variable, +or in the `DSC_RESOURCE_PATH` environment variable when it's defined, for files with the +`.dsc.resource.json` suffix. The resource manifests and the script that implements the resources +are stored in the root of the module folder: + +```Output +Microsoft.PowerShell.PSResourceGet/ +└── 1.3.0/ + ├── Microsoft.PowerShell.PSResourceGet.psd1 + ├── psresourceget.ps1 + ├── psresourcelist.dsc.resource.json + └── repository.dsc.resource.json +``` + +Add the folder for the installed module version to `PATH` so that DSC can find the manifests. The +following commands add the newest installed version for the current session: + +```powershell +$module = Get-Module -Name Microsoft.PowerShell.PSResourceGet -ListAvailable | + Sort-Object -Property Version -Descending | + Select-Object -First 1 +$env:PATH += [System.IO.Path]::PathSeparator + $module.ModuleBase +``` + +To make the change permanent, add the folder to the `PATH` environment variable for your user or +the machine. Alternatively, set the `DSC_RESOURCE_PATH` environment variable to the module folder. +When `DSC_RESOURCE_PATH` is defined, DSC only searches the folders it lists. For more information, +see [Environment variables][10] in the `dsc` command reference. + +Verify that DSC can find the resources: + +```powershell +dsc resource list Microsoft.PowerShell.PSResourceGet/* +``` + +```Output +Type Kind Version Capabilities +---------------------------------------------------------------------------------- +Microsoft.PowerShell.PSResourceGet/PSResourceList Resource 0.0.1 gs-wt-e- +Microsoft.PowerShell.PSResourceGet/Repository Resource 0.0.1 gs---de- +``` + +The **Capabilities** column shows `g` for `get`, `s` for `set`, `w` for `whatIf`, `t` for `test`, +`d` for `delete`, and `e` for `export`. The table view omits the description column for +readability. + +> [!NOTE] +> The resources use the version of **Microsoft.PowerShell.PSResourceGet** stored in the same folder +> as the resource manifests, even when a different version of the module is already imported in +> your session. Keep the folder on `PATH` pointed at the version you 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-PSResource` | +| **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][11]. + +## See also + +- [Invoke the PSResourceGet DSC resources directly][05] +- [Manage packages with a DSC configuration document][06] +- [Microsoft.PowerShell.PSResourceGet/Repository][02] +- [Microsoft.PowerShell.PSResourceGet/PSResourceList][03] +- [What's new in PSResourceGet][12] + + +[01]: /powershell/dsc/overview?view=dsc-3.0&preserve-view=true +[02]: reference/repository.md +[03]: reference/psresourcelist.md +[04]: /powershell/dsc/concepts/resources/operations?view=dsc-3.0&preserve-view=true +[05]: how-to/invoke-resources.md +[06]: how-to/configuration-documents.md +[07]: /windows/package-manager/configuration/ +[08]: ../install-powershellget.md +[09]: /powershell/dsc/install?view=dsc-3.0&preserve-view=true +[10]: /powershell/dsc/reference/cli/index?view=dsc-3.0&preserve-view=true#environment-variables +[11]: ../how-to/credential-persistence.md +[12]: ../psresourceget-release-notes.md diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md new file mode 100644 index 0000000..3a33799 --- /dev/null +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md @@ -0,0 +1,453 @@ +--- +description: Microsoft.PowerShell.PSResourceGet/PSResourceList DSC resource reference documentation +ms.date: 09/12/2026 +ms.topic: reference +title: Microsoft.PowerShell.PSResourceGet/PSResourceList +--- +# Microsoft.PowerShell.PSResourceGet/PSResourceList + +## Synopsis + +Manage the PowerShell packages installed from a repository with +**Microsoft.PowerShell.PSResourceGet**. + +## Metadata + +```yaml +Version : 0.0.1 +Kind : resource +Tags : [linux, windows, macos, powershell, nuget] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.PowerShell.PSResourceGet/PSResourceList + properties: + # Required properties + repositoryName: string + # Instance properties + trustedRepository: boolean + resources: + - name: string + version: string + scope: CurrentUser | AllUsers + preRelease: boolean + _exist: boolean +``` + +## Description + +The `Microsoft.PowerShell.PSResourceGet/PSResourceList` resource enables you to idempotently +manage the packages installed from a single repository. An instance of the resource describes one +repository and the list of packages that should, or shouldn't, be installed from it. The resource +can: + +- Report whether each package in the list is installed and which version is installed. +- Install packages that are missing or whose installed version doesn't satisfy the requested + version. +- Uninstall packages that shouldn't be installed. +- Report what it would install or uninstall without changing the machine. +- Export the installed packages on the machine, grouped by repository. + +The resource wraps the `Get-PSResource`, `Install-PSResource`, and `Uninstall-PSResource` cmdlets. +Packages are modules or scripts and are installed to the same locations the cmdlets use, so they +are available to every PowerShell session for the selected scope. + +> [!NOTE] +> This resource is installed with the **Microsoft.PowerShell.PSResourceGet** module. To use it, the +> folder containing the module must be discoverable by DSC. For more information, see +> [Make the resources discoverable][01]. + +## Requirements + +- PowerShell 7.2 or later must be available as `pwsh` in the `PATH` environment variable. +- **Microsoft.PowerShell.PSResourceGet** 1.3.0-preview1 or later must be installed. +- The repository named in `repositoryName` must be registered for the user that runs `dsc`. You + can register it in the same configuration document with the + [Microsoft.PowerShell.PSResourceGet/Repository][02] resource. +- To install packages with the `AllUsers` scope, `dsc` must run in an elevated process. +- Installing packages requires access to the repository. Private repositories must have a + persisted credential configured. For more information, see + [How to add credentials to repositories with PSResourceGet][03]. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the installed state of the packages in the list. +- `set` - You can use the resource to install and uninstall packages so that the machine matches + the list. +- `whatIf` - The resource reports how it would change the machine during a **Set** operation in + what-if mode. +- `test` - The resource implements its own test and reports whether every package in the list is + in the desired state. +- `export` - You can use the resource to enumerate every installed package on the machine. + +For more information about resource capabilities, see [DSC resource capabilities][04]. + +## Examples + +1. [Invoke the PSResourceGet DSC resources directly][05] - Shows how to get, test, set, and export + package lists with the `dsc resource` commands. +1. [Manage packages with a DSC configuration document][06] - Shows how to declare repositories and + packages in a configuration document and preview changes with `--what-if`. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. + + - [repositoryName](#repositoryname) - The repository to install the packages from. + +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [trustedRepository](#trustedrepository) - Whether to install from the repository even when + it isn't trusted. + - [resources](#resources) - The list of packages to manage. + +- **Read-only properties:** The resource returns the following + properties, but they aren't configurable. For more information about read-only properties, see + the "Read-only resource properties" section in [DSC resource properties][07]. + + - [_inDesiredState](#_indesiredstate) - Whether the list is in the desired state. + +### repositoryName + +```yaml +Type : string +IsRequired : true +IsKey : true +IsReadOnly : false +``` + +Defines the name of the registered repository to install the packages from. The resource only +considers packages whose installation metadata records this repository. A package with the same +name that was installed from a different repository is reported as not installed. + +When the repository isn't registered, the **Get** and **Test** operations report every package in +the list as not installed, and the **Set** operation fails with exit code `2`. + +### trustedRepository + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +DefaultValue : false +``` + +Defines whether the resource can install packages from the repository when the repository isn't +registered as trusted. When the value is `true`, the resource installs packages as if you passed +the **TrustRepository** parameter to `Install-PSResource`. When the value is `false` and the +repository isn't trusted, the **Set** operation fails with exit code `3` instead of installing +anything. + +This property doesn't change the trust setting of the repository. To trust a repository +permanently, use the [Microsoft.PowerShell.PSResourceGet/Repository][02] resource. + +### resources + +```yaml +Type : array +IsRequired : false +IsKey : false +IsReadOnly : false +ItemsMinimumCount : 0 +``` + +Defines the list of packages to manage. Each entry is an object that describes one package. The +**Get** and **Test** operations return one entry for every entry you define, in the same order. +The **Export** operation returns one entry for every installed package. + +Each entry in `resources` has the following properties: + +- [name](#name) - The name of the package. +- [version](#version) - The version or version range of the package. +- [scope](#scope) - Where the package is installed. +- [repositoryName](#resourcesrepositoryname) - The repository the package was installed from. +- [preRelease](#prerelease) - Whether to install prerelease versions. +- [_exist](#_exist) - Whether the package should be installed. +- [_metadata](#_metadata) - Messages returned in what-if mode. + +#### name + +```yaml +Type : string +IsRequired : true +IsKey : true +IsReadOnly : false +``` + +Defines the name of the package. The value is compared without regard to case. The same package +name can appear more than once in the list when each entry has a different `version` or +`preRelease` value, for example to install a stable and a prerelease version side by side. + +#### version + +```yaml +Type : [string, 'null'] +IsRequired : false +IsKey : false +IsReadOnly : false +``` + +Defines the version or version range of the package, using the [NuGet version range syntax][08]. +When you don't define this property, the resource installs the latest version and treats any +installed version as satisfying the desired state. + +The resource uses the value in two ways: + +- The **Get** and **Test** operations check whether an installed version _satisfies_ the value as + a NuGet version range. A bare version like `2.0.0` is treated as the range `[2.0.0, )`, so any + installed version equal to or newer than `2.0.0` satisfies it. +- The **Set** operation passes the value to the **Version** parameter of `Install-PSResource`. A + bare version like `2.0.0` installs exactly that version. + +To pin a package to an exact version for both comparison and installation, use the exact range +syntax `[2.0.0]`. The following table shows common values. + +| Value | Get and Test treat it as | Set installs | +|:-----------------|:-----------------------------|:-------------------------------| +| _not defined_ | Any installed version | The latest version | +| `2.0.0` | `2.0.0` or newer | Exactly `2.0.0` | +| `[2.0.0]` | Exactly `2.0.0` | Exactly `2.0.0` | +| `[2.0.0, 3.0.0)` | `2.0.0` up to, not including, `3.0.0` | The newest version in the range | +| `[2.0.0, )` | `2.0.0` or newer | The newest version | + +When more than one version of the package is installed, the **Get** operation returns the version +that satisfies the range. When no installed version satisfies the range, the **Get** operation +returns the installed version it found with `_exist` set to `false`, so you can see which version +is on the machine. For prerelease versions, the returned value includes the prerelease label, like +`2.0.0-preview1`. + +#### scope + +```yaml +Type : [string, 'null'] +IsRequired : false +IsKey : false +IsReadOnly : false +ValidValues : [CurrentUser, AllUsers] +DefaultValue : CurrentUser +``` + +Defines the scope to install the package in. `CurrentUser` installs the package to the module or +script path for the current user. `AllUsers` installs the package to the shared path for every +user and requires an elevated process. The default value is `CurrentUser`. + +The **Get** operation searches both scopes and returns the scope where it found the package. +Packages installed for the current user are found before packages installed for all users. + +#### resources.repositoryName + +```yaml +Type : [string, 'null'] +IsRequired : false +IsKey : false +IsReadOnly : false +``` + +The name of the repository the package was installed from. The **Get** and **Export** operations +return this property for every installed package. You don't need to define it in the desired state. +When you do, the value must match the [repositoryName](#repositoryname) of the list, otherwise the +**Test** operation reports the package as out of the desired state. + +#### preRelease + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +DefaultValue : false +``` + +Defines whether the resource may install a prerelease version of the package. When the value is +`true`, the resource installs the package as if you passed the **Prerelease** parameter to +`Install-PSResource`. Combine this property with a `version` range that includes prerelease +versions, like `[3.0.0-preview1, )`, to install a specific prerelease. + +The **Get** and **Export** operations return `true` for this property when the installed version +is a prerelease version. + +#### _exist + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +DefaultValue : true +``` + +The `_exist` canonical resource property determines whether the package should be installed. When +the value is `true`, the **Set** operation installs the package if it's missing or if the installed +version doesn't satisfy `version`. When the value is `false`, the **Set** operation uninstalls the +package if it's installed. The default value is `true`. + +The **Get** operation returns `false` for this property when the package isn't installed from the +repository or when no installed version satisfies `version`. + +#### _metadata + +```yaml +Type : object +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +This property is returned for entries the resource would change during a **Set** operation invoked +in what-if mode. For other operations, and for entries that are already in the desired state, the +return data doesn't include this property. + +`_metadata` has the following properties: + +- **whatIf** - An array of strings. Each string describes an action the resource would take, like + `Would install resource 'PSScriptAnalyzer' version '1.24.0'` or + `Would uninstall resource 'Pester'`. When the resource would install the latest version, the + message reports the version as `latest`. + +### _inDesiredState + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : true +``` + +Returned by the **Test** operation. The value is `true` when every entry in `resources` is in the +desired state. An entry is in the desired state when its installed state matches `_exist`, the +installed version satisfies `version`, and the installed `scope` and `repositoryName` match the +values you defined. + +The resource also returns this property for every entry in `resources`. Only the top-level value +is meaningful. The per-entry value is always `false`. + +When the list is in the desired state, the `actualState` returned by the **Test** operation +contains the installed packages. When the list isn't in the desired state, the `actualState` +contains the entries you defined, with default values filled in, rather than the installed +packages. To see which versions are installed in that case, use the **Get** operation. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. The +validating schema only includes schema keywords that affect how the instance is validated. All +non-validating keywords are omitted. + +```json +{ + "type": "object", + "additionalProperties": false, + "required": ["repositoryName"], + "properties": { + "repositoryName": { "type": ["string", "null"] }, + "trustedRepository": { "type": "boolean", "default": false }, + "resources": { + "type": "array", + "minItems": 0, + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name"], + "properties": { + "name": { "type": ["string", "null"] }, + "version": { "type": ["string", "null"] }, + "scope": { "type": ["string", "null"], "enum": ["CurrentUser", "AllUsers"] }, + "repositoryName": { "type": ["string", "null"] }, + "preRelease": { "type": "boolean", "default": false }, + "_exist": { "type": "boolean", "default": true }, + "_inDesiredState": { "type": "boolean", "default": true }, + "_metadata": { + "type": "object", + "readOnly": true, + "additionalProperties": false, + "properties": { + "whatIf": { "type": "array", "items": { "type": "string" } } + } + } + } + } + }, + "_inDesiredState": { "type": "boolean", "default": true } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error +- [2](#exit-code-2) - Repository not found +- [3](#exit-code-3) - Repository not trusted +- [4](#exit-code-4) - Could not install one or more packages +- [12](#exit-code-12) - Unknown operation + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed with an unhandled error. The resource writes a JSON error +message to stderr with the details. Common causes include invalid input JSON or a cmdlet that +raised a terminating error, for example when `Uninstall-PSResource` can't remove a package +because another module depends on it. + +### Exit code 2 + +Indicates the **Set** operation couldn't install packages because no repository with the name +defined in `repositoryName` is registered. Register the repository, for example with the +[Microsoft.PowerShell.PSResourceGet/Repository][02] resource, and retry the operation. + +### Exit code 3 + +Indicates the **Set** operation couldn't install packages because the repository isn't trusted and +`trustedRepository` isn't `true`. Set `trustedRepository` to `true` in the desired state, or trust +the repository with the [Microsoft.PowerShell.PSResourceGet/Repository][02] resource. + +### Exit code 4 + +Indicates the **Set** operation failed to install at least one package. The resource writes the +error from `Install-PSResource` to stderr. Common causes include a package name or version that +doesn't exist in the repository, a repository that requires credentials, and network errors. The +resource stops at the first package that fails to install. Packages that were uninstalled or +installed before the failure remain changed. + +### Exit code 12 + +Indicates the resource was invoked with an operation it doesn't recognize. This exit code doesn't +occur when you invoke the resource through DSC. + +## See also + +- [Microsoft.PowerShell.PSResourceGet/Repository][02] +- [Manage PowerShell packages with Microsoft DSC][09] +- [Install-PSResource][10] +- [Uninstall-PSResource][11] +- [Get-PSResource][12] + + +[01]: ../overview.md#make-the-resources-discoverable +[02]: repository.md +[03]: ../../how-to/credential-persistence.md +[04]: /powershell/dsc/concepts/resources/capabilities?view=dsc-3.0&preserve-view=true +[05]: ../how-to/invoke-resources.md +[06]: ../how-to/configuration-documents.md +[07]: /powershell/dsc/concepts/resources/properties?view=dsc-3.0&preserve-view=true#read-only-resource-properties +[08]: /nuget/concepts/package-versioning?tabs=semver20sort#version-ranges +[09]: ../overview.md +[10]: xref:Microsoft.PowerShell.PSResourceGet.Install-PSResource +[11]: xref:Microsoft.PowerShell.PSResourceGet.Uninstall-PSResource +[12]: xref:Microsoft.PowerShell.PSResourceGet.Get-PSResource diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md new file mode 100644 index 0000000..7fd7048 --- /dev/null +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md @@ -0,0 +1,294 @@ +--- +description: Microsoft.PowerShell.PSResourceGet/Repository DSC resource reference documentation +ms.date: 09/12/2026 +ms.topic: reference +title: Microsoft.PowerShell.PSResourceGet/Repository +--- +# Microsoft.PowerShell.PSResourceGet/Repository + +## Synopsis + +Manage the package repositories registered for **Microsoft.PowerShell.PSResourceGet**. + +## Metadata + +```yaml +Version : 0.0.1 +Kind : resource +Tags : [linux, windows, macos, powershell, nuget] +Author : Microsoft +``` + +## Instance definition syntax + +```yaml +resources: + - name: + type: Microsoft.PowerShell.PSResourceGet/Repository + properties: + # Required properties + name: string + uri: string # Required unless _exist is false + # Instance properties + trusted: boolean + priority: integer + repositoryType: Unknown | V2 | V3 | Local | NugetServer | ContainerRegistry + _exist: boolean +``` + +## Description + +The `Microsoft.PowerShell.PSResourceGet/Repository` resource enables you to idempotently manage +the repositories that **Microsoft.PowerShell.PSResourceGet** installs packages from. The resource +can: + +- Register a repository that doesn't exist. +- Update the URI, trust setting, priority, or API type of an existing repository. +- Unregister a repository. +- Export every registered repository as a configuration document. + +The resource wraps the `Get-PSResourceRepository`, `Register-PSResourceRepository`, +`Set-PSResourceRepository`, and `Unregister-PSResourceRepository` cmdlets. It manages the same +repository store those cmdlets use, so changes made with the resource are visible to interactive +sessions and the other way around. + +> [!NOTE] +> This resource is installed with the **Microsoft.PowerShell.PSResourceGet** module. To use it, the +> folder containing the module must be discoverable by DSC. For more information, see +> [Make the resources discoverable][01]. + +## Requirements + +- PowerShell 7.2 or later must be available as `pwsh` in the `PATH` environment variable. +- **Microsoft.PowerShell.PSResourceGet** 1.3.0-preview1 or later must be installed. +- The repository store is per user. The resource manages the repositories for the user account + that runs `dsc`. + +## Capabilities + +The resource has the following capabilities: + +- `get` - You can use the resource to retrieve the actual state of a repository. +- `set` - You can use the resource to enforce the desired state for a repository. +- `delete` - You can use the resource to unregister a repository. +- `export` - You can use the resource to enumerate every registered repository. + +This resource uses the synthetic test functionality of DSC to determine whether an instance is in +the desired state. DSC compares each property you define in the desired state with the value the +resource returns from the **Get** operation. For more information about resource capabilities, see +[DSC resource capabilities][02]. + +> [!TIP] +> The resource returns the `uri` property in the normalized form that +> `Get-PSResourceRepository` reports. For example, a URI without a path gets a trailing slash. To +> avoid a synthetic test that reports the repository as out of the desired state, define `uri` in +> the desired state exactly as `Get-PSResourceRepository` returns it. + +## Examples + +1. [Invoke the PSResourceGet DSC resources directly][03] - Shows how to get, set, delete, and + export repositories with the `dsc resource` commands. +1. [Manage packages with a DSC configuration document][04] - Shows how to register a repository + and install packages from it in a single configuration document. + +## Properties + +The following list describes the properties for the resource. + +- **Required properties:** The following properties are always + required when defining an instance of the resource. + + - [name](#name) - The name of the repository. + - [uri](#uri) - The location of the repository. Required unless `_exist` is `false`. + +- **Instance properties:** The following properties are optional. + They define the desired state for an instance of the resource. + + - [trusted](#trusted) - Whether packages can be installed from the repository without a prompt. + - [priority](#priority) - The search order of the repository relative to other repositories. + - [repositoryType](#repositorytype) - The API type of the repository. + - [_exist](#_exist) - Whether the repository should be registered. + +### name + +```yaml +Type : string +IsRequired : true +IsKey : true +IsReadOnly : false +``` + +Defines the name of the repository. The name identifies the repository in the repository store and +is the value you pass to the **Repository** parameter of cmdlets like `Install-PSResource`. The +name must be unique. The value is compared without regard to case. + +### uri + +```yaml +Type : [string, 'null'] +IsRequired : true (when _exist is true) / false (when _exist is false) +IsKey : false +IsReadOnly : false +Format : uri +``` + +Defines the location of the repository. The value can be an HTTPS URL, a file system path, or the +URL of a container registry. For more information about the repository types that +**Microsoft.PowerShell.PSResourceGet** supports, see [PSResourceGet supported repositories][05]. + +When `_exist` is `false`, this property is optional. The **Get** operation returns `null` for this +property when the repository isn't registered. + +### trusted + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +``` + +Defines whether the repository is trusted. When a repository is trusted, `Install-PSResource` +installs packages from it without prompting for confirmation. When you register a repository with +the resource and don't define this property, the repository is registered as untrusted. + +The [Microsoft.PowerShell.PSResourceGet/PSResourceList][06] resource can only install packages +from an untrusted repository when its `trustedRepository` property is `true`. + +### priority + +```yaml +Type : integer +IsRequired : false +IsKey : false +IsReadOnly : false +InclusiveMinimumValue : 0 +InclusiveMaximumValue : 100 +``` + +Defines the priority of the repository. When a cmdlet searches more than one repository, it +searches repositories with a lower priority value first. When you register a repository with the +resource and don't define this property, the repository gets the default priority of `50`. + +### repositoryType + +```yaml +Type : string +IsRequired : false +IsKey : false +IsReadOnly : false +ValidValues : [Unknown, V2, V3, Local, NugetServer, ContainerRegistry] +``` + +Defines the API type of the repository. The value maps to the **ApiVersion** parameter of +`Register-PSResourceRepository` and `Set-PSResourceRepository`. When you don't define this +property, **Microsoft.PowerShell.PSResourceGet** detects the API type from the URI. + +The following table describes the valid values. + +| Value | Description | +|:--------------------|:-----------------------------------------------------------------------| +| `V2` | A NuGet v2 API feed, like the PowerShell Gallery. | +| `V3` | A NuGet v3 API feed. | +| `Local` | A folder on the file system or a network share. | +| `NugetServer` | A NuGet.Server instance. | +| `ContainerRegistry` | An OCI container registry, like Azure Container Registry or the Microsoft Artifact Registry. | +| `Unknown` | Returned by the **Get** operation when the repository isn't registered. Don't use this value in the desired state. | + +### _exist + +```yaml +Type : boolean +IsRequired : false +IsKey : false +IsReadOnly : false +DefaultValue : true +``` + +The `_exist` canonical resource property determines whether the repository should be registered. +When the value is `true`, the resource registers the repository if it isn't registered and updates +it if it is. When the value is `false`, the resource unregisters the repository if it's +registered. The default value is `true`. + +The **Get** operation returns `false` for this property when no repository with the specified +`name` is registered. In that case the resource returns `null` for `uri`, `false` for `trusted`, +`0` for `priority`, and `Unknown` for `repositoryType`. + +## Instance validating schema + +The following snippet contains the JSON Schema that validates an instance of the resource. The +validating schema only includes schema keywords that affect how the instance is validated. All +non-validating keywords are omitted. + +```json +{ + "type": "object", + "additionalProperties": false, + "allOf": [ + { + "if": { + "properties": { "_exist": { "const": false } } + }, + "then": { "required": ["name"] }, + "else": { "required": ["name", "uri"] } + } + ], + "properties": { + "name": { "type": "string" }, + "uri": { "type": ["string", "null"], "format": "uri" }, + "trusted": { "type": "boolean" }, + "priority": { "type": "integer", "minimum": 0, "maximum": 100 }, + "repositoryType": { + "type": "string", + "enum": ["Unknown", "V2", "V3", "Local", "NugetServer", "ContainerRegistry"] + }, + "_exist": { "type": "boolean", "default": true } + } +} +``` + +## Exit codes + +The resource returns the following exit codes from operations: + +- [0](#exit-code-0) - Success +- [1](#exit-code-1) - Error +- [12](#exit-code-12) - Unknown operation + +### Exit code 0 + +Indicates the resource operation completed without errors. + +### Exit code 1 + +Indicates the resource operation failed. The resource writes a JSON error message to stderr with +the details. Common causes include: + +- The **Get** operation was invoked without input. The `name` property is required, so you must + pass the desired state with the `--input` or `--file` option. +- The **Delete** operation was invoked with `_exist` set to `true`. +- A cmdlet raised a terminating error, for example when the value of `uri` isn't a valid URI. + +### Exit code 12 + +Indicates the resource was invoked with an operation it doesn't recognize. This exit code doesn't +occur when you invoke the resource through DSC. + +## See also + +- [Microsoft.PowerShell.PSResourceGet/PSResourceList][06] +- [Manage PowerShell packages with Microsoft DSC][07] +- [Register-PSResourceRepository][08] +- [Set-PSResourceRepository][09] +- [PSResourceGet supported repositories][05] + + +[01]: ../overview.md#make-the-resources-discoverable +[02]: /powershell/dsc/concepts/resources/capabilities?view=dsc-3.0&preserve-view=true +[03]: ../how-to/invoke-resources.md +[04]: ../how-to/configuration-documents.md +[05]: ../../supported-repositories.md +[06]: psresourcelist.md +[07]: ../overview.md +[08]: xref:Microsoft.PowerShell.PSResourceGet.Register-PSResourceRepository +[09]: xref:Microsoft.PowerShell.PSResourceGet.Set-PSResourceRepository diff --git a/powershell-gallery/docs-conceptual/powershellget/toc.yml b/powershell-gallery/docs-conceptual/powershellget/toc.yml index e5c1970..1b5a68d 100644 --- a/powershell-gallery/docs-conceptual/powershellget/toc.yml +++ b/powershell-gallery/docs-conceptual/powershellget/toc.yml @@ -11,6 +11,22 @@ items: href: how-to/use-acr-repository.md - name: Use the Azure Artifacts Credential Provider with Azure Artifacts feeds href: how-to/use-credential-provider-with-azure-artifacts.md + - name: Microsoft DSC resources + items: + - name: Overview + href: dsc/overview.md + - name: How to + items: + - name: Invoke the resources directly + href: dsc/how-to/invoke-resources.md + - name: Manage packages with a configuration document + href: dsc/how-to/configuration-documents.md + - name: Resource reference + items: + - name: Microsoft.PowerShell.PSResourceGet/Repository + href: dsc/reference/repository.md + - name: Microsoft.PowerShell.PSResourceGet/PSResourceList + href: dsc/reference/psresourcelist.md - name: PSResourceGet supported repositories href: supported-repositories.md - name: PSResourceGet release notes From e21986639a76398c5c37fc1705e9ce1f6b9411ee Mon Sep 17 00:00:00 2001 From: "G.Reijn" <26114636+Gijsreyn@users.noreply.github.com> Date: Wed, 16 Sep 2026 18:46:51 +0200 Subject: [PATCH 2/5] Resolve technical review --- .../dsc/how-to/configuration-documents.md | 7 +- .../dsc/how-to/invoke-resources.md | 16 ++-- .../powershellget/dsc/overview.md | 84 ++++++++++--------- .../dsc/reference/psresourcelist.md | 34 ++++---- .../powershellget/dsc/reference/repository.md | 22 ++--- 5 files changed, 86 insertions(+), 77 deletions(-) diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md index e655c23..8a93e90 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md @@ -16,8 +16,9 @@ and how to work with that document using the `dsc config` commands. ## Prerequisites -- Complete the steps in [Make the resources discoverable][01] so that `dsc resource list` - returns both resources. +- Install **Microsoft.PowerShell.PSResourceGet** 1.3.0-preview1 or later and confirm that + `dsc resource list Microsoft.PowerShell.PSResourceGet/*` returns both resources. For more + information, see [How DSC discovers the resources][01]. - A text editor for YAML files. Visual Studio Code with the YAML extension validates the document against the DSC schema while you type. @@ -502,7 +503,7 @@ For more information, see [DSC configuration document parameters][05]. - [dsc config command reference][10] -[01]: ../overview.md#make-the-resources-discoverable +[01]: ../overview.md#how-dsc-discovers-the-resources [02]: /powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#dependson [03]: ../reference/psresourcelist.md#version [04]: ../reference/psresourcelist.md#exit-codes diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md index 2b6a0ee..b7dc4b0 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md @@ -15,8 +15,9 @@ each operation the [Repository][01] and [PSResourceList][02] resources support. ## Prerequisites -- Complete the steps in [Make the resources discoverable][03] so that `dsc resource list` - returns both resources. +- Install **Microsoft.PowerShell.PSResourceGet** 1.3.0-preview1 or later and confirm that + `dsc resource list Microsoft.PowerShell.PSResourceGet/*` returns both resources. For more + information, see [How DSC discovers the resources][03]. - Run the commands in PowerShell 7. The examples build the input JSON with hashtables and `ConvertTo-Json`, which keeps the quoting readable. @@ -418,15 +419,16 @@ relax them to a range. For more information, see the [version][04] property. ## Troubleshoot -- **DSC reports that the resource type isn't found.** The module folder isn't on `PATH` or - `DSC_RESOURCE_PATH` for the process that runs `dsc`. For more information, see - [Make the resources discoverable][03]. +- **DSC reports that the resource type isn't found.** DSC didn't discover the module. Confirm that + `pwsh` is in `PATH`, that the installed version is 1.3.0-preview1 or later, and that the module is + installed for PowerShell 7 rather than Windows PowerShell. For more information, see + [How DSC discovers the resources][03]. - **The operation exits with code 2, 3, or 4.** The **PSResourceList** resource couldn't install packages. The exit code identifies the cause: the repository isn't registered, the repository isn't trusted, or `Install-PSResource` failed. For more information, see the [PSResourceList exit codes][05]. - **You need more detail about what the resource did.** Add `--trace-level debug` to the `dsc` - command. The resource writes debug and trace messages for every step, including the cmdlets it + command. The resource writes debug and info messages for every step, including the cmdlets it calls and the version comparison it performs. ## See also @@ -438,7 +440,7 @@ relax them to a range. For more information, see the [version][04] property. [01]: ../reference/repository.md [02]: ../reference/psresourcelist.md -[03]: ../overview.md#make-the-resources-discoverable +[03]: ../overview.md#how-dsc-discovers-the-resources [04]: ../reference/psresourcelist.md#version [05]: ../reference/psresourcelist.md#exit-codes [06]: configuration-documents.md diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md b/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md index db7e2ef..574c35f 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md @@ -1,7 +1,7 @@ --- description: >- Learn about the Microsoft Desired State Configuration (DSC) v3 resources that ship with - Microsoft.PowerShell.PSResourceGet, what they can manage, and how to make them available to DSC. + Microsoft.PowerShell.PSResourceGet, what they can manage, and how DSC discovers them. ms.date: 09/12/2026 ms.topic: overview title: Manage PowerShell packages with Microsoft DSC @@ -19,9 +19,9 @@ you use interactively, such as `Register-PSResourceRepository` and `Install-PSRe ## Available resources -| Resource type | Manages | -|:-------------------------------------------------|:--------------------------------------------------------------| -| [Microsoft.PowerShell.PSResourceGet/Repository][02] | A registered package repository: name, URI, trust, priority, and API type | +| Resource type | Manages | +|:--------------------------------------------------------|:-------------------------------------------------------------------------------| +| [Microsoft.PowerShell.PSResourceGet/Repository][02] | A registered package repository: name, URI, trust, priority, and API type | | [Microsoft.PowerShell.PSResourceGet/PSResourceList][03] | A list of packages that should, or shouldn't, be installed from one repository | The **Repository** resource supports the `get`, `set`, `delete`, and `export` operations. The @@ -56,14 +56,18 @@ types from a [WinGet configuration file][07] that uses the `dscv3` processor. ``` For more information, see [Install a package manager for PowerShell][08]. -- **Microsoft DSC 3.0 or later.** For installation instructions, see [Install DSC][09]. +- **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][09]. -## Make the resources discoverable +## How DSC discovers the resources -DSC discovers command-based resources by searching the folders in the `PATH` environment variable, -or in the `DSC_RESOURCE_PATH` environment variable when it's defined, for files with the -`.dsc.resource.json` suffix. The resource manifests and the script that implements the resources -are stored in the root of the module folder: +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 `PSModulePath` environment +variable for DSC resource manifests. Because `Install-PSResource` installs the module to a folder in +`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: ```Output Microsoft.PowerShell.PSResourceGet/ @@ -74,21 +78,6 @@ Microsoft.PowerShell.PSResourceGet/ └── repository.dsc.resource.json ``` -Add the folder for the installed module version to `PATH` so that DSC can find the manifests. The -following commands add the newest installed version for the current session: - -```powershell -$module = Get-Module -Name Microsoft.PowerShell.PSResourceGet -ListAvailable | - Sort-Object -Property Version -Descending | - Select-Object -First 1 -$env:PATH += [System.IO.Path]::PathSeparator + $module.ModuleBase -``` - -To make the change permanent, add the folder to the `PATH` environment variable for your user or -the machine. Alternatively, set the `DSC_RESOURCE_PATH` environment variable to the module folder. -When `DSC_RESOURCE_PATH` is defined, DSC only searches the folders it lists. For more information, -see [Environment variables][10] in the `dsc` command reference. - Verify that DSC can find the resources: ```powershell @@ -98,28 +87,43 @@ dsc resource list Microsoft.PowerShell.PSResourceGet/* ```Output Type Kind Version Capabilities ---------------------------------------------------------------------------------- -Microsoft.PowerShell.PSResourceGet/PSResourceList Resource 0.0.1 gs-wt-e- -Microsoft.PowerShell.PSResourceGet/Repository Resource 0.0.1 gs---de- +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 table view omits the description column for -readability. +`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 module is installed for PowerShell 7.** The extension ignores the Windows PowerShell module + folders in `PSModulePath`. Run + `Get-InstalledPSResource -Name Microsoft.PowerShell.PSResourceGet` in `pwsh` to confirm where the + module is installed. +- **The installed version is 1.3.0-preview1 or later.** Earlier versions don't include the resource + manifests. + +To confirm that the extension is available, run `dsc extension list`. For more information, see +[dsc extension list][10]. > [!NOTE] -> The resources use the version of **Microsoft.PowerShell.PSResourceGet** stored in the same folder -> as the resource manifests, even when a different version of the module is already imported in -> your session. Keep the folder on `PATH` pointed at the version you want DSC to use. +> 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-PSResource` | -| **PSResourceList** set | `Install-PSResource`, `Uninstall-PSResource` | +| 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 @@ -144,6 +148,6 @@ configured before DSC can install from it. For more information, see [07]: /windows/package-manager/configuration/ [08]: ../install-powershellget.md [09]: /powershell/dsc/install?view=dsc-3.0&preserve-view=true -[10]: /powershell/dsc/reference/cli/index?view=dsc-3.0&preserve-view=true#environment-variables +[10]: /powershell/dsc/reference/cli/extension/list?view=dsc-3.0&preserve-view=true [11]: ../how-to/credential-persistence.md [12]: ../psresourceget-release-notes.md diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md index 3a33799..b4e1465 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md @@ -53,14 +53,14 @@ can: - Report what it would install or uninstall without changing the machine. - Export the installed packages on the machine, grouped by repository. -The resource wraps the `Get-PSResource`, `Install-PSResource`, and `Uninstall-PSResource` cmdlets. -Packages are modules or scripts and are installed to the same locations the cmdlets use, so they -are available to every PowerShell session for the selected scope. +The resource wraps the `Get-InstalledPSResource`, `Install-PSResource`, and `Uninstall-PSResource` +cmdlets. Packages are modules or scripts and are installed to the same locations the cmdlets use, +so they are available to every PowerShell session for the selected scope. > [!NOTE] -> This resource is installed with the **Microsoft.PowerShell.PSResourceGet** module. To use it, the -> folder containing the module must be discoverable by DSC. For more information, see -> [Make the resources discoverable][01]. +> This resource is installed with the **Microsoft.PowerShell.PSResourceGet** module. DSC discovers +> it from `PSModulePath`, so you don't need to add the module folder to `PATH`. For more +> information, see [How DSC discovers the resources][01]. ## Requirements @@ -214,13 +214,13 @@ The resource uses the value in two ways: To pin a package to an exact version for both comparison and installation, use the exact range syntax `[2.0.0]`. The following table shows common values. -| Value | Get and Test treat it as | Set installs | -|:-----------------|:-----------------------------|:-------------------------------| -| _not defined_ | Any installed version | The latest version | -| `2.0.0` | `2.0.0` or newer | Exactly `2.0.0` | -| `[2.0.0]` | Exactly `2.0.0` | Exactly `2.0.0` | +| Value | Get and Test treat it as | Set installs | +|:-----------------|:--------------------------------------|:--------------------------------| +| _not defined_ | Any installed version | The latest version | +| `2.0.0` | `2.0.0` or newer | Exactly `2.0.0` | +| `[2.0.0]` | Exactly `2.0.0` | Exactly `2.0.0` | | `[2.0.0, 3.0.0)` | `2.0.0` up to, not including, `3.0.0` | The newest version in the range | -| `[2.0.0, )` | `2.0.0` or newer | The newest version | +| `[2.0.0, )` | `2.0.0` or newer | The newest version | When more than one version of the package is installed, the **Get** operation returns the version that satisfies the range. When no installed version satisfies the range, the **Get** operation @@ -246,7 +246,9 @@ user and requires an elevated process. The default value is `CurrentUser`. The **Get** operation searches both scopes and returns the scope where it found the package. Packages installed for the current user are found before packages installed for all users. -#### resources.repositoryName + + +#### repositoryName ```yaml Type : [string, 'null'] @@ -436,10 +438,10 @@ occur when you invoke the resource through DSC. - [Manage PowerShell packages with Microsoft DSC][09] - [Install-PSResource][10] - [Uninstall-PSResource][11] -- [Get-PSResource][12] +- [Get-InstalledPSResource][12] -[01]: ../overview.md#make-the-resources-discoverable +[01]: ../overview.md#how-dsc-discovers-the-resources [02]: repository.md [03]: ../../how-to/credential-persistence.md [04]: /powershell/dsc/concepts/resources/capabilities?view=dsc-3.0&preserve-view=true @@ -450,4 +452,4 @@ occur when you invoke the resource through DSC. [09]: ../overview.md [10]: xref:Microsoft.PowerShell.PSResourceGet.Install-PSResource [11]: xref:Microsoft.PowerShell.PSResourceGet.Uninstall-PSResource -[12]: xref:Microsoft.PowerShell.PSResourceGet.Get-PSResource +[12]: xref:Microsoft.PowerShell.PSResourceGet.Get-InstalledPSResource diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md index 7fd7048..13ee70e 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md @@ -53,9 +53,9 @@ repository store those cmdlets use, so changes made with the resource are visibl sessions and the other way around. > [!NOTE] -> This resource is installed with the **Microsoft.PowerShell.PSResourceGet** module. To use it, the -> folder containing the module must be discoverable by DSC. For more information, see -> [Make the resources discoverable][01]. +> This resource is installed with the **Microsoft.PowerShell.PSResourceGet** module. DSC discovers +> it from `PSModulePath`, so you don't need to add the module folder to `PATH`. For more +> information, see [How DSC discovers the resources][01]. ## Requirements @@ -186,13 +186,13 @@ property, **Microsoft.PowerShell.PSResourceGet** detects the API type from the U The following table describes the valid values. -| Value | Description | -|:--------------------|:-----------------------------------------------------------------------| -| `V2` | A NuGet v2 API feed, like the PowerShell Gallery. | -| `V3` | A NuGet v3 API feed. | -| `Local` | A folder on the file system or a network share. | -| `NugetServer` | A NuGet.Server instance. | -| `ContainerRegistry` | An OCI container registry, like Azure Container Registry or the Microsoft Artifact Registry. | +| Value | Description | +|:--------------------|:-------------------------------------------------------------------------------------------------------------------| +| `V2` | A NuGet v2 API feed, like the PowerShell Gallery. | +| `V3` | A NuGet v3 API feed. | +| `Local` | A folder on the file system or a network share. | +| `NugetServer` | A NuGet.Server instance. | +| `ContainerRegistry` | An OCI container registry, like Azure Container Registry or the Microsoft Artifact Registry. | | `Unknown` | Returned by the **Get** operation when the repository isn't registered. Don't use this value in the desired state. | ### _exist @@ -283,7 +283,7 @@ occur when you invoke the resource through DSC. - [PSResourceGet supported repositories][05] -[01]: ../overview.md#make-the-resources-discoverable +[01]: ../overview.md#how-dsc-discovers-the-resources [02]: /powershell/dsc/concepts/resources/capabilities?view=dsc-3.0&preserve-view=true [03]: ../how-to/invoke-resources.md [04]: ../how-to/configuration-documents.md From 484ca9e79ac2bd5aa52d219f4edc060066479a1e Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 21 Sep 2026 14:05:32 -0500 Subject: [PATCH 3/5] Editorial pass --- .../dsc/how-to/configuration-documents.md | 88 ++++---- .../dsc/how-to/invoke-resources.md | 55 +++-- .../powershellget/dsc/overview.md | 80 +++---- .../dsc/reference/psresourcelist.md | 195 ++++++++++-------- .../powershellget/dsc/reference/repository.md | 97 +++++---- 5 files changed, 273 insertions(+), 242 deletions(-) diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md index 8a93e90..a6072fa 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/configuration-documents.md @@ -2,7 +2,7 @@ description: >- Learn how to declare package repositories and PowerShell packages in a Microsoft DSC configuration document and apply, test, preview, and export it with the dsc config commands. -ms.date: 09/12/2026 +ms.date: 09/21/2026 ms.topic: how-to title: Manage packages with a DSC configuration document --- @@ -11,14 +11,14 @@ title: Manage packages with a DSC configuration document A DSC configuration document describes the desired state of a machine as a list of resource instances. When you apply the document, the DSC engine invokes each resource in order, resolves dependencies between instances, and reports the result for the document as a whole. This article -shows how to describe the repositories and packages a machine needs in a configuration document -and how to work with that document using the `dsc config` commands. +shows how to describe the repositories and packages a machine needs in a configuration document and +how to work with that document using the `dsc config` commands. ## Prerequisites - Install **Microsoft.PowerShell.PSResourceGet** 1.3.0-preview1 or later and confirm that `dsc resource list Microsoft.PowerShell.PSResourceGet/*` returns both resources. For more - information, see [How DSC discovers the resources][01]. + information, see [How DSC discovers the resources][02]. - A text editor for YAML files. Visual Studio Code with the YAML extension validates the document against the DSC schema while you type. @@ -70,20 +70,19 @@ resources: The document shows several patterns: - **Register before you install.** The `dependsOn` entry tells DSC to process the **Repository** - instance before the **PSResourceList** instance that installs from it. Without the dependency, - DSC processes instances in document order, which works here but isn't guaranteed if you - reorder the document. For more information, see - [Configuration document resource dependencies][02]. + instance before the **PSResourceList** instance that installs from it. Without the dependency, DSC + processes instances in document order, which works here but isn't guaranteed if you reorder the + document. For more information, see [Configuration document resource dependencies][10]. - **One list per repository.** Each **PSResourceList** instance manages the packages from a single repository. Use one instance for each repository you install from. - **Trust at the repository or at the list.** The Contoso repository is registered as trusted, so its list doesn't need `trustedRepository`. The PowerShell Gallery keeps its default untrusted setting, so the list that installs from it sets `trustedRepository` to `true`. -- **Pin, range, or latest.** `PSScriptAnalyzer` is pinned to an exact version, `Pester` accepts - any version from 5.0.0 onward, and `Microsoft.WinGet.Client` takes the latest - version including prereleases. For more information, see the [version][03] property. -- **Remove what shouldn't be there.** `Contoso.Legacy` has `_exist: false`, so DSC uninstalls it - if it's found. +- **Pin, range, or latest.** `PSScriptAnalyzer` is pinned to an exact version, `Pester` accepts any + version from 5.0.0 onward, and `Microsoft.WinGet.Client` takes the latest version including + prereleases. For more information, see the [version][06] property. +- **Remove what shouldn't be there.** `Contoso.Legacy` has `_exist: false`, so DSC uninstalls it if + it's found. > [!NOTE] > The `Pester` entry installs to the `AllUsers` scope, so `dsc` must run in an elevated process to @@ -91,9 +90,8 @@ The document shows several patterns: ## Test the document -Use `dsc config test` to compare the document with the machine without changing anything. The -output reports the state of every instance and whether the document as a whole is in the desired -state. +Use `dsc config test` to compare the document with the machine without changing anything. The output +reports the state of every instance and whether the document as a whole is in the desired state. ```powershell dsc config test --file ./packages.dsc.yaml @@ -225,10 +223,10 @@ hadErrors: false > returns for the **Test** operation echoes the entries you defined, with default values filled in, > rather than the installed packages. The per-entry `_inDesiredState` value is always `false`. Use > `dsc config get` to see which versions are installed. For more information, see the -> [_inDesiredState][11] property. +> [_inDesiredState][04] property. -The output is long. Convert the JSON output to objects to list only the instances that aren't in -the desired state: +The output is long. Convert the JSON output to objects to list only the instances that aren't in the +desired state: ```powershell $result = dsc config test --file ./packages.dsc.yaml -o json | ConvertFrom-Json @@ -412,15 +410,15 @@ that isn't in the desired state and reports the state before and after each chan dsc config set --file ./packages.dsc.yaml ``` -The command is idempotent. Run it again and the resources report no changes, because every -instance is already in the desired state. Run `dsc config test` at any time to detect drift, for -example after someone installs or removes a package interactively. +The command is idempotent. Run it again and the resources report no changes, because every instance +is already in the desired state. Run `dsc config test` at any time to detect drift, for example +after someone installs or removes a package interactively. If a **PSResourceList** instance fails to install a package, DSC stops processing the document and reports the error. The `hadErrors` property in the output is `true`, and the `messages` property contains the error the resource wrote. Fix the cause and apply the document again. Packages that were installed before the failure stay installed and aren't reinstalled. For more information, see -the [PSResourceList exit codes][04]. +the [PSResourceList exit codes][05]. ## Capture the state of a machine @@ -445,11 +443,11 @@ dsc config export --file ./export.dsc.yaml | Out-File -FilePath ./machine.dsc.ya Before you apply the exported document elsewhere, review it: - Remove packages that shouldn't be managed, such as modules that ship with PowerShell. -- Decide how strict each `version` should be. The export records bare versions, which the - resource treats as minimum versions when it tests the machine and as exact versions when it - installs. Pin with `[]` or widen to a range as needed. -- Add `trustedRepository: true` to lists that install from untrusted repositories, or set - `trusted: true` on the corresponding **Repository** instance. +- Decide how strict each `version` should be. The export records bare versions, which the resource + treats as minimum versions when it tests the machine and as exact versions when it installs. Pin + with `[]` or widen to a range as needed. +- Add `trustedRepository: true` to lists that install from untrusted repositories, or set `trusted: + true` on the corresponding **Repository** instance. ## Use parameters for values that change per machine @@ -492,25 +490,25 @@ $parameters = @{ dsc config --parameters $parameters set --file ./packages-parameterized.dsc.yaml ``` -For more information, see [DSC configuration document parameters][05]. +For more information, see [DSC configuration document parameters][09]. ## See also -- [Invoke the PSResourceGet DSC resources directly][06] -- [Manage PowerShell packages with Microsoft DSC][07] -- [Microsoft.PowerShell.PSResourceGet/Repository][08] -- [Microsoft.PowerShell.PSResourceGet/PSResourceList][09] -- [dsc config command reference][10] +- [Invoke the PSResourceGet DSC resources directly][11] +- [Manage PowerShell packages with Microsoft DSC][01] +- [Microsoft.PowerShell.PSResourceGet/Repository][07] +- [Microsoft.PowerShell.PSResourceGet/PSResourceList][03] +- [dsc config command reference][08] -[01]: ../overview.md#how-dsc-discovers-the-resources -[02]: /powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#dependson -[03]: ../reference/psresourcelist.md#version -[04]: ../reference/psresourcelist.md#exit-codes -[05]: /powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true -[06]: invoke-resources.md -[07]: ../overview.md -[08]: ../reference/repository.md -[09]: ../reference/psresourcelist.md -[10]: /powershell/dsc/reference/cli/config/index?view=dsc-3.0&preserve-view=true -[11]: ../reference/psresourcelist.md#_indesiredstate +[01]: ../overview.md +[02]: ../overview.md#how-dsc-discovers-the-resources +[03]: ../reference/psresourcelist.md +[04]: ../reference/psresourcelist.md#_indesiredstate +[05]: ../reference/psresourcelist.md#exit-codes +[06]: ../reference/psresourcelist.md#version +[07]: ../reference/repository.md +[08]: /powershell/dsc/reference/cli/config/index?view=dsc-3.0&preserve-view=true +[09]: /powershell/dsc/reference/schemas/config/parameter?view=dsc-3.0&preserve-view=true +[10]: /powershell/dsc/reference/schemas/config/resource?view=dsc-3.0&preserve-view=true#dependson +[11]: invoke-resources.md diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md index b7dc4b0..d573c71 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/how-to/invoke-resources.md @@ -2,7 +2,7 @@ description: >- Learn how to invoke the Microsoft.PowerShell.PSResourceGet DSC resources one at a time with the dsc resource commands to inspect, test, change, and export repositories and packages. -ms.date: 09/12/2026 +ms.date: 09/21/2026 ms.topic: how-to title: Invoke the PSResourceGet DSC resources directly --- @@ -10,14 +10,14 @@ title: Invoke the PSResourceGet DSC resources directly The `dsc resource` commands invoke a single DSC resource with the desired state you pass on the command line. Use them to inspect what's on a machine, to check whether a machine already matches -what you want, or to make a change without writing a configuration document. This article shows -each operation the [Repository][01] and [PSResourceList][02] resources support. +what you want, or to make a change without writing a configuration document. This article shows each +operation the [Repository][07] and [PSResourceList][03] resources support. ## Prerequisites - Install **Microsoft.PowerShell.PSResourceGet** 1.3.0-preview1 or later and confirm that `dsc resource list Microsoft.PowerShell.PSResourceGet/*` returns both resources. For more - information, see [How DSC discovers the resources][03]. + information, see [How DSC discovers the resources][02]. - Run the commands in PowerShell 7. The examples build the input JSON with hashtables and `ConvertTo-Json`, which keeps the quoting readable. @@ -55,8 +55,8 @@ actualState: ``` > [!NOTE] -> The **Get** operation requires input. Running the command without `--input` or `--file` exits -> with a non-zero code and an error that explains the `name` property is required. +> The **Get** operation requires input. Running the command without `--input` or `--file` exits with +> a non-zero code and an error that explains the `name` property is required. ### Register or update a repository @@ -127,9 +127,8 @@ dsc resource delete --resource $type --input $instance ### Export the registered repositories -The **Export** operation returns a configuration document that declares every registered -repository. Save the output to capture the repository setup of a machine so you can apply it to -another one. +The **Export** operation returns a configuration document that declares every registered repository. +Save the output to capture the repository setup of a machine so you can apply it to another one. ```powershell dsc resource export --resource Microsoft.PowerShell.PSResourceGet/Repository | @@ -209,9 +208,9 @@ actualState: ``` When a package is installed but no installed version satisfies the `version` you asked for, the -resource returns the version it found and sets `_exist` to `false`. That tells you the package -needs to be updated rather than installed. For more information about how the resource interprets -`version`, see the [version][04] property. +resource returns the version it found and sets `_exist` to `false`. That tells you the package needs +to be updated rather than installed. For more information about how the resource interprets +`version`, see the [version][06] property. ### Test whether packages are in the desired state @@ -265,8 +264,8 @@ differingProperties: [] Only the top-level `_inDesiredState` value is meaningful. The resource returns the property for every entry as well, but always as `false`. When the list isn't in the desired state, the `actualState` echoes the entries you defined rather than the installed packages. Use the **Get** -operation when you need the installed versions. For more information, see the -[_inDesiredState][08] property. +operation when you need the installed versions. For more information, see the [_inDesiredState][04] +property. ### Install packages @@ -414,15 +413,15 @@ resources: ``` The exported versions are bare versions. Before you apply an exported document to another machine, -review the `version` values and decide whether to pin them with the `[]` syntax or to -relax them to a range. For more information, see the [version][04] property. +review the `version` values and decide whether to pin them with the `[]` syntax or to relax +them to a range. For more information, see the [version][06] property. ## Troubleshoot - **DSC reports that the resource type isn't found.** DSC didn't discover the module. Confirm that `pwsh` is in `PATH`, that the installed version is 1.3.0-preview1 or later, and that the module is installed for PowerShell 7 rather than Windows PowerShell. For more information, see - [How DSC discovers the resources][03]. + [How DSC discovers the resources][02]. - **The operation exits with code 2, 3, or 4.** The **PSResourceList** resource couldn't install packages. The exit code identifies the cause: the repository isn't registered, the repository isn't trusted, or `Install-PSResource` failed. For more information, see the @@ -433,17 +432,17 @@ relax them to a range. For more information, see the [version][04] property. ## See also -- [Manage packages with a DSC configuration document][06] -- [Manage PowerShell packages with Microsoft DSC][07] -- [dsc resource command reference][09] +- [Manage packages with a DSC configuration document][09] +- [Manage PowerShell packages with Microsoft DSC][01] +- [dsc resource command reference][08] -[01]: ../reference/repository.md -[02]: ../reference/psresourcelist.md -[03]: ../overview.md#how-dsc-discovers-the-resources -[04]: ../reference/psresourcelist.md#version +[01]: ../overview.md +[02]: ../overview.md#how-dsc-discovers-the-resources +[03]: ../reference/psresourcelist.md +[04]: ../reference/psresourcelist.md#_indesiredstate [05]: ../reference/psresourcelist.md#exit-codes -[06]: configuration-documents.md -[07]: ../overview.md -[08]: ../reference/psresourcelist.md#_indesiredstate -[09]: /powershell/dsc/reference/cli/resource/index?view=dsc-3.0&preserve-view=true +[06]: ../reference/psresourcelist.md#version +[07]: ../reference/repository.md +[08]: /powershell/dsc/reference/cli/resource/index?view=dsc-3.0&preserve-view=true +[09]: configuration-documents.md diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md b/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md index 574c35f..b258a95 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md @@ -2,14 +2,14 @@ description: >- Learn about the Microsoft Desired State Configuration (DSC) v3 resources that ship with Microsoft.PowerShell.PSResourceGet, what they can manage, and how DSC discovers them. -ms.date: 09/12/2026 +ms.date: 09/21/2026 ms.topic: overview title: Manage PowerShell packages with Microsoft DSC --- # 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)][01] v3 resources. You can use the resources to +[Microsoft Desired State Configuration (DSC)][06] 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. @@ -19,13 +19,14 @@ you use interactively, such as `Register-PSResourceRepository` and `Install-PSRe ## Available resources -| Resource type | Manages | -|:--------------------------------------------------------|:-------------------------------------------------------------------------------| -| [Microsoft.PowerShell.PSResourceGet/Repository][02] | A registered package repository: name, URI, trust, priority, and API type | -| [Microsoft.PowerShell.PSResourceGet/PSResourceList][03] | A list of packages that should, or shouldn't, be installed from one repository | +The [Microsoft.PowerShell.PSResourceGet/Repository][12] resource manages a registered package +repository: name, URI, trust, priority, and API type. This resource supports the `get`, `set`, +`delete`, and `export` operations. The + +The [Microsoft.PowerShell.PSResourceGet/PSResourceList][11] resource manages a list of packages that +should, or shouldn't, be installed from one repository. This PSResourceList** resource supports the +`get`, `set`, `test`, `export`, and `whatIf` operations. -The **Repository** resource supports the `get`, `set`, `delete`, and `export` operations. The -**PSResourceList** resource supports the `get`, `set`, `test`, `export`, and `whatIf` operations. For more information about what each operation does, see [DSC resource operations][04]. ## Choose how to use the resources @@ -35,14 +36,14 @@ 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][05]. + [Invoke the PSResourceGet DSC resources directly][10]. - **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][06]. + information, see [Manage packages with a DSC configuration document][09]. Any tool that hosts DSC v3 can also use the resources. For example, you can reference the resource -types from a [WinGet configuration file][07] that uses the `dscv3` processor. +types from a [WinGet configuration file][08] that uses the `dscv3` processor. ## Prerequisites @@ -55,21 +56,21 @@ types from a [WinGet configuration file][07] that uses the `dscv3` processor. Install-PSResource -Name Microsoft.PowerShell.PSResourceGet -Prerelease ``` - For more information, see [Install a package manager for PowerShell][08]. + For more information, see [Install a package manager for PowerShell][02]. - **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][09]. + packaged in PowerShell modules. For installation instructions, see [Install DSC][05]. ## 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 `PSModulePath` environment +`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 -`PSModulePath`, DSC finds the resources as soon as you install the module. +`$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: -```Output +``` Microsoft.PowerShell.PSResourceGet/ └── 1.3.0/ ├── Microsoft.PowerShell.PSResourceGet.psd1 @@ -99,15 +100,18 @@ 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 module is installed for PowerShell 7.** The extension ignores the Windows PowerShell module - folders in `PSModulePath`. Run - `Get-InstalledPSResource -Name Microsoft.PowerShell.PSResourceGet` in `pwsh` to confirm where the - module is installed. - **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: + + ```powershell + Get-Module Microsoft.PowerShell.PSResourceGet -ListAvailable + ``` To confirm that the extension is available, run `dsc extension list`. For more information, see -[dsc extension list][10]. +[dsc extension list][07]. > [!NOTE] > DSC runs the resources from the module folder that contains the manifest it discovered, not from @@ -128,26 +132,26 @@ To confirm that the extension is available, run `dsc extension list`. For more i 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][11]. +[How to add credentials to repositories with PSResourceGet][01]. ## See also -- [Invoke the PSResourceGet DSC resources directly][05] -- [Manage packages with a DSC configuration document][06] -- [Microsoft.PowerShell.PSResourceGet/Repository][02] -- [Microsoft.PowerShell.PSResourceGet/PSResourceList][03] -- [What's new in PSResourceGet][12] +- [Invoke the PSResourceGet DSC resources directly][10] +- [Manage packages with a DSC configuration document][09] +- [Microsoft.PowerShell.PSResourceGet/Repository][12] +- [Microsoft.PowerShell.PSResourceGet/PSResourceList][11] +- [What's new in PSResourceGet][03] -[01]: /powershell/dsc/overview?view=dsc-3.0&preserve-view=true -[02]: reference/repository.md -[03]: reference/psresourcelist.md +[01]: ../how-to/credential-persistence.md +[02]: ../install-powershellget.md +[03]: ../psresourceget-release-notes.md [04]: /powershell/dsc/concepts/resources/operations?view=dsc-3.0&preserve-view=true -[05]: how-to/invoke-resources.md -[06]: how-to/configuration-documents.md -[07]: /windows/package-manager/configuration/ -[08]: ../install-powershellget.md -[09]: /powershell/dsc/install?view=dsc-3.0&preserve-view=true -[10]: /powershell/dsc/reference/cli/extension/list?view=dsc-3.0&preserve-view=true -[11]: ../how-to/credential-persistence.md -[12]: ../psresourceget-release-notes.md +[05]: /powershell/dsc/install?view=dsc-3.0&preserve-view=true +[06]: /powershell/dsc/overview?view=dsc-3.0&preserve-view=true +[07]: /powershell/dsc/reference/cli/extension/list?view=dsc-3.0&preserve-view=true +[08]: /windows/package-manager/configuration/ +[09]: how-to/configuration-documents.md +[10]: how-to/invoke-resources.md +[11]: reference/psresourcelist.md +[12]: reference/repository.md diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md index b4e1465..ffc20e5 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/psresourcelist.md @@ -1,6 +1,6 @@ --- description: Microsoft.PowerShell.PSResourceGet/PSResourceList DSC resource reference documentation -ms.date: 09/12/2026 +ms.date: 09/21/2026 ms.topic: reference title: Microsoft.PowerShell.PSResourceGet/PSResourceList --- @@ -55,12 +55,12 @@ can: The resource wraps the `Get-InstalledPSResource`, `Install-PSResource`, and `Uninstall-PSResource` cmdlets. Packages are modules or scripts and are installed to the same locations the cmdlets use, -so they are available to every PowerShell session for the selected scope. +so they're available to every PowerShell session for the selected scope. > [!NOTE] > This resource is installed with the **Microsoft.PowerShell.PSResourceGet** module. DSC discovers > it from `PSModulePath`, so you don't need to add the module folder to `PATH`. For more -> information, see [How DSC discovers the resources][01]. +> information, see [How DSC discovers the resources][05]. ## Requirements @@ -68,11 +68,11 @@ so they are available to every PowerShell session for the selected scope. - **Microsoft.PowerShell.PSResourceGet** 1.3.0-preview1 or later must be installed. - The repository named in `repositoryName` must be registered for the user that runs `dsc`. You can register it in the same configuration document with the - [Microsoft.PowerShell.PSResourceGet/Repository][02] resource. + [Microsoft.PowerShell.PSResourceGet/Repository][26] resource. - To install packages with the `AllUsers` scope, `dsc` must run in an elevated process. - Installing packages requires access to the repository. Private repositories must have a persisted credential configured. For more information, see - [How to add credentials to repositories with PSResourceGet][03]. + [How to add credentials to repositories with PSResourceGet][01]. ## Capabilities @@ -87,13 +87,13 @@ The resource has the following capabilities: in the desired state. - `export` - You can use the resource to enumerate every installed package on the machine. -For more information about resource capabilities, see [DSC resource capabilities][04]. +For more information about resource capabilities, see [DSC resource capabilities][07]. ## Examples -1. [Invoke the PSResourceGet DSC resources directly][05] - Shows how to get, test, set, and export +1. [Invoke the PSResourceGet DSC resources directly][03] - Shows how to get, test, set, and export package lists with the `dsc resource` commands. -1. [Manage packages with a DSC configuration document][06] - Shows how to declare repositories and +1. [Manage packages with a DSC configuration document][02] - Shows how to declare repositories and packages in a configuration document and preview changes with `--what-if`. ## Properties @@ -103,20 +103,19 @@ The following list describes the properties for the resource. - **Required properties:** The following properties are always required when defining an instance of the resource. - - [repositoryName](#repositoryname) - The repository to install the packages from. + - [repositoryName][20] - The repository to install the packages from. - **Instance properties:** The following properties are optional. They define the desired state for an instance of the resource. - - [trustedRepository](#trustedrepository) - Whether to install from the repository even when - it isn't trusted. - - [resources](#resources) - The list of packages to manage. + - [trustedRepository][24] - Whether to install from the repository even when it isn't trusted. + - [resources][21] - The list of packages to manage. - **Read-only properties:** The resource returns the following - properties, but they aren't configurable. For more information about read-only properties, see - the "Read-only resource properties" section in [DSC resource properties][07]. + properties, but they aren't configurable. For more information about read-only properties, see the + _Read-only resource properties_ section in [DSC resource properties][08]. - - [_inDesiredState](#_indesiredstate) - Whether the list is in the desired state. + - [_inDesiredState][10] - Whether the list is in the desired state. ### repositoryName @@ -128,8 +127,11 @@ IsReadOnly : false ``` Defines the name of the registered repository to install the packages from. The resource only -considers packages whose installation metadata records this repository. A package with the same -name that was installed from a different repository is reported as not installed. +considers packages whose installation metadata matches this repository. + +> [!IMPORTANT] +> A package with the same name that was installed from a different repository is reported as not +> installed. When the repository isn't registered, the **Get** and **Test** operations report every package in the list as not installed, and the **Set** operation fails with exit code `2`. @@ -145,13 +147,12 @@ DefaultValue : false ``` Defines whether the resource can install packages from the repository when the repository isn't -registered as trusted. When the value is `true`, the resource installs packages as if you passed -the **TrustRepository** parameter to `Install-PSResource`. When the value is `false` and the -repository isn't trusted, the **Set** operation fails with exit code `3` instead of installing -anything. +registered as trusted. When the value is `true`, the resource installs packages as if you passed the +**TrustRepository** parameter to `Install-PSResource`. When the value is `false` and the repository +isn't trusted, the **Set** operation fails with exit code `3` instead of installing anything. -This property doesn't change the trust setting of the repository. To trust a repository -permanently, use the [Microsoft.PowerShell.PSResourceGet/Repository][02] resource. +This property doesn't change the trust setting of the repository. To trust a repository permanently, +use the [Microsoft.PowerShell.PSResourceGet/Repository][26] resource. ### resources @@ -164,18 +165,18 @@ ItemsMinimumCount : 0 ``` Defines the list of packages to manage. Each entry is an object that describes one package. The -**Get** and **Test** operations return one entry for every entry you define, in the same order. -The **Export** operation returns one entry for every installed package. +**Get** and **Test** operations return one entry for every entry you define, in the same order. The +**Export** operation returns one entry for every installed package. Each entry in `resources` has the following properties: -- [name](#name) - The name of the package. -- [version](#version) - The version or version range of the package. -- [scope](#scope) - Where the package is installed. -- [repositoryName](#resourcesrepositoryname) - The repository the package was installed from. -- [preRelease](#prerelease) - Whether to install prerelease versions. -- [_exist](#_exist) - Whether the package should be installed. -- [_metadata](#_metadata) - Messages returned in what-if mode. +- [name][18] - The name of the package +- [version][25] - The version or version range of the package +- [scope][23] - Where the package is installed +- [repositoryName][22] - The repository the package was installed from +- [preRelease][19] - Whether to install prerelease versions +- [_exist][09] - Whether the package should be installed +- [_metadata][11] - Messages returned in what-if mode #### name @@ -186,9 +187,9 @@ IsKey : true IsReadOnly : false ``` -Defines the name of the package. The value is compared without regard to case. The same package -name can appear more than once in the list when each entry has a different `version` or -`preRelease` value, for example to install a stable and a prerelease version side by side. +Defines the name of the package. The value is compared without regard to case. The same package name +can appear more than once in the list when each entry has a different `version` or `preRelease` +value, for example to install a stable and a prerelease version side by side. #### version @@ -199,14 +200,14 @@ IsKey : false IsReadOnly : false ``` -Defines the version or version range of the package, using the [NuGet version range syntax][08]. +Defines the version or version range of the package, using the [NuGet version range syntax][06]. When you don't define this property, the resource installs the latest version and treats any installed version as satisfying the desired state. The resource uses the value in two ways: -- The **Get** and **Test** operations check whether an installed version _satisfies_ the value as - a NuGet version range. A bare version like `2.0.0` is treated as the range `[2.0.0, )`, so any +- The **Get** and **Test** operations check whether an installed version _satisfies_ the value as a + NuGet version range. A bare version like `2.0.0` is treated as the range `[2.0.0, )`, so any installed version equal to or newer than `2.0.0` satisfies it. - The **Set** operation passes the value to the **Version** parameter of `Install-PSResource`. A bare version like `2.0.0` installs exactly that version. @@ -224,8 +225,8 @@ syntax `[2.0.0]`. The following table shows common values. When more than one version of the package is installed, the **Get** operation returns the version that satisfies the range. When no installed version satisfies the range, the **Get** operation -returns the installed version it found with `_exist` set to `false`, so you can see which version -is on the machine. For prerelease versions, the returned value includes the prerelease label, like +returns the installed version it found with `_exist` set to `false`, so you can see which version is +on the machine. For prerelease versions, the returned value includes the prerelease label, like `2.0.0-preview1`. #### scope @@ -240,8 +241,8 @@ DefaultValue : CurrentUser ``` Defines the scope to install the package in. `CurrentUser` installs the package to the module or -script path for the current user. `AllUsers` installs the package to the shared path for every -user and requires an elevated process. The default value is `CurrentUser`. +script path for the current user. `AllUsers` installs the package to the shared path for every user +and requires an elevated process. The default value is `CurrentUser`. The **Get** operation searches both scopes and returns the scope where it found the package. Packages installed for the current user are found before packages installed for all users. @@ -259,8 +260,8 @@ IsReadOnly : false The name of the repository the package was installed from. The **Get** and **Export** operations return this property for every installed package. You don't need to define it in the desired state. -When you do, the value must match the [repositoryName](#repositoryname) of the list, otherwise the -**Test** operation reports the package as out of the desired state. +When you do, the value must match the [repositoryName][20] of the list, otherwise the **Test** +operation reports the package as out of the desired state. #### preRelease @@ -277,8 +278,8 @@ Defines whether the resource may install a prerelease version of the package. Wh `Install-PSResource`. Combine this property with a `version` range that includes prerelease versions, like `[3.0.0-preview1, )`, to install a specific prerelease. -The **Get** and **Export** operations return `true` for this property when the installed version -is a prerelease version. +The **Get** and **Export** operations return `true` for this property when the installed version is +a prerelease version. #### _exist @@ -307,16 +308,19 @@ IsKey : false IsReadOnly : true ``` -This property is returned for entries the resource would change during a **Set** operation invoked -in what-if mode. For other operations, and for entries that are already in the desired state, the +DSC returns this property for entries the resource would change during a **Set** operation invoked +in what-if mode. For other operations and for entries that are already in the desired state, the return data doesn't include this property. -`_metadata` has the following properties: +`_metadata` has one property: + +- **whatIf** - An array of strings. Each string describes an action the resource would take. For + example: + + - `Would install resource 'PSScriptAnalyzer' version '1.24.0'` + - `Would uninstall resource 'Pester'` -- **whatIf** - An array of strings. Each string describes an action the resource would take, like - `Would install resource 'PSScriptAnalyzer' version '1.24.0'` or - `Would uninstall resource 'Pester'`. When the resource would install the latest version, the - message reports the version as `latest`. + When the resource would install the latest version, the message reports the version as `latest`. ### _inDesiredState @@ -332,13 +336,13 @@ desired state. An entry is in the desired state when its installed state matches installed version satisfies `version`, and the installed `scope` and `repositoryName` match the values you defined. -The resource also returns this property for every entry in `resources`. Only the top-level value -is meaningful. The per-entry value is always `false`. +The resource also returns this property for every entry in `resources`. Only the top-level value is +meaningful. The per-entry value is always `false`. -When the list is in the desired state, the `actualState` returned by the **Test** operation -contains the installed packages. When the list isn't in the desired state, the `actualState` -contains the entries you defined, with default values filled in, rather than the installed -packages. To see which versions are installed in that case, use the **Get** operation. +When the list is in the desired state, the `actualState` returned by the **Test** operation contains +the installed packages. When the list isn't in the desired state, the `actualState` contains the +entries you defined, with default values filled in, rather than the installed packages. To see which +versions are installed in that case, use the **Get** operation. ## Instance validating schema @@ -389,12 +393,12 @@ non-validating keywords are omitted. The resource returns the following exit codes from operations: -- [0](#exit-code-0) - Success -- [1](#exit-code-1) - Error -- [2](#exit-code-2) - Repository not found -- [3](#exit-code-3) - Repository not trusted -- [4](#exit-code-4) - Could not install one or more packages -- [12](#exit-code-12) - Unknown operation +- [0][12] - Success +- [1][13] - Error +- [2][15] - Repository not found +- [3][16] - Repository not trusted +- [4][17] - Could not install one or more packages +- [12][14] - Unknown operation ### Exit code 0 @@ -403,21 +407,21 @@ Indicates the resource operation completed without errors. ### Exit code 1 Indicates the resource operation failed with an unhandled error. The resource writes a JSON error -message to stderr with the details. Common causes include invalid input JSON or a cmdlet that -raised a terminating error, for example when `Uninstall-PSResource` can't remove a package -because another module depends on it. +message to stderr with the details. Common causes include invalid input JSON or a cmdlet that raised +a terminating error, for example when `Uninstall-PSResource` can't remove a package because another +module depends on it. ### Exit code 2 Indicates the **Set** operation couldn't install packages because no repository with the name defined in `repositoryName` is registered. Register the repository, for example with the -[Microsoft.PowerShell.PSResourceGet/Repository][02] resource, and retry the operation. +[Microsoft.PowerShell.PSResourceGet/Repository][26] resource, and retry the operation. ### Exit code 3 Indicates the **Set** operation couldn't install packages because the repository isn't trusted and `trustedRepository` isn't `true`. Set `trustedRepository` to `true` in the desired state, or trust -the repository with the [Microsoft.PowerShell.PSResourceGet/Repository][02] resource. +the repository with the [Microsoft.PowerShell.PSResourceGet/Repository][26] resource. ### Exit code 4 @@ -434,22 +438,39 @@ occur when you invoke the resource through DSC. ## See also -- [Microsoft.PowerShell.PSResourceGet/Repository][02] -- [Manage PowerShell packages with Microsoft DSC][09] -- [Install-PSResource][10] -- [Uninstall-PSResource][11] -- [Get-InstalledPSResource][12] +- [Microsoft.PowerShell.PSResourceGet/Repository][26] +- [Manage PowerShell packages with Microsoft DSC][04] +- [Install-PSResource][28] +- [Uninstall-PSResource][29] +- [Get-InstalledPSResource][27] -[01]: ../overview.md#how-dsc-discovers-the-resources -[02]: repository.md -[03]: ../../how-to/credential-persistence.md -[04]: /powershell/dsc/concepts/resources/capabilities?view=dsc-3.0&preserve-view=true -[05]: ../how-to/invoke-resources.md -[06]: ../how-to/configuration-documents.md -[07]: /powershell/dsc/concepts/resources/properties?view=dsc-3.0&preserve-view=true#read-only-resource-properties -[08]: /nuget/concepts/package-versioning?tabs=semver20sort#version-ranges -[09]: ../overview.md -[10]: xref:Microsoft.PowerShell.PSResourceGet.Install-PSResource -[11]: xref:Microsoft.PowerShell.PSResourceGet.Uninstall-PSResource -[12]: xref:Microsoft.PowerShell.PSResourceGet.Get-InstalledPSResource +[01]: ../../how-to/credential-persistence.md +[02]: ../how-to/configuration-documents.md +[03]: ../how-to/invoke-resources.md +[04]: ../overview.md +[05]: ../overview.md#how-dsc-discovers-the-resources +[06]: /nuget/concepts/package-versioning?tabs=semver20sort#version-ranges +[07]: /powershell/dsc/concepts/resources/capabilities?view=dsc-3.0&preserve-view=true +[08]: /powershell/dsc/concepts/resources/properties?view=dsc-3.0&preserve-view=true#read-only-resource-properties +[09]: #_exist +[10]: #_indesiredstate +[11]: #_metadata +[12]: #exit-code-0 +[13]: #exit-code-1 +[14]: #exit-code-12 +[15]: #exit-code-2 +[16]: #exit-code-3 +[17]: #exit-code-4 +[18]: #name +[19]: #prerelease +[20]: #repositoryname +[21]: #resources +[22]: #resourcesrepositoryname +[23]: #scope +[24]: #trustedrepository +[25]: #version +[26]: repository.md +[27]: xref:Microsoft.PowerShell.PSResourceGet.Get-InstalledPSResource +[28]: xref:Microsoft.PowerShell.PSResourceGet.Install-PSResource +[29]: xref:Microsoft.PowerShell.PSResourceGet.Uninstall-PSResource diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md index 13ee70e..21458b1 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md @@ -1,6 +1,6 @@ --- description: Microsoft.PowerShell.PSResourceGet/Repository DSC resource reference documentation -ms.date: 09/12/2026 +ms.date: 09/21/2026 ms.topic: reference title: Microsoft.PowerShell.PSResourceGet/Repository --- @@ -42,26 +42,26 @@ The `Microsoft.PowerShell.PSResourceGet/Repository` resource enables you to idem the repositories that **Microsoft.PowerShell.PSResourceGet** installs packages from. The resource can: -- Register a repository that doesn't exist. -- Update the URI, trust setting, priority, or API type of an existing repository. -- Unregister a repository. -- Export every registered repository as a configuration document. +- Register a repository that doesn't exist +- Update the URI, trust setting, priority, or API type of an existing repository +- Unregister a repository +- Export every registered repository as a configuration document The resource wraps the `Get-PSResourceRepository`, `Register-PSResourceRepository`, `Set-PSResourceRepository`, and `Unregister-PSResourceRepository` cmdlets. It manages the same -repository store those cmdlets use, so changes made with the resource are visible to interactive -sessions and the other way around. +repository store those cmdlets use, so changes made with the resource are visible to DSC and +interactive sessions. > [!NOTE] > This resource is installed with the **Microsoft.PowerShell.PSResourceGet** module. DSC discovers > it from `PSModulePath`, so you don't need to add the module folder to `PATH`. For more -> information, see [How DSC discovers the resources][01]. +> information, see [How DSC discovers the resources][05]. ## Requirements - PowerShell 7.2 or later must be available as `pwsh` in the `PATH` environment variable. - **Microsoft.PowerShell.PSResourceGet** 1.3.0-preview1 or later must be installed. -- The repository store is per user. The resource manages the repositories for the user account +- Since repository stores are per user, the resource manages the repositories for the user account that runs `dsc`. ## Capabilities @@ -76,7 +76,7 @@ The resource has the following capabilities: This resource uses the synthetic test functionality of DSC to determine whether an instance is in the desired state. DSC compares each property you define in the desired state with the value the resource returns from the **Get** operation. For more information about resource capabilities, see -[DSC resource capabilities][02]. +[DSC resource capabilities][06]. > [!TIP] > The resource returns the `uri` property in the normalized form that @@ -88,7 +88,7 @@ resource returns from the **Get** operation. For more information about resource 1. [Invoke the PSResourceGet DSC resources directly][03] - Shows how to get, set, delete, and export repositories with the `dsc resource` commands. -1. [Manage packages with a DSC configuration document][04] - Shows how to register a repository +1. [Manage packages with a DSC configuration document][02] - Shows how to register a repository and install packages from it in a single configuration document. ## Properties @@ -98,16 +98,16 @@ The following list describes the properties for the resource. - **Required properties:** The following properties are always required when defining an instance of the resource. - - [name](#name) - The name of the repository. - - [uri](#uri) - The location of the repository. Required unless `_exist` is `false`. + - [name][11] - The name of the repository. + - [uri][15] - The location of the repository. Required unless `_exist` is `false`. - **Instance properties:** The following properties are optional. They define the desired state for an instance of the resource. - - [trusted](#trusted) - Whether packages can be installed from the repository without a prompt. - - [priority](#priority) - The search order of the repository relative to other repositories. - - [repositoryType](#repositorytype) - The API type of the repository. - - [_exist](#_exist) - Whether the repository should be registered. + - [trusted][14] - Whether packages can be installed from the repository without a prompt. + - [priority][12] - The search order of the repository relative to other repositories. + - [repositoryType][13] - The API type of the repository. + - [_exist][07] - Whether the repository should be registered. ### name @@ -134,7 +134,7 @@ Format : uri Defines the location of the repository. The value can be an HTTPS URL, a file system path, or the URL of a container registry. For more information about the repository types that -**Microsoft.PowerShell.PSResourceGet** supports, see [PSResourceGet supported repositories][05]. +**Microsoft.PowerShell.PSResourceGet** supports, see [PSResourceGet supported repositories][01]. When `_exist` is `false`, this property is optional. The **Get** operation returns `null` for this property when the repository isn't registered. @@ -152,7 +152,7 @@ Defines whether the repository is trusted. When a repository is trusted, `Instal installs packages from it without prompting for confirmation. When you register a repository with the resource and don't define this property, the repository is registered as untrusted. -The [Microsoft.PowerShell.PSResourceGet/PSResourceList][06] resource can only install packages +The [Microsoft.PowerShell.PSResourceGet/PSResourceList][16] resource can only install packages from an untrusted repository when its `trustedRepository` property is `true`. ### priority @@ -184,16 +184,16 @@ Defines the API type of the repository. The value maps to the **ApiVersion** par `Register-PSResourceRepository` and `Set-PSResourceRepository`. When you don't define this property, **Microsoft.PowerShell.PSResourceGet** detects the API type from the URI. -The following table describes the valid values. +The **ApiVersion** property of a repository can have the following values. -| Value | Description | -|:--------------------|:-------------------------------------------------------------------------------------------------------------------| -| `V2` | A NuGet v2 API feed, like the PowerShell Gallery. | -| `V3` | A NuGet v3 API feed. | -| `Local` | A folder on the file system or a network share. | -| `NugetServer` | A NuGet.Server instance. | -| `ContainerRegistry` | An OCI container registry, like Azure Container Registry or the Microsoft Artifact Registry. | -| `Unknown` | Returned by the **Get** operation when the repository isn't registered. Don't use this value in the desired state. | +- `V2` - A NuGet v2 API feed, like the PowerShell Gallery. +- `V3` - A NuGet v3 API feed. +- `Local` - A folder on the file system or a network share. +- `NugetServer` - A NuGet.Server instance. +- `ContainerRegistry` - An OCI container registry, like Azure Container Registry or the Microsoft + Artifact Registry. +- `Unknown` - Returned by the **Get** operation when the repository isn't registered. Don't use this + value in the desired state. ### _exist @@ -251,9 +251,9 @@ non-validating keywords are omitted. The resource returns the following exit codes from operations: -- [0](#exit-code-0) - Success -- [1](#exit-code-1) - Error -- [12](#exit-code-12) - Unknown operation +- [0][08] - Success +- [1][09] - Error +- [12][10] - Unknown operation ### Exit code 0 @@ -276,19 +276,28 @@ occur when you invoke the resource through DSC. ## See also -- [Microsoft.PowerShell.PSResourceGet/PSResourceList][06] -- [Manage PowerShell packages with Microsoft DSC][07] -- [Register-PSResourceRepository][08] -- [Set-PSResourceRepository][09] -- [PSResourceGet supported repositories][05] +- [Microsoft.PowerShell.PSResourceGet/PSResourceList][16] +- [Manage PowerShell packages with Microsoft DSC][04] +- [Register-PSResourceRepository][17] +- [Set-PSResourceRepository][18] +- [PSResourceGet supported repositories][01] -[01]: ../overview.md#how-dsc-discovers-the-resources -[02]: /powershell/dsc/concepts/resources/capabilities?view=dsc-3.0&preserve-view=true +[01]: ../../supported-repositories.md +[02]: ../how-to/configuration-documents.md [03]: ../how-to/invoke-resources.md -[04]: ../how-to/configuration-documents.md -[05]: ../../supported-repositories.md -[06]: psresourcelist.md -[07]: ../overview.md -[08]: xref:Microsoft.PowerShell.PSResourceGet.Register-PSResourceRepository -[09]: xref:Microsoft.PowerShell.PSResourceGet.Set-PSResourceRepository +[04]: ../overview.md +[05]: ../overview.md#how-dsc-discovers-the-resources +[06]: /powershell/dsc/concepts/resources/capabilities?view=dsc-3.0&preserve-view=true +[07]: #_exist +[08]: #exit-code-0 +[09]: #exit-code-1 +[10]: #exit-code-12 +[11]: #name +[12]: #priority +[13]: #repositorytype +[14]: #trusted +[15]: #uri +[16]: psresourcelist.md +[17]: xref:Microsoft.PowerShell.PSResourceGet.Register-PSResourceRepository +[18]: xref:Microsoft.PowerShell.PSResourceGet.Set-PSResourceRepository From 264e2aa61d42d9be7e3470dd87467c9c3b1f5c4e Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 21 Sep 2026 14:14:12 -0500 Subject: [PATCH 4/5] fix typos --- .../docs-conceptual/powershellget/dsc/overview.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md b/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md index b258a95..e1e06f2 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/overview.md @@ -21,11 +21,11 @@ you use interactively, such as `Register-PSResourceRepository` and `Install-PSRe The [Microsoft.PowerShell.PSResourceGet/Repository][12] resource manages a registered package repository: name, URI, trust, priority, and API type. This resource supports the `get`, `set`, -`delete`, and `export` operations. The +`delete`, and `export` operations. The [Microsoft.PowerShell.PSResourceGet/PSResourceList][11] resource manages a list of packages that -should, or shouldn't, be installed from one repository. This PSResourceList** resource supports the -`get`, `set`, `test`, `export`, and `whatIf` operations. +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][04]. From 0aa8e3089cc74aad290a577a6e9dca45c8a4c749 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 21 Sep 2026 14:24:32 -0500 Subject: [PATCH 5/5] Fixing Copilot suggestion --- .../docs-conceptual/powershellget/dsc/reference/repository.md | 1 + 1 file changed, 1 insertion(+) diff --git a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md index 21458b1..e15b195 100644 --- a/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md +++ b/powershell-gallery/docs-conceptual/powershellget/dsc/reference/repository.md @@ -227,6 +227,7 @@ non-validating keywords are omitted. "allOf": [ { "if": { + "required": ["_exist"], "properties": { "_exist": { "const": false } } }, "then": { "required": ["name"] },