PSRepository: New DSC resource

CHANGELOG.md

@@ -5,7 +5,7 @@
 - Made the list entries in the CHANGELOG.md to use dash `-` throughout to
   be consequent (before there was a mix of dashes and asterisk).
 - Update the AppVeyor CI test pipeline with a new job to run tests for
-  the DSC resources, primarily for the resource `PSModule`.
+  the DSC resources.
   The new job uses the test framework used for the DSC Resource Kit,
   the [DscResource.Tests](https://github.com/PowerShell/DscResource.Tests) repository.
 - Update .gitignore to ignore the [DscResource.Tests](https://github.com/PowerShell/DscResource.Tests)
@@ -41,9 +41,9 @@
   - Refactored the Get-TargetResource to return the correct hash table
     when the current state is absent.
   - Added new examples.
-- Changed the AppVeyor CI build pipeline so it added the DSC resource
-  `PSModule` and dependent helper modules (the `Modules` folder) to the
-  AppVeyor artifact.
+- Changed the AppVeyor CI build pipeline so it adds the DSC resources
+  and dependent helper modules (the `Modules` folder) to the AppVeyor
+  artifact.
 - Added the `.MetaTestOptIn.json` file to opt-in for a lot of common test
   in the DscResource.Tests test framework that tests the DSC resources.
 - The examples under the folder `DSC/Examples` will be [published to PowerShell Gallery](https://github.com/PowerShell/DscResource.Tests#publish-examples-to-powershell-gallery)
@@ -57,7 +57,7 @@
   - In the file `appveyor.yml` the PowerShell Gallery API key was added
     for the account 'dscresourcekit', which can only be decrypted using
     the PowerShell AppVeyor account.
-
+- Added DSC resource PSRepository.
 
 ## 2.0.4
 

DSC/DSCResources/MSFT_PSRepository/MSFT_PSRepository.psm1

@@ -0,0 +1,308 @@
+$resourceModuleRoot = Split-Path -Path (Split-Path -Path $PSScriptRoot -Parent) -Parent
+
+# Import localization helper functions.
+$helperName = 'PowerShellGet.LocalizationHelper'
+$dscResourcesFolderFilePath = Join-Path -Path $resourceModuleRoot -ChildPath "Modules\$helperName\$helperName.psm1"
+Import-Module -Name $dscResourcesFolderFilePath
+
+$script:localizedData = Get-LocalizedData -ResourceName 'MSFT_PSRepository' -ScriptRoot $PSScriptRoot
+
+# Import resource helper functions.
+$helperName = 'PowerShellGet.ResourceHelper'
+$dscResourcesFolderFilePath = Join-Path -Path $resourceModuleRoot -ChildPath "Modules\$helperName\$helperName.psm1"
+Import-Module -Name $dscResourcesFolderFilePath
+
+<#
+    .SYNOPSIS
+        Returns the current state of the repository.
+
+    .PARAMETER Name
+        Specifies the name of the repository to manage.
+#>
+function Get-TargetResource {
+    <#
+        These suppressions are added because this repository have other Visual Studio Code workspace
+        settings than those in DscResource.Tests DSC test framework.
+        Only those suppression that contradict this repository guideline is added here.
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('DscResource.AnalyzerRules\Measure-FunctionBlockBraces', '')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('DscResource.AnalyzerRules\Measure-IfStatement', '')]
+    [CmdletBinding()]
+    [OutputType([System.Collections.Hashtable])]
+    param
+    (
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name
+    )
+
+    $returnValue = @{
+        Ensure                    = 'Absent'
+        Name                      = $Name
+        SourceLocation            = $null
+        ScriptSourceLocation      = $null
+        PublishLocation           = $null
+        ScriptPublishLocation     = $null
+        InstallationPolicy        = $null
+        PackageManagementProvider = $null
+        Trusted                   = $false
+        Registered                = $false
+    }
+
+    Write-Verbose -Message ($localizedData.GetTargetResourceMessage -f $Name)
+
+    $repository = Get-PSRepository -Name $Name -ErrorAction 'SilentlyContinue'
+
+    if ($repository) {
+        $returnValue.Ensure = 'Present'
+        $returnValue.SourceLocation = $repository.SourceLocation
+        $returnValue.ScriptSourceLocation = $repository.ScriptSourceLocation
+        $returnValue.PublishLocation = $repository.PublishLocation
+        $returnValue.ScriptPublishLocation = $repository.ScriptPublishLocation
+        $returnValue.InstallationPolicy = $repository.InstallationPolicy
+        $returnValue.PackageManagementProvider = $repository.PackageManagementProvider
+        $returnValue.Trusted = $repository.Trusted
+        $returnValue.Registered = $repository.Registered
+    }
+    else {
+        Write-Verbose -Message ($localizedData.RepositoryNotFound -f $Name)
+    }
+
+    return $returnValue
+}
+
+<#
+    .SYNOPSIS
+        Determines if the repository is in the desired state.
+
+    .PARAMETER Ensure
+        If the repository should be present or absent on the server
+        being configured. Default values is 'Present'.
+
+    .PARAMETER Name
+        Specifies the name of the repository to manage.
+
+    .PARAMETER SourceLocation
+        Specifies the URI for discovering and installing modules from
+        this repository. A URI can be a NuGet server feed, HTTP, HTTPS,
+        FTP or file location.
+
+    .PARAMETER ScriptSourceLocation
+        Specifies the URI for the script source location.
+
+    .PARAMETER PublishLocation
+        Specifies the URI of the publish location. For example, for
+        NuGet-based repositories, the publish location is similar
+        to http://someNuGetUrl.com/api/v2/Packages.
+
+    .PARAMETER ScriptPublishLocation
+        Specifies the URI for the script publish location.
+
+    .PARAMETER InstallationPolicy
+        Specifies the installation policy. Valid values are  'Trusted'
+        or 'Untrusted'. The default value is 'Untrusted'.
+
+    .PARAMETER PackageManagementProvider
+        Specifies a OneGet package provider. Default value is 'NuGet'.
+#>
+function Test-TargetResource {
+    <#
+        These suppressions are added because this repository have other Visual Studio Code workspace
+        settings than those in DscResource.Tests DSC test framework.
+        Only those suppression that contradict this repository guideline is added here.
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('DscResource.AnalyzerRules\Measure-FunctionBlockBraces', '')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('DscResource.AnalyzerRules\Measure-IfStatement', '')]
+    [CmdletBinding()]
+    [OutputType([System.Boolean])]
+    param
+    (
+        [Parameter()]
+        [ValidateSet('Present', 'Absent')]
+        [System.String]
+        $Ensure = 'Present',
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.String]
+        $SourceLocation,
+
+        [Parameter()]
+        [System.String]
+        $ScriptSourceLocation,
+
+        [Parameter()]
+        [System.String]
+        $PublishLocation,
+
+        [Parameter()]
+        [System.String]
+        $ScriptPublishLocation,
+
+        [Parameter()]
+        [ValidateSet('Trusted', 'Untrusted')]
+        [System.String]
+        $InstallationPolicy = 'Untrusted',
+
+        [Parameter()]
+        [System.String]
+        $PackageManagementProvider = 'NuGet'
+    )
+
+    Write-Verbose -Message ($localizedData.TestTargetResourceMessage -f $Name)
+
+    $returnValue = $false
+
+    $getTargetResourceResult = Get-TargetResource -Name $Name
+
+    if ($Ensure -eq $getTargetResourceResult.Ensure) {
+        if ($getTargetResourceResult.Ensure -eq 'Present' ) {
+            $returnValue = Test-DscParameterState `
+                -CurrentValues $getTargetResourceResult `
+                -DesiredValues $PSBoundParameters `
+                -ValuesToCheck @(
+                'SourceLocation'
+                'ScriptSourceLocation'
+                'PublishLocation'
+                'ScriptPublishLocation'
+                'InstallationPolicy'
+                'PackageManagementProvider'
+            )
+        }
+        else {
+            $returnValue = $true
+        }
+    }
+
+    if ($returnValue) {
+        Write-Verbose -Message ($localizedData.InDesiredState -f $Name)
+    }
+    else {
+        Write-Verbose -Message ($localizedData.NotInDesiredState -f $Name)
+    }
+
+    return $returnValue
+}
+
+<#
+    .SYNOPSIS
+        Creates, removes or updates the repository.
+
+    .PARAMETER Ensure
+        If the repository should be present or absent on the server
+        being configured. Default values is 'Present'.
+
+    .PARAMETER Name
+        Specifies the name of the repository to manage.
+
+    .PARAMETER SourceLocation
+        Specifies the URI for discovering and installing modules from
+        this repository. A URI can be a NuGet server feed, HTTP, HTTPS,
+        FTP or file location.
+
+    .PARAMETER ScriptSourceLocation
+        Specifies the URI for the script source location.
+
+    .PARAMETER PublishLocation
+        Specifies the URI of the publish location. For example, for
+        NuGet-based repositories, the publish location is similar
+        to http://someNuGetUrl.com/api/v2/Packages.
+
+    .PARAMETER ScriptPublishLocation
+        Specifies the URI for the script publish location.
+
+    .PARAMETER InstallationPolicy
+        Specifies the installation policy. Valid values are  'Trusted'
+        or 'Untrusted'. The default value is 'Untrusted'.
+
+    .PARAMETER PackageManagementProvider
+        Specifies a OneGet package provider. Default value is 'NuGet'.
+#>
+function Set-TargetResource {
+    <#
+        These suppressions are added because this repository have other Visual Studio Code workspace
+        settings than those in DscResource.Tests DSC test framework.
+        Only those suppression that contradict this repository guideline is added here.
+    #>
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('DscResource.AnalyzerRules\Measure-FunctionBlockBraces', '')]
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('DscResource.AnalyzerRules\Measure-IfStatement', '')]
+    [CmdletBinding()]
+    param
+    (
+        [Parameter()]
+        [ValidateSet('Present', 'Absent')]
+        [System.String]
+        $Ensure = 'Present',
+
+        [Parameter(Mandatory = $true)]
+        [System.String]
+        $Name,
+
+        [Parameter()]
+        [System.String]
+        $SourceLocation,
+
+        [Parameter()]
+        [System.String]
+        $ScriptSourceLocation,
+
+        [Parameter()]
+        [System.String]
+        $PublishLocation,
+
+        [Parameter()]
+        [System.String]
+        $ScriptPublishLocation,
+
+        [Parameter()]
+        [ValidateSet('Trusted', 'Untrusted')]
+        [System.String]
+        $InstallationPolicy = 'Untrusted',
+
+        [Parameter()]
+        [System.String]
+        $PackageManagementProvider = 'NuGet'
+    )
+
+    $getTargetResourceResult = Get-TargetResource -Name $Name
+
+    # Determine if the repository should be present or absent.
+    if ($Ensure -eq 'Present') {
+        $repositoryParameters = New-SplatParameterHashTable `
+            -FunctionBoundParameters $PSBoundParameters `
+            -ArgumentNames @(
+            'Name'
+            'SourceLocation'
+            'ScriptSourceLocation'
+            'PublishLocation'
+            'ScriptPublishLocation'
+            'InstallationPolicy'
+            'PackageManagementProvider'
+        )
+
+        # Determine if the repository is already present.
+        if ($getTargetResourceResult.Ensure -eq 'Present') {
+            Write-Verbose -Message ($localizedData.RepositoryExist -f $Name)
+
+            # Repository exist, update the properties.
+            Set-PSRepository @repositoryParameters -ErrorAction 'Stop'
+        }
+        else {
+            Write-Verbose -Message ($localizedData.RepositoryDoesNotExist -f $Name)
+
+            # Repository did not exist, create the repository.
+            Register-PSRepository @repositoryParameters -ErrorAction 'Stop'
+        }
+    }
+    else {
+        if ($getTargetResourceResult.Ensure -eq 'Present') {
+            Write-Verbose -Message ($localizedData.RemoveExistingRepository -f $Name)
+
+            # Repository did exist, remove the repository.
+            Unregister-PSRepository -Name $Name -ErrorAction 'Stop'
+        }
+    }
+}

DSC/DSCResources/MSFT_PSRepository/MSFT_PSRepository.schema.mfl

@@ -0,0 +1,18 @@
+#pragma namespace("\\\\.\\root\\default")
+instance of __namespace{ name="MS_409";};
+#pragma namespace("\\\\.\\root\\default\\MS_409")
+
+[AMENDMENT, LOCALE("MS_409")]
+class MSFT_PSModule : OMI_BaseResource
+{
+  [Key, Description("Specifies the name of the repository to manage.") : Amended] String Name;
+  [Description("If the repository should be present or absent on the server being configured. Default values is 'Present'.") : Amended] String Ensure;
+  [Description("Specifies the URI for discovering and installing modules from this repository. A URI can be a NuGet server feed, HTTP, HTTPS, FTP or file location.") : Amended] String SourceLocation;
+  [Description("Specifies the URI for the script source location.") : Amended] String ScriptSourceLocation;
+  [Description("Specifies the URI of the publish location. For example, for NuGet-based repositories, the publish location is similar to http://someNuGetUrl.com/api/v2/Packages.") : Amended] String PublishLocation;
+  [Description("Specifies the URI for the script publish location.") : Amended] String ScriptPublishLocation;
+  [Description("Specifies the installation policy. Valid values are 'Trusted' or 'Untrusted'. The default value is 'Untrusted'.") : Amended] String InstallationPolicy;
+  [Description("Specifies a OneGet package provider. Default value is 'NuGet'.") : Amended] String PackageManagementProvider;
+  [Description("Specifies if the repository is trusted.") : Amended] Boolean Trusted;
+  [Description("Specifies if the repository is registered.") : Amended] Boolean Registered;
+};

DSC/DSCResources/MSFT_PSRepository/MSFT_PSRepository.schema.mof

@@ -0,0 +1,14 @@
+[ClassVersion("1.0.0.0"),FriendlyName("PSRepository")]
+class MSFT_PSRepository : OMI_BaseResource
+{
+    [Key] String Name;
+    [Write, ValueMap{"Present","Absent"}, Values{"Present","Absent"}] String Ensure;
+    [Write] String SourceLocation;
+    [Write] String ScriptSourceLocation;
+    [Write] String PublishLocation;
+    [Write] String ScriptPublishLocation;
+    [Write, ValueMap{"Trusted","Untrusted"}, Values{"Trusted","Untrusted"}] String InstallationPolicy;
+    [Write] String PackageManagementProvider;
+    [Read] Boolean Trusted;
+    [Read] Boolean Registered;
+};

DSC/DSCResources/MSFT_PSRepository/en-US/MSFT_PSRepository.strings.psd1

@@ -0,0 +1,22 @@
+#
+# Copyright (c) Microsoft Corporation.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+#
+# culture = "en-US"
+ConvertFrom-StringData -StringData @'
+    GetTargetResourceMessage  = Return the current state of the repository '{0}'.
+    RepositoryNotFound        = The repository '{0}' was not found.
+    TestTargetResourceMessage = Determining if the repository '{0}' is in the desired state.
+    InDesiredState            = Repository '{0}' is in the desired state.
+    NotInDesiredState         = Repository '{0}' is not in the desired state.
+    RepositoryExist           = Updating the properties of the repository '{0}'.
+    RepositoryDoesNotExist    = Creating the repository '{0}'.
+    RemoveExistingRepository  = Removing the repository '{0}'.
+'@