DSC v3 resource for PSResourceGet

[adityapatwardhan]

PR Summary

The initial implementation of DSC v3 resource for PSResourceGet. It include two resources, Repository and PSResources.

PR Context

PR Checklist

• PR has a meaningful title
  • Use the present tense and imperative mood when describing your changes
• Summarized changes
• Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• This PR is ready to merge and is not Work in Progress.
  • If the PR is work in progress, please add the prefix WIP: or [ WIP ] to the beginning of the title (the WIP bot will keep its status check at Pending while the prefix is present) and remove the prefix when the PR is ready.
• Breaking changes
  • None
  • OR
  • Documentation needed
    • Issue filed:
• User-facing changes
  • Not Applicable
  • OR
  • Documentation needed
    • Issue filed:
• Testing - New and feature
  • N/A or can only be tested interactively
  • OR
  • Make sure you've added a new test if existing tests do not effectively test the code changed
• Tooling
  • I have considered the user experience from a tooling perspective and don't believe tooling will be impacted.
  • OR
  • I have considered the user experience from a tooling perspective and enumerated concerns in the summary.

[michaeltlombardi]

Quick review pass on the manifests, looking at resource implementation next.

[michaeltlombardi]

A few more comments on the schema and implementation.

[ThomasNieto]

Is the plan to add a discover extension in DSC to be able to find these resource manifests? If so, is there an issue/pr for that?

[michaeltlombardi]

Is the plan to add a discover extension in DSC to be able to find these resource manifests? If so, is there an issue/pr for that?

@ThomasNieto yup! PowerShell/DSC#913 proposes a discovery extension for finding resource and extension manifests through the PSModulePath.

[ThomasNieto]

I logged PowerShell/DSC#1024 issue. PSResourceGet will also have the same issue since it uses NuGet version range syntax containing square brackets.

[Gijsreyn]

@adityapatwardhan - I think you've followed the news, but you should be able to define a single resource manifest now e.g.,:

// psresourceget.dsc.manifests.json
{
  "resources": [
    {
      "$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json",
      "description": "Manage PowerShell resources using PSResourceGet.",
      "tags": [
        "linux",
        "windows",
        "macos",
        "powershell",
        "nuget"
      ],
      "type": "Microsoft.PowerShell.PSResourceGet/PSResourceList",
      "version": "0.0.1",
      "get": {
        "executable": "pwsh",
        "args": [
          "-NoLogo",
          "-NonInteractive",
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-Command",
          "$Input | ./psresourceget.ps1 -resourcetype 'psresourcelist' -operation 'get'"
        ],
        "input": "stdin"
      },
      "set": {
        "executable": "pwsh",
        "args": [
          "-NoLogo",
          "-NonInteractive",
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-Command",
          "$Input | ./psresourceget.ps1 -resourcetype 'psresourcelist' -operation set"
        ],
        "input": "stdin",
        "return": "stateAndDiff"
      },
      "export": {
        "executable": "pwsh",
        "args": [
          "-NoLogo",
          "-NonInteractive",
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-Command",
          "./psresourceget.ps1 -resourcetype 'psresourcelist' -operation export"
        ],
        "input": "stdin"
      },
      "test": {
        "executable": "pwsh",
        "args": [
          "-NoLogo",
          "-NonInteractive",
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-Command",
          "$Input | ./psresourceget.ps1 -resourcetype 'psresourcelist' -operation test"
        ],
        "input": "stdin",
        "return": "stateAndDiff"
      },
      "schema": {
        "embedded": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "PSResourceList",
          "type": "object",
          "additionalProperties": false,
          "required": [
            "repositoryName"
          ],
          "properties": {
            "repositoryName": {
              "title": "Repository Name",
              "description": "The name of the repository from where the resources are acquired.",
              "type": "string"
            },
            "resources": {
              "title": "Resources",
              "description": "The list of resources to manage.",
              "type": "array",
              "items": {
                "$ref": "#/$defs/PSResource"
              },
              "minItems": 0
            },
            "_exist": {
              "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json"
            },
            "_inDesiredState": {
              "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/inDesiredState.json"
            }
          },
          "$defs": {
            "Scope": {
              "type": "string",
              "title": "Scope",
              "description": "Scope of the resource installation.",
              "enum": [
                "CurrentUser",
                "AllUsers"
              ]
            },
            "PSResource": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "name"
              ],
              "properties": {
                "name": {
                  "title": "Name",
                  "description": "The name of the resource.",
                  "type": "string"
                },
                "version": {
                  "title": "Version",
                  "description": "The version range of the resource.",
                  "type": "string",
                  "pattern": "^(\\[|\\()\\s*\\d+(\\.\\d+){0,2}(-[0-9A-Za-z-.]+)?\\s*(,\\s*(\\d+(\\.\\d+){0,2}(-[0-9A-Za-z-.]+)?)?\\s*(\\]|\\)))?$"
                },
                "scope": {
                  "title": "Scope",
                  "description": "The scope of the resource. Can be 'CurrentUser' or 'AllUsers'.",
                  "$ref": "#/$defs/Scope"
                },
                "repositoryName": {
                  "title": "Repository Name",
                  "description": "The name of the repository from where the resource is acquired.",
                  "type": "string"
                },
                "preRelease": {
                  "title": "Pre-Release version",
                  "description": "Indicates whether to include pre-release versions of the resource.",
                  "type": "boolean",
                  "default": false
                },
                "_exist": {
                  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json"
                },
                "_inDesiredState": {
                  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/inDesiredState.json"
                }
              }
            },
            "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json": {
              "$schema": "https://json-schema.org/draft/2020-12/schema",
              "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json",
              "title": "Instance should exist",
              "description": "Indicates whether the DSC resource instance should exist.",
              "type": "boolean",
              "default": true,
              "enum": [
                false,
                true
              ]
            },
            "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/inDesiredState.json": {
              "$schema": "https://json-schema.org/draft/2020-12/schema",
              "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/inDesiredState.json",
              "title": "Instance is in desired state",
              "description": "Indicates whether the DSC resource instance is in the desired state.",
              "type": "boolean",
              "default": true,
              "enum": [
                false,
                true
              ]
            }
          }
        }
      }
    },
    {
      "$schema": "https://aka.ms/dsc/schemas/v3/bundled/resource/manifest.json",
      "description": "Manage PowerShell repositories using PSResourceGet.",
      "tags": [
        "linux",
        "windows",
        "macos",
        "powershell",
        "nuget"
      ],
      "type": "Microsoft.PowerShell.PSResourceGet/Repository",
      "version": "0.0.1",
      "get": {
        "executable": "pwsh",
        "args": [
          "-NoLogo",
          "-NonInteractive",
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-Command",
          "$Input | ./psresourceget.ps1 -resourcetype 'repository' -operation 'get'"
        ],
        "input": "stdin"
      },
      "set": {
        "executable": "pwsh",
        "args": [
          "-NoLogo",
          "-NonInteractive",
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-Command",
          "$Input | ./psresourceget.ps1 -resourcetype 'repository' -operation set"
        ],
        "input": "stdin"
      },
      "delete": {
        "executable": "pwsh",
        "args": [
          "-NoLogo",
          "-NonInteractive",
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-Command",
          "$Input | ./psresourceget.ps1 -resourcetype 'repository' -operation delete"
        ],
        "input": "stdin"
      },
      "export": {
        "executable": "pwsh",
        "args": [
          "-NoLogo",
          "-NonInteractive",
          "-NoProfile",
          "-ExecutionPolicy",
          "Bypass",
          "-Command",
          "./psresourceget.ps1 -resourcetype 'repository' -operation export"
        ],
        "input": "stdin"
      },
      "schema": {
        "embedded": {
          "$schema": "https://json-schema.org/draft/2020-12/schema",
          "title": "Repository",
          "description": "A PowerShell Resource repository from where to acquire the resources.",
          "type": "object",
          "additionalProperties": false,
          "allOf": [
            {
              "if": {
                "properties": {
                  "_exist": {
                    "const": false
                  }
                }
              },
              "then": {
                "required": [
                  "name"
                ]
              },
              "else": {
                "required": [
                  "name",
                  "uri"
                ]
              }
            }
          ],
          "properties": {
            "name": {
              "title": "Name",
              "description": "The name of the repository.",
              "type": "string"
            },
            "uri": {
              "title": "URI",
              "description": "The URI of the repository.",
              "type": "string",
              "format": "uri"
            },
            "trusted": {
              "title": "Trusted",
              "description": "Indicates whether the repository is trusted.",
              "type": "boolean"
            },
            "priority": {
              "title": "Priority",
              "description": "The priority of the repository. Lower numbers indicate higher priority.",
              "type": "integer",
              "minimum": 0,
              "maximum": 100
            },
            "repositoryType": {
              "title": "Repository Type",
              "description": "The type of the repository.",
              "$ref": "#/$defs/RepositoryType"
            },
            "_exist": {
              "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json"
            }
          },
          "$defs": {
            "RepositoryType": {
              "type": "string",
              "title": "Repository Type",
              "description": "The type of the repository. Can be 'Unknown', 'V2', 'V3', 'Local', 'NugetServer', or 'ContainerRegistry'.",
              "enum": [
                "Unknown",
                "V2",
                "V3",
                "Local",
                "NugetServer",
                "ContainerRegistry"
              ]
            },
            "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json": {
              "$schema": "https://json-schema.org/draft/2020-12/schema",
              "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3/resource/properties/exist.json",
              "title": "Instance should exist",
              "description": "Indicates whether the DSC resource instance should exist.",
              "type": "boolean",
              "default": true,
              "enum": [
                false,
                true
              ]
            }
          }
        }
      }
    }
  ]
}

[Gijsreyn]

I think the pattern for version should also slightly change to:

"pattern": "^((\\[|\\()[ \\t]*(>=|>|<=|<)?[ \\t]*\\d+(\\.\\d+){0,2}(-[0-9A-Za-z-.]+)?[ \\t]*(,[ \\t]*(>=|>|<=|<)?[ \\t]*(\\d+(\\.\\d+){0,2}(-[0-9A-Za-z-.]+)?)?[ \\t]*)?(\\]|\\))|\\d+(\\.\\d+){0,2}(-[0-9A-Za-z-.]+)?)$"

[adityapatwardhan]

@Gijsreyn - thanks for your comments. I would still maybe want to keep it separate files for two resources. Easier to understand. What do others think?

Also, I removed the pattern validation for the NuGet version ranges. It can get really unwieldy and difficult to maintain.

[adityapatwardhan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[adityapatwardhan]

Close / Re-Open to re-kick off pipelines.

[adityapatwardhan]

@Gijsreyn this does not use the adapter so have to keep Write-Trace style

[adityapatwardhan]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[Gijsreyn]

@adityapatwardhan - my bad Aditya. Should have seen the resource manifest.