Egyéni DSC-erőforrás írása PowerShell-osztályokkalWriting a custom DSC resource with PowerShell classes

A következőkre vonatkozik: Windows PowerShell 5,0Applies To: Windows PowerShell 5.0

A PowerShell-osztályok Windows PowerShell 5,0-ben való bevezetésével mostantól egy osztály létrehozásával is meghatározhatja a DSC-erőforrásokat.With the introduction of PowerShell classes in Windows PowerShell 5.0, you can now define a DSC resource by creating a class. Az osztály az erőforrás sémáját és megvalósítását is meghatározza, így nem kell külön MOF-fájlt létrehoznia.The class defines both the schema and the implementation of the resource, so there is no need to create a separate MOF file. Az osztály alapú erőforrások DSCResources is egyszerűbb, mert nincs szükség a szükséges mappákra.The folder structure for a class-based resource is also simpler, because a DSCResources folder is not necessary.

A Class-alapú DSC-erőforrásokban a séma az osztály tulajdonságaiként van definiálva, amely az attribútumokkal módosítható a tulajdonság típusának megadásához.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.. Az erőforrást a, Get() a Set() és a Test() metódus valósítja meg (a Get-TargetResource , a Set-TargetResource és a Test-TargetResource függvények egy parancsfájl-erőforrásban.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.

Ebben a cikkben egy FileResource nevű egyszerű erőforrást hozunk létre, amely egy megadott elérési úton felügyel egy fájlt.In this article, we will create a simple resource named FileResource that manages a file in a specified path.

A DSC-erőforrásokkal kapcsolatos további információkért lásd: Egyéni Windows PowerShell kívánt állapot konfigurációs erőforrásainak létrehozásaFor more information about DSC resources, see Build Custom Windows PowerShell Desired State Configuration Resources

Megjegyzés

Az általános gyűjtemények nem támogatottak a Class-alapú erőforrásokban.Generic collections are not supported in class-based resources.

Osztály erőforrásának mappastruktúrátFolder structure for a class resource

Ha egyéni DSC-erőforrást szeretne létrehozni egy PowerShell-osztállyal, hozza létre a következő mappastruktúrát.To implement a DSC custom resource with a PowerShell class, create the following folder structure. Az osztály definiálva van, MyDscResource.psm1 és a modul jegyzékfájlja meg van határozva a ben 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

Az osztály létrehozásaCreate the class

A Class kulcsszó használatával PowerShell-osztályt hozhat létre.You use the class keyword to create a PowerShell class. Annak megadásához, hogy egy osztály DSC-erőforrás legyen, használja az DscResource() attribútumot.To specify that a class is a DSC resource, use the DscResource() attribute. Az osztály neve a DSC-erőforrás neve.The name of the class is the name of the DSC resource.

[DscResource()]
class FileResource {
}

Tulajdonságok deklarálásaDeclare properties

A DSC-erőforrás sémája a osztály tulajdonságaiként van definiálva.The DSC resource schema is defined as properties of the class. A következő három tulajdonságot deklaráljuk.We declare three properties as follows.

[DscProperty(Key)]
[string]$Path

[DscProperty(Mandatory)]
[Ensure] $Ensure

[DscProperty(Mandatory)]
[string] $SourcePath

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

Figyelje meg, hogy a tulajdonságokat az attribútumok módosítják.Notice that the properties are modified by attributes. Az attribútumok jelentése a következő:The meaning of the attributes is as follows:

  • DscProperty (kulcs) : a tulajdonság megadása kötelező.DscProperty(Key) : The property is required. A tulajdonság egy kulcs.The property is a key. A kulcsokként megjelölt tulajdonságok értékének kombinálva kell lennie az erőforrás-példányok egyedi azonosításához a konfiguráción belül.The values of all properties marked as keys must combine to uniquely identify a resource instance within a configuration.
  • DscProperty (kötelező) : a tulajdonság megadása kötelező.DscProperty(Mandatory) : The property is required.
  • DscProperty (NotConfigurable) : a tulajdonság csak olvasható.DscProperty(NotConfigurable) : The property is read-only. Az ezzel az attribútummal jelölt tulajdonságok nem állíthatók be konfigurációval, de a metódus a következő módon tölti fel őket Get() .Properties marked with this attribute cannot be set by a configuration, but are populated by the Get() method when present.
  • DscProperty () : a tulajdonság konfigurálható, de nem kötelező.DscProperty() : The property is configurable, but it is not required.

A $Path és a $SourcePath Tulajdonságok egyaránt karakterláncok.The $Path and $SourcePath properties are both strings. A $CreationTime egy datetime tulajdonság.The $CreationTime is a DateTime property. A $Ensure tulajdonság egy enumerálási típus, amelyet a következőképpen határozhat meg.The $Ensure property is an enumeration type, defined as follows.

enum Ensure
{
    Absent
    Present
}

A módszerek megvalósításaImplementing the methods

A, a Get() Set() és a Test() metódusok Get-TargetResource egy parancsfájl-erőforráshoz hasonlók, Set-TargetResource és Test-TargetResource függvények.The Get(), Set(), and Test() methods are analogous to the Get-TargetResource, Set-TargetResource, and Test-TargetResource functions in a script resource.

Ez a kód tartalmazza a CopyFile() függvényt is, amely egy segítő függvény, amely átmásolja a fájlt a alkalmazásba $SourcePath $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
    }

A teljes fájlThe complete file

Az osztály teljes fájlja a következő:.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.

Jegyzékfájl létrehozásaCreate a manifest

Ahhoz, hogy egy osztály alapú erőforrás elérhető legyen a DSC motor számára, meg kell adnia egy DscResourcesToExport utasítást a jegyzékfájlban, amely arra utasítja a modult, hogy exportálja az erőforrást.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. A jegyzékfájl így néz ki: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 = ''
}

Az erőforrás teszteléseTest the resource

Miután mentette az osztályt és a jegyzékfájlt a mappa struktúrájában a korábban leírtak szerint, létrehozhat egy olyan konfigurációt, amely az új erőforrást használja.After saving the class and manifest files in the folder structure as described earlier, you can create a configuration that uses the new resource. A DSC-konfiguráció futtatásával kapcsolatos információkért lásd: konfigurációklétrehozása.For information about how to run a DSC configuration, see Enacting configurations. A következő konfiguráció azt vizsgálja, hogy a fájl c:\test\test.txt létezik-e, és ha nem, másolja a fájlt (a c:\test.txt konfiguráció futtatása előtt létre kell hoznia c:\test.txt ).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

Támogató PsDscRunAsCredentialSupporting PsDscRunAsCredential

Megjegyzés A PsDscRunAsCredential a PowerShell 5,0-es és újabb verzióiban támogatott.[Note] PsDscRunAsCredential is supported in PowerShell 5.0 and later.

A PsDscRunAsCredential tulajdonság a DSC-konfigurációk erőforrás-blokkban használható annak megadásához, hogy az erőforrást a hitelesítő adatok meghatározott készlete alatt kell futtatni.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. További információ: a DSC futtatása felhasználói hitelesítő adatokkal.For more information, see Running DSC with user credentials.

Az erőforrás PsDscRunAsCredential megkövetelése vagy letiltásaRequire or disallow PsDscRunAsCredential for your resource

Az DscResource() attribútum egy opcionális RunAsCredential paramétert is igénybe vesz.The DscResource() attribute takes an optional parameter RunAsCredential . Ez a paraméter a következő három érték egyikét veszi figyelembe:This parameter takes one of three values:

  • OptionalAz PsDscRunAsCredential az adott erőforrást meghívó konfigurációk esetében nem kötelező.Optional PsDscRunAsCredential is optional for configurations that call this resource. Ez az alapértelmezett érték.This is the default value.
  • MandatoryA PsDscRunAsCredential minden olyan konfigurációhoz használni kell, amely meghívja ezt az erőforrást.Mandatory PsDscRunAsCredential must be used for any configuration that calls this resource.
  • NotSupported Az erőforrást meghívó konfigurációk nem használhatják a PsDscRunAsCredential .NotSupported Configurations that call this resource cannot use PsDscRunAsCredential .
  • Default Ugyanaz, mint Optional .Default Same as Optional.

Például a következő attribútum használatával adhatja meg, hogy az egyéni erőforrás nem támogatja a PsDscRunAsCredential használatát:For example, use the following attribute to specify that your custom resource does not support using PsDscRunAsCredential :

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

Több Class-erőforrás deklarálása egy modulbanDeclaring multiple class resources in a module

Egy modul több Class-alapú DSC-erőforrást is meghatározhat.A module can define multiple class based DSC resources. A mappa szerkezete a következő módokon hozható létre:You can create the folder structure in the following ways:

  1. Adja meg az első erőforrást a <ModuleName>.psm1 fájl és az azt követő erőforrások számára a DSCResources mappában.Define the first resource in the <ModuleName>.psm1 file and subsequent resources under the DSCResources folder.

    $env:ProgramFiles\WindowsPowerShell\Modules (folder)
         |- MyDscResource (folder)
            |- MyDscResource.psm1
               MyDscResource.psd1
         |- DSCResources
            |- SecondResource.psm1
    
  2. Adja meg az összes erőforrást a DSCResources mappában.Define all resources under the DSCResources folder.

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

Megjegyzés

A fenti példákban vegyen fel minden PSM1-fájlt a DSCResources alá a PSD1-fájlban lévő NestedModules -kulcshoz.In the examples above, add any PSM1 files under the DSCResources to the NestedModules key in your PSD1 file.

Hozzáférés a felhasználói környezethezAccess the user context

Ha egyéni erőforráson belül szeretné elérni a felhasználói környezetet, használhatja az automatikus változót $global:PsDscContext .To access the user context from within a custom resource, you can use the automatic variable $global:PsDscContext.

Például a következő kód azt a felhasználói környezetet írja, amelyben az erőforrás fut a részletes kimeneti adatfolyamként: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";
}

Lásd még:See Also

Egyéni Windows PowerShell kívánt állapot konfigurációs erőforrásainak létrehozásaBuild Custom Windows PowerShell Desired State Configuration Resources