Schrijven van een aangepaste DSC-resource met PowerShell-klassenWriting a custom DSC resource with PowerShell classes

Van toepassing op: Windows Windows PowerShell 5.0Applies To: Windows Windows PowerShell 5.0

Dankzij de introductie van de klassen van PowerShell in Windows PowerShell 5.0, kunt u nu een DSC-resource definiƫren door een klasse maken.With the introduction of PowerShell classes in Windows PowerShell 5.0, you can now define a DSC resource by creating a class. De klasse definieert de schema- en de implementatie van de resource, dus u hoeft niet te maken van een afzonderlijke MOF-bestand.The class defines both the schema and the implementation of the resource, so there is no need to create a separate MOF file. De mapstructuur voor een bron op basis van een klasse is ook eenvoudiger, omdat een DSCResources map is niet nodig.The folder structure for a class-based resource is also simpler, because a DSCResources folder is not necessary.

Het schema is in een klasse gebaseerde DSC-resource gedefinieerd als de eigenschappen van de klasse die kan worden gewijzigd met kenmerken om op te geven van het eigenschapstype...In a class-based DSC resource, the schema is defined as properties of the class which can be modified with attributes to specify the property type.. De resource wordt geĆÆmplementeerd door Get(), Set(), en Test() methoden (gelijk aan de Get-TargetResource, Set TargetResource, en Test TargetResource functies in de bron van een script.The resource is implemented by Get(), Set(), and Test() methods (equivalent to the Get-TargetResource, Set-TargetResource, and Test-TargetResource functions in a script resource.

In dit onderwerp, maken we een eenvoudige resource met de naam FileResource die een bestand in een opgegeven pad beheert.In this topic, we will create a simple resource named FileResource that manages a file in a specified path.

Zie voor meer informatie over DSC-resources bouwen aangepaste Windows PowerShell Desired status configuratie ResourcesFor more information about DSC resources, see Build Custom Windows PowerShell Desired State Configuration Resources

Opmerking: algemene verzamelingen worden niet ondersteund in de klasse-bronnen.Note: Generic collections are not supported in class-based resources.

Mapstructuur voor een klasse-bronFolder structure for a class resource

Voor het implementeren van een aangepaste DSC-resource met een PowerShell-klasse, maken de volgende mapstructuur.To implement a DSC custom resource with a PowerShell class, create the following folder structure. De klasse is gedefinieerd in MyDscResource.psm1 en de module-manifest wordt gedefinieerd in MyDscResource.psd1.The class is defined in MyDscResource.psm1 and the module manifest is defined in MyDscResource.psd1.

$env:ProgramFiles\WindowsPowerShell\Modules (folder)
    |- MyDscResource (folder)
        |- MyDscResource.psm1
           MyDscResource.psd1

De klasse makenCreate the class

Het sleutelwoord klasse kunt u een PowerShell-klasse maken.You use the class keyword to create a PowerShell class. Als u wilt opgeven dat een klasse een DSC-resource is, gebruiken de DscResource() kenmerk.To specify that a class is a DSC resource, use the DscResource() attribute. De naam van de klasse is de naam van de DSC-resource.The name of the class is the name of the DSC resource.

[DscResource()]
class FileResource {
}

Eigenschappen declarerenDeclare properties

De DSC-resource-schema is gedefinieerd als de eigenschappen van de klasse.The DSC resource schema is defined as properties of the class. We declareren drie eigenschappen als volgt.We declare three properties as follows.

[DscProperty(Key)]
[string]$Path

[DscProperty(Mandatory)]
[Ensure] $Ensure

[DscProperty(Mandatory)]
[string] $SourcePath

[DscProperty(NotConfigurable)]
[Nullable[datetime]] $CreationTime

U ziet dat de eigenschappen zijn gewijzigd door de kenmerken.Notice that the properties are modified by attributes. De betekenis van de kenmerken is als volgt:The meaning of the attributes is as follows:

  • DscProperty(Key): de eigenschap is vereist.DscProperty(Key): The property is required. De eigenschap is een sleutel.The property is a key. De waarden van alle eigenschappen die zijn gemarkeerd als sleutels combineren moeten om een unieke identificatie van een resource-instantie in een configuratie.The values of all properties marked as keys must combine to uniquely identify a resource instance within a configuration.
  • DscProperty(Mandatory): de eigenschap is vereist.DscProperty(Mandatory): The property is required.
  • DscProperty(NotConfigurable): de eigenschap is alleen-lezen.DscProperty(NotConfigurable): The property is read-only. Eigenschappen die zijn gemarkeerd met dit kenmerk kan niet worden ingesteld door een configuratie, maar worden ingevuld met de Get() methode indien aanwezig.Properties marked with this attribute cannot be set by a configuration, but are populated by the Get() method when present.
  • DscProperty(): de eigenschap kan worden geconfigureerd, maar is niet vereist.DscProperty(): The property is configurable, but it is not required.

De $Path en $SourcePath eigenschappen zijn beide tekenreeksen.The $Path and $SourcePath properties are both strings. De $CreationTime is een DateTime eigenschap.The $CreationTime is a DateTime property. De $Ensure eigenschap is een opsommingstype als volgt gedefinieerd.The $Ensure property is an enumeration type, defined as follows.

enum Ensure
{
    Absent
    Present
}

Implementeren van de methodenImplementing the methods

De Get(), Set(), en Test() methoden zijn vergelijkbaar met de Get-TargetResource, Set TargetResource , en Test TargetResource functies in de bron van een script.The Get(), Set(), and Test() methods are analogous to the Get-TargetResource, Set-TargetResource, and Test-TargetResource functions in a script resource.

Deze code bevat ook de functie CopyFile(), een Help-functie waarmee het bestand worden gekopieerd $SourcePath naar $Path.This code also includes the CopyFile() function, a helper function that copies the file from $SourcePath to $Path.


    <#
        This method is equivalent of the Set-TargetResource script function.
        It sets the resource to the desired state.
    #>
    [void] Set()
    {
        $fileExists = $this.TestFilePath($this.Path)

        if ($this.ensure -eq [Ensure]::Present)
        {
            if(-not $fileExists)
            {
                $this.CopyFile()
            }
        }
        else
        {
            if ($fileExists)
            {
                Write-Verbose -Message "Deleting the file $($this.Path)"
                Remove-Item -LiteralPath $this.Path -Force
            }
        }
    }

    <#
        This method is equivalent of the Test-TargetResource script function.
        It should return True or False, showing whether the resource
        is in a desired state.
    #>
    [bool] Test()
    {
        $present = $this.TestFilePath($this.Path)

        if ($this.Ensure -eq [Ensure]::Present)
        {
            return $present
        }
        else
        {
            return -not $present
        }
    }

    <#
        This method is equivalent of the Get-TargetResource script function.
        The implementation should use the keys to find appropriate resources.
        This method returns an instance of this class with the updated key
         properties.
    #>
    [FileResource] Get()
    {
        $present = $this.TestFilePath($this.Path)

        if ($present)
        {
            $file = Get-ChildItem -LiteralPath $this.Path
            $this.CreationTime = $file.CreationTime
            $this.Ensure = [Ensure]::Present
        }
        else
        {
            $this.CreationTime = $null
            $this.Ensure = [Ensure]::Absent
        }

        return $this
    }

    <#
        Helper method to check if the file exists and it is file
    #>
    [bool] TestFilePath([string] $location)
    {
        $present = $true

        $item = Get-ChildItem -LiteralPath $location -ErrorAction Ignore

        if ($item -eq $null)
        {
            $present = $false
        }
        elseif ($item.PSProvider.Name -ne "FileSystem")
        {
            throw "Path $($location) is not a file path."
        }
        elseif ($item.PSIsContainer)
        {
            throw "Path $($location) is a directory path."
        }

        return $present
    }

    <#
        Helper method to copy file from source to path
    #>
    [void] CopyFile()
    {
        if (-not $this.TestFilePath($this.SourcePath))
        {
            throw "SourcePath $($this.SourcePath) is not found."
        }

        [System.IO.FileInfo] $destFileInfo = New-Object -TypeName System.IO.FileInfo($this.Path)

        if (-not $destFileInfo.Directory.Exists)
        {
            Write-Verbose -Message "Creating directory $($destFileInfo.Directory.FullName)"

            <#
                Use CreateDirectory instead of New-Item to avoid code
                to handle the non-terminating error
            #>
            [System.IO.Directory]::CreateDirectory($destFileInfo.Directory.FullName)
        }

        if (Test-Path -LiteralPath $this.Path -PathType Container)
        {
            throw "Path $($this.Path) is a directory path"
        }

        Write-Verbose -Message "Copying $($this.SourcePath) to $($this.Path)"

        # DSC engine catches and reports any error that occurs
        Copy-Item -LiteralPath $this.SourcePath -Destination $this.Path -Force
    }

Het volledige bestandThe complete file

Het klassebestand voltooid volgt.The complete class file follows.

enum Ensure
{
    Absent
    Present
}

<#
   This resource manages the file in a specific path.
   [DscResource()] indicates the class is a DSC resource
#>

[DscResource()]
class FileResource
{
    <#
       This property is the fully qualified path to the file that is
       expected to be present or absent.

       The [DscProperty(Key)] attribute indicates the property is a
       key and its value uniquely identifies a resource instance.
       Defining this attribute also means the property is required
       and DSC will ensure a value is set before calling the resource.

       A DSC resource must define at least one key property.
    #>
    [DscProperty(Key)]
    [string]$Path

    <#
        This property indicates if the settings should be present or absent
        on the system. For present, the resource ensures the file pointed
        to by $Path exists. For absent, it ensures the file point to by
        $Path does not exist.

        The [DscProperty(Mandatory)] attribute indicates the property is
        required and DSC will guarantee it is set.

        If Mandatory is not specified or if it is defined as
        Mandatory=$false, the value is not guaranteed to be set when DSC
        calls the resource.  This is appropriate for optional properties.
    #>
    [DscProperty(Mandatory)]
    [Ensure] $Ensure

    <#
       This property defines the fully qualified path to a file that will
       be placed on the system if $Ensure = Present and $Path does not
        exist.

       NOTE: This property is required because [DscProperty(Mandatory)] is
        set.
    #>
    [DscProperty(Mandatory)]
    [string] $SourcePath

    <#
       This property reports the file's create timestamp.

       [DscProperty(NotConfigurable)] attribute indicates the property is
       not configurable in DSC configuration.  Properties marked this way
       are populated by the Get() method to report additional details
       about the resource when it is present.

    #>
    [DscProperty(NotConfigurable)]
    [Nullable[datetime]] $CreationTime

    <#
        This method is equivalent of the Set-TargetResource script function.
        It sets the resource to the desired state.
    #>
    [void] Set()
    {
        $fileExists = $this.TestFilePath($this.Path)
        if ($this.ensure -eq [Ensure]::Present)
        {
            if (-not $fileExists)
            {
                $this.CopyFile()
            }
        }
        else
        {
            if ($fileExists)
            {
                Write-Verbose -Message "Deleting the file $($this.Path)"
                Remove-Item -LiteralPath $this.Path -Force
            }
        }
    }

    <#
        This method is equivalent of the Test-TargetResource script function.
        It should return True or False, showing whether the resource
        is in a desired state.
    #>
    [bool] Test()
    {
        $present = $this.TestFilePath($this.Path)

        if ($this.Ensure -eq [Ensure]::Present)
        {
            return $present
        }
        else
        {
            return -not $present
        }
    }

    <#
        This method is equivalent of the Get-TargetResource script function.
        The implementation should use the keys to find appropriate resources.
        This method returns an instance of this class with the updated key
         properties.
    #>
    [FileResource] Get()
    {
        $present = $this.TestFilePath($this.Path)

        if ($present)
        {
            $file = Get-ChildItem -LiteralPath $this.Path
            $this.CreationTime = $file.CreationTime
            $this.Ensure = [Ensure]::Present
        }
        else
        {
            $this.CreationTime = $null
            $this.Ensure = [Ensure]::Absent
        }

        return $this
    }

    <#
        Helper method to check if the file exists and it is file
    #>
    [bool] TestFilePath([string] $location)
    {
        $present = $true

        $item = Get-ChildItem -LiteralPath $location -ea Ignore
        if ($item -eq $null)
        {
            $present = $false
        }
        elseif ($item.PSProvider.Name -ne "FileSystem")
        {
            throw "Path $($location) is not a file path."
        }
        elseif ($item.PSIsContainer)
        {
            throw "Path $($location) is a directory path."
        }

        return $present
    }

    <#
        Helper method to copy file from source to path
    #>
    [void] CopyFile()
    {
        if (-not $this.TestFilePath($this.SourcePath))
        {
            throw "SourcePath $($this.SourcePath) is not found."
        }

        [System.IO.FileInfo] $destFileInfo = new-object System.IO.FileInfo($this.Path)
        if (-not $destFileInfo.Directory.Exists)
        {
            Write-Verbose -Message "Creating directory $($destFileInfo.Directory.FullName)"

            <#
                Use CreateDirectory instead of New-Item to avoid code
                 to handle the non-terminating error
            #>
            [System.IO.Directory]::CreateDirectory($destFileInfo.Directory.FullName)
        }

        if (Test-Path -LiteralPath $this.Path -PathType Container)
        {
            throw "Path $($this.Path) is a directory path"
        }

        Write-Verbose -Message "Copying $($this.SourcePath) to $($this.Path)"

        # DSC engine catches and reports any error that occurs
        Copy-Item -LiteralPath $this.SourcePath -Destination $this.Path -Force
    }
} # This module defines a class for a DSC "FileResource" provider.

Maken van een manifestCreate a manifest

Als u een resource op basis van een klasse met de DSC-engine, moet u opnemen een DscResourcesToExport -instructie in het manifestbestand geeft u de module voor het exporteren van de resource.To make a class-based resource available to the DSC engine, you must include a DscResourcesToExport statement in the manifest file that instructs the module to export the resource. Onze manifest ziet er als volgt:Our manifest looks like this:

@{

# Script module or binary module file associated with this manifest.
RootModule = 'MyDscResource.psm1'

DscResourcesToExport = 'FileResource'

# Version number of this module.
ModuleVersion = '1.0'

# ID used to uniquely identify this module
GUID = '81624038-5e71-40f8-8905-b1a87afe22d7'

# Author of this module
Author = 'Microsoft Corporation'

# Company or vendor of this module
CompanyName = 'Microsoft Corporation'

# Copyright statement for this module
Copyright = '(c) 2014 Microsoft. All rights reserved.'

# Description of the functionality provided by this module
# Description = ''

# Minimum version of the Windows PowerShell engine required by this module
PowerShellVersion = '5.0'

# Name of the Windows PowerShell host required by this module
# PowerShellHostName = ''
}

De resource testenTest the resource

Na het opslaan van de klasse en de manifest-bestanden in de mapstructuur zoals eerder beschreven, kunt u een configuratie die gebruikmaakt van de nieuwe resource.After saving the class and manifest files in the folder structure as described earlier, you can create a configuration that uses the new resource. Zie voor meer informatie over het uitvoeren van een DSC-configuratie vast te stellen configuraties.For information about how to run a DSC configuration, see Enacting configurations. De volgende configuratie wordt gecontroleerd of het bestand op c:\test\test.txt bestaat en als dat niet het geval is, kopieert u het bestand van c:\test.txt (u moet maken c:\test.txt voordat u de configuratie uitvoeren).The following configuration will check to see whether the file at c:\test\test.txt exists, and, if not, copies the file from c:\test.txt (you should create c:\test.txt before you run the configuration).

Configuration Test
{
    Import-DSCResource -module MyDscResource
    FileResource file
    {
        Path = "C:\test\test.txt"
        SourcePath = "c:\test.txt"
        Ensure = "Present"
    }
}
Test
Start-DscConfiguration -Wait -Force Test

Ondersteunende PsDscRunAsCredentialSupporting PsDscRunAsCredential

Opmerking: PsDscRunAsCredential wordt ondersteund in PowerShell 5.0 en hoger.Note: PsDscRunAsCredential is supported in PowerShell 5.0 and later.

De PsDscRunAsCredential eigenschap kan worden gebruikt DSC-configuraties resource blok om op te geven dat de resource moet worden uitgevoerd onder een opgegeven set referenties.The PsDscRunAsCredential property can be used in DSC configurations resource block to specify that the resource should be run under a specified set of credentials. Zie voor meer informatie DSC uitgevoerd met gebruikersreferenties.For more information, see Running DSC with user credentials.

Vereist of niet toestaan van PsDscRunAsCredential voor uw resourceRequire or disallow PsDscRunAsCredential for your resource

De DscResource() kenmerk duurt een optionele parameter RunAsCredential.The DscResource() attribute takes an optional parameter RunAsCredential. Deze parameter heeft een van drie waarden:This parameter takes one of three values:

  • Optional PsDscRunAsCredential is optioneel voor configuraties die aanroepen van deze resource.Optional PsDscRunAsCredential is optional for configurations that call this resource. Dit is de standaardwaarde.This is the default value.
  • Mandatory PsDscRunAsCredential moet worden gebruikt voor een configuratie die deze resource roept.Mandatory PsDscRunAsCredential must be used for any configuration that calls this resource.
  • NotSupported Configuraties die aanroepen van deze resource kunnen niet worden gebruikt PsDscRunAsCredential.NotSupported Configurations that call this resource cannot use PsDscRunAsCredential.
  • Default Hetzelfde als Optional.Default Same as Optional.

Het volgende kenmerk bijvoorbeeld gebruiken om op te geven dat uw aangepaste resource biedt geen ondersteuning met behulp van PsDscRunAsCredential:For example, use the following attribute to specify that your custom resource does not support using PsDscRunAsCredential:

[DscResource(RunAsCredential=NotSupported)]
class FileResource {
}

Toegang tot de gebruikerscontextAccess the user context

Voor toegang tot de gebruikerscontext van binnen een aangepaste bron, kunt u de automatische variabele $global:PsDscContext.To access the user context from within a custom resource, you can use the automatic variable $global:PsDscContext.

De volgende code zou bijvoorbeeld de gebruikerscontext waaronder de bron wordt uitgevoerd naar de uitgebreide uitvoerstroom schrijven:For example the following code would write the user context under which the resource is running to the verbose output stream:

if (PsDscContext.RunAsUser) {
    Write-Verbose "User: $global:PsDscContext.RunAsUser";
}

Zie ookSee Also

ConceptenConcepts

Aangepaste Windows PowerShell Desired State Configuration Resources bouwenBuild Custom Windows PowerShell Desired State Configuration Resources