Megosztás a következőn keresztül:

Egyéni DSC-erőforrás írása PowerShell-osztályokkal

A következőkre vonatkozik: Windows PowerShell 5.0

A PowerShell-osztályok Windows PowerShell 5.0-s verziójának bevezetésével mostantól definiálhat egy DSC-erőforrást egy osztály létrehozásával. Az osztály meghatározza az erőforrás sémáját és implementációját is, így nincs szükség külön MOF-fájl létrehozására. Az osztályalapú erőforrások mappaszerkezete is egyszerűbb, mivel nincs szükség DSCResources mappára.

Egy osztályalapú DSC-erőforrásban a séma az osztály tulajdonságaiként van definiálva, amely attribútumokkal módosítható a tulajdonságtípus megadásához. Az erőforrást a , és metódusok Test() valósítják Get()meg (egyenértékű Get-TargetResourcea , Set-TargetResource, és Test-TargetResource függvényekkel egy szkripterőforrásban. Set()

Ebben a cikkben létrehozunk egy NewFile nevű egyszerű erőforrást, amely egy adott elérési úton kezeli a fájlt.

További információ a DSC-erőforrásokról: Egyéni Windows PowerShell Desired State Configuration Resources létrehozása

Jegyzet

Az általános gyűjtemények nem támogatottak az osztályalapú erőforrásokban.

Osztályerőforrás mappastruktúrája

Ha egyéni DSC-erőforrást szeretne implementálni egy PowerShell-osztálysal, hozza létre a következő mappastruktúrát. Az osztály definiálása a következőben MyDscResource.psm1 van, a moduljegyzék pedig a következőben MyDscResource.psd1van definiálva: .

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

Az osztály létrehozása

Az osztály kulcsszóval hozhat létre Egy PowerShell-osztályt. Ha meg szeretné adni, hogy egy osztály DSC-erőforrás, használja az attribútumot DscResource() . Az osztály neve a DSC-erőforrás neve.

[DscResource()]
class NewFile {
}

Tulajdonságok deklarálása

A DSC-erőforrásséma az osztály tulajdonságaiként van definiálva. Három tulajdonságot deklarálunk az alábbiak szerint.

[DscProperty(Key)]
[string] $path

[DscProperty(Mandatory)]
[ensure] $ensure

[DscProperty()]
[string] $content

[DscProperty(NotConfigurable)]
[MyDscResourceReason[]] $Reasons

Figyelje meg, hogy a tulajdonságokat attribútumok módosítják. Az attribútumok jelentése a következő:

  • DscProperty(Key): A tulajdonság kötelező. A tulajdonság egy kulcs. A kulcsként megjelölt összes tulajdonság értékeinek egyesíteniük kell az erőforráspéldány egyedi azonosításához egy konfiguráción belül.
  • DscProperty(Kötelező): A tulajdonság kötelező.
  • DscProperty(NotConfigurable): A tulajdonság csak olvasható. Az ezzel az attribútummal megjelölt tulajdonságokat nem lehet beállítani egy konfigurációval, de a Get() metódus feltölti őket, ha vannak.
  • DscProperty(): A tulajdonság konfigurálható, de nem kötelező.

A $Path és tulajdonságok $SourcePath egyaránt sztringek. A $CreationTimeDateTime tulajdonság. A $Ensure tulajdonság egy enumerálási típus, amely az alábbiak szerint van definiálva.

enum Ensure
{
    Absent
    Present
}

Osztályok beágyazása

Ha olyan új típust szeretne felvenni, amely definiált tulajdonságokkal rendelkezik, amelyeket az erőforráson belül használhat, csak hozzon létre egy, a fent ismertetett tulajdonságtípusokkal rendelkező osztályt.

class MyDscResourceReason {
    [DscProperty()]
    [string] $Code

    [DscProperty()]
    [string] $Phrase
}

Jegyzet

Az MyDscResourceReason osztály itt a modul nevével van deklarálva. Bár bármilyen nevet adhat a beágyazott osztályoknak, ha két vagy több modul azonos nevű osztályt határoz meg, és mindkettőt egy konfigurációban használják, a PowerShell kivételt okoz.

A DSC-ben a névütközések által okozott kivételek elkerülése érdekében a beágyazott osztályok nevét a modul nevével kell előtaggal előtaggal elnevezni. Ha a beágyazott osztály neve már nem valószínű, hogy ütközik, előtag nélkül is használhatja.

Ha a DSC-erőforrás az Azure-gépkonfigurációval való használatra van tervezve, mindig előtaggal adja elő az Okok tulajdonsághoz létrehozott beágyazott osztály nevét.

Nyilvános és privát függvények

PowerShell-függvényeket ugyanabban a modulfájlban hozhat létre, és használhatja őket a DSC-osztályerőforrás metódusai között. A függvényeket nyilvánosként kell deklarálni, a nyilvános függvények szkriptblokkja azonban meghívhat privát függvényeket. Az egyetlen különbség az, hogy szerepelnek-e FunctionsToExport a moduljegyzék tulajdonságában.

<#
   Public Functions
#>

function Get-File {
    param(
        [ensure]$ensure,

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    $fileContent        = [MyDscResourceReason]::new()
    $fileContent.code   = 'file:file:content'

    $filePresent        = [MyDscResourceReason]::new()
    $filePresent.code   = 'file:file:path'

    $ensureReturn = 'Absent'

    $fileExists = Test-path $path -ErrorAction SilentlyContinue

    if ($true -eq $fileExists) {
        $filePresent.phrase     = "The file was expected to be: $ensure`nThe file exists at path: $path"

        $existingFileContent    = Get-Content $path -Raw
        if ([string]::IsNullOrEmpty($existingFileContent)) {
            $existingFileContent = ''
        }

        if ($false -eq ([string]::IsNullOrEmpty($content))) {
            $content = $content | ConvertTo-SpecialChars
        }

        $fileContent.phrase     = "The file was expected to contain: $content`nThe file contained: $existingFileContent"

        if ($content -eq $existingFileContent) {
            $ensureReturn = 'Present'
        }
    }
    else {
        $filePresent.phrase     = "The file was expected to be: $ensure`nThe file does not exist at path: $path"
        $path = 'file not found'
    }

    return @{
        ensure  = $ensureReturn
        path    = $path
        content = $existingFileContent
        Reasons = @($filePresent,$fileContent)
    }
}

function Set-File {
    param(
        [ensure]$ensure = "Present",

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    Remove-Item $path -Force -ErrorAction SilentlyContinue
    if ($ensure -eq "Present") {
        New-Item $path -ItemType File -Force
        if ([ValidateNotNullOrEmpty()]$content) {
            $content | ConvertTo-SpecialChars | Set-Content $path -NoNewline -Force
        }
    }
}

function Test-File {
    param(
        [ensure]$ensure = "Present",

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    $test = $false
    $get = Get-File @PSBoundParameters

    if ($get.ensure -eq $ensure) {
        $test = $true
    }
    return $test
}

<#
   Private Functions
#>

function ConvertTo-SpecialChars {
    param(
        [parameter(Mandatory = $true,ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$string
    )
    $specialChars = @{
        '`n' = "`n"
        '\\n' = "`n"
        '`r' = "`r"
        '\\r' = "`r"
        '`t' = "`t"
        '\\t' = "`t"
    }
    foreach ($char in $specialChars.Keys) {
        $string = $string -replace ($char,$specialChars[$char])
    }
    return $string
}

A módszerek implementálása

A , és a Test() metódusok hasonlóak Get-TargetResourcea , Set-TargetResourceés Test-TargetResource függvényekhez egy szkripterőforrásban. Set()Get()

Ajánlott eljárásként minimalizálja a kód mennyiségét az osztály implementálásán belül. Ehelyett helyezze át a kód nagy részét a modul nyilvános függvényeibe, amelyek ezután egymástól függetlenül tesztelhetők.

<#
    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.
#>
[NewFile] Get() {
    $get = Get-File -ensure $this.ensure -path $this.path -content $this.content
    return $get
}

<#
    This method is equivalent of the Set-TargetResource script function.
    It sets the resource to the desired state.
#>
[void] Set() {
    $set = Set-File -ensure $this.ensure -path $this.path -content $this.content
}

<#
    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() {
    $test = Test-File -ensure $this.ensure -path $this.path -content $this.content
    return $test
}

A teljes fájl

A teljes osztályfájl a következő.

enum ensure {
    Absent
    Present
}

<#
    This class is used within the DSC Resource to standardize how data
    is returned about the compliance details of the machine. Note that
    the class name is prefixed with the module name - this helps prevent
    errors raised when multiple modules with DSC Resources define the
    Reasons property for reporting when they're out-of-state.
#>
class MyDscResourceReason {
    [DscProperty()]
    [string] $Code

    [DscProperty()]
    [string] $Phrase
}

<#
   Public Functions
#>

function Get-File {
    param(
        [ensure]$ensure,

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    $fileContent        = [MyDscResourceReason]::new()
    $fileContent.code   = 'file:file:content'

    $filePresent        = [MyDscResourceReason]::new()
    $filePresent.code   = 'file:file:path'

    $ensureReturn = 'Absent'

    $fileExists = Test-path $path -ErrorAction SilentlyContinue

    if ($true -eq $fileExists) {
        $filePresent.phrase     = "The file was expected to be: $ensure`nThe file exists at path: $path"

        $existingFileContent    = Get-Content $path -Raw
        if ([string]::IsNullOrEmpty($existingFileContent)) {
            $existingFileContent = ''
        }

        if ($false -eq ([string]::IsNullOrEmpty($content))) {
            $content = $content | ConvertTo-SpecialChars
        }

        $fileContent.phrase     = "The file was expected to contain: $content`nThe file contained: $existingFileContent"

        if ($content -eq $existingFileContent) {
            $ensureReturn = 'Present'
        }
    }
    else {
        $filePresent.phrase     = "The file was expected to be: $ensure`nThe file does not exist at path: $path"
        $path = 'file not found'
    }

    return @{
        ensure  = $ensureReturn
        path    = $path
        content = $existingFileContent
        Reasons = @($filePresent,$fileContent)
    }
}

function Set-File {
    param(
        [ensure]$ensure = "Present",

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    Remove-Item $path -Force -ErrorAction SilentlyContinue
    if ($ensure -eq "Present") {
        New-Item $path -ItemType File -Force
        if ([ValidateNotNullOrEmpty()]$content) {
            $content | ConvertTo-SpecialChars | Set-Content $path -NoNewline -Force
        }
    }
}

function Test-File {
    param(
        [ensure]$ensure = "Present",

        [parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [String]$path,

        [String]$content
    )
    $test = $false
    $get = Get-File @PSBoundParameters

    if ($get.ensure -eq $ensure) {
        $test = $true
    }
    return $test
}

<#
   Private Functions
#>

function ConvertTo-SpecialChars {
    param(
        [parameter(Mandatory = $true,ValueFromPipeline)]
        [ValidateNotNullOrEmpty()]
        [string]$string
    )
    $specialChars = @{
        '`n' = "`n"
        '\\n' = "`n"
        '`r' = "`r"
        '\\r' = "`r"
        '`t' = "`t"
        '\\t' = "`t"
    }
    foreach ($char in $specialChars.Keys) {
        $string = $string -replace ($char,$specialChars[$char])
    }
    return $string
}

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

[DscResource()]
class NewFile {

    <#
        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 is optional. When provided, the content of the file
        will be overwridden by this value.
    #>
    [DscProperty()]
    [string] $content

    <#
        This property reports the reasons the machine is or is not compliant.

        [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)]
    [MyDscResourceReason[]] $Reasons

    <#
        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.
    #>
    [NewFile] Get() {
        $get = Get-File -ensure $this.ensure -path $this.path -content $this.content
        return $get
    }

    <#
        This method is equivalent of the Set-TargetResource script function.
        It sets the resource to the desired state.
    #>
    [void] Set() {
        $set = Set-File -ensure $this.ensure -path $this.path -content $this.content
    }

    <#
        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() {
        $test = Test-File -ensure $this.ensure -path $this.path -content $this.content
        return $test
    }
}

Jegyzék létrehozása

Ahhoz, hogy egy osztályalapú erőforrást elérhetővé tegyen a DSC-motor számára, a jegyzékfájlban szerepelnie kell egy DscResourcesToExport utasítást, amely utasítja a modult az erőforrás exportálására. A jegyzék a következőképpen néz ki:

@{

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

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

    # ID used to uniquely identify this module
    GUID = 'fad0d04e-65d9-4e87-aa17-39de1d008ee4'

    # Author of this module
    Author = 'Microsoft Corporation'

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

    # Copyright statement for this module
    Copyright = ''

    # Description of the functionality provided by this module
    Description = 'Create and set content of a file'

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

    # Functions to export from this module
    FunctionsToExport = @('Get-File','Set-File','Test-File')

    # DSC resources to export from this module
    DscResourcesToExport = @('NewFile')

    # Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
    PrivateData = @{

        PSData = @{

            # Tags applied to this module. These help with module discovery in online galleries.
            # Tags = @(Power Plan, Energy, Battery)

            # A URL to the license for this module.
            # LicenseUri = ''

            # A URL to the main website for this project.
            # ProjectUri = ''

            # A URL to an icon representing this module.
            # IconUri = ''

            # ReleaseNotes of this module
            # ReleaseNotes = ''

        } # End of PSData hashtable

    }
}

Az erőforrás tesztelése

Miután mentette az osztály- és jegyzékfájlokat a mappastruktúrában a korábban ismertetett módon, létrehozhat egy konfigurációt, amely az új erőforrást használja. További információ a DSC-konfigurációk futtatásáról: Konfigurációk végrehajtása. A következő konfiguráció ellenőrzi, hogy létezik-e a fájl, /tmp/test.txt és hogy a tartalom megegyezik-e a "Content" tulajdonság által megadott sztringgel. Ha nem, a teljes fájl meg van írva.

Configuration MyConfig
{
    Import-DSCResource -ModuleName NewFile
    NewFile testFile
    {
        Path = "/tmp/test.txt"
        Content = "DSC Rocks!"
        Ensure = "Present"
    }
}
MyConfig

PsDscRunAsCredential támogatása

[Megjegyzés] A PsDscRunAsCredential a PowerShell 5.0-s és újabb verzióiban támogatott.

A PsDscRunAsCredential tulajdonság a DSC-konfigurációk erőforrásblokkjában használható annak megadására, hogy az erőforrást egy megadott hitelesítő adatkészlettel kell futtatni. További információ: A DSC futtatása felhasználói hitelesítő adatokkal.

PsDscRunAsCredential megkövetelése vagy letiltása az erőforráshoz

Az DscResource() attribútum egy opcionális paramétert vesz fel. Ez a paraméter a következő három érték egyikét veszi fel:

  • Optional A PsDscRunAsCredential nem kötelező az erőforrást meghívó konfigurációkhoz. Ez az alapértelmezett érték.
  • Mandatory A PsDscRunAsCredential minden olyan konfigurációhoz használható, amely meghívja ezt az erőforrást.
  • NotSupportedAz erőforrást meghívó konfigurációk nem használhatják a PsDscRunAsCredential.
  • Default ugyanaz, mint Optional.

A következő attribútummal például megadhatja, hogy az egyéni erőforrás ne támogassa a PsDscRunAsCredential használatát:

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

Több osztályerőforrás deklarálása egy modulban

Egy modul több osztályalapú DSC-erőforrást is definiálhat. Csak deklarálnia kell az összes osztályt ugyanabban a .psm1 fájlban, és minden nevet bele kell foglalnia a .psd1 jegyzékbe.

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

Hozzáférés a felhasználói környezethez

A felhasználói környezet egyéni erőforrásból való eléréséhez használhatja az automatikus változót $global:PsDscContext.

Az alábbi kód például azt a felhasználói környezetet írja meg, amely alatt az erőforrás fut a részletes kimeneti adatfolyamon:

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

Lásd még:

Egyéni Windows PowerShell kívánt állapotkonfigurációs erőforrások létrehozása

  • Last updated on