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

Egyéni DSC-erőforrás írása MOF használatával

  • Cikk

A következőkre vonatkozik: Windows PowerShell 4.0, Windows PowerShell 5.0

Ebben a cikkben meghatározzuk egy Windows PowerShell Desired State Configuration (DSC) egyéni erőforrás sémáját egy MOF-fájlban, és implementáljuk az erőforrást egy Windows PowerShell szkriptfájlban. Ez az egyéni erőforrás egy webhely létrehozására és karbantartására használható.

Az MOF-séma létrehozása

A séma meghatározza az erőforrás azon tulajdonságait, amelyeket egy DSC-konfigurációs szkript konfigurálhat.

MOF-erőforrás mappastruktúrája

A DSC egyéni erőforrás MOF-sémával való implementálásához hozza létre a következő mappastruktúrát. Az MOF-séma a fájlban Demo_IISWebsite.schema.mofvan definiálva, az erőforrásszkript pedig a következőben van definiálva Demo_IISWebsite.psm1: . Lehetőség van moduljegyzékfájl (psd1) létrehozására is.

$env:ProgramFiles\WindowsPowerShell\Modules (folder)
    |- MyDscResources (folder)
        |- MyDscResources.psd1 (file, required)
        |- DSCResources (folder)
            |- Demo_IISWebsite (folder)
                |- Demo_IISWebsite.psd1 (file, optional)
                |- Demo_IISWebsite.psm1 (file, required)
                |- Demo_IISWebsite.schema.mof (file, required)

Megjegyzés

Létre kell hozni egy DSCResources nevű mappát a legfelső szintű mappa alatt, és hogy az egyes erőforrások mappájának az erőforrás nevével azonosnak kell lennie.

Az MOF-fájl tartalma

Az alábbiakban egy példa MOF-fájlt mutatunk be, amely egy egyéni webhelyerőforráshoz használható. A példa követéséhez mentse a sémát egy fájlba, és hívja meg a fájlt Demo_IISWebsite.schema.mof.

[ClassVersion("1.0.0"), FriendlyName("Website")]
class Demo_IISWebsite : OMI_BaseResource
{
  [Key] string Name;
  [Required] string PhysicalPath;
  [write,ValueMap{"Present", "Absent"},Values{"Present", "Absent"}] string Ensure;
  [write,ValueMap{"Started","Stopped"},Values{"Started", "Stopped"}] string State;
  [write] string Protocol[];
  [write] string BindingInfo[];
  [write] string ApplicationPool;
  [read] string ID;
};

Jegyezze fel a következőt az előző kóddal kapcsolatban:

  • FriendlyName Meghatározza a DSC konfigurációs szkriptjeiben az egyéni erőforrásra való hivatkozáshoz használható nevet. Ebben a példában Website egyenértékű a beépített archív erőforrás felhasználóbarát nevével Archive .
  • Az egyéni erőforráshoz definiált osztálynak a következőből OMI_BaseResourcekell származnia: .
  • A tulajdonság típusminősítője azt jelzi, [Key]hogy ez a tulajdonság egyedileg azonosítja az erőforráspéldányt. Legalább egy [Key] tulajdonságra szükség van.
  • A [Required] minősítő azt jelzi, hogy a tulajdonság megadása kötelező (az erőforrást használó konfigurációs szkriptekben meg kell adni egy értéket).
  • A [write] minősítő azt jelzi, hogy ez a tulajdonság nem kötelező, ha az egyéni erőforrást konfigurációs szkriptben használja. A [read] minősítő azt jelzi, hogy egy tulajdonság nem állítható be konfigurációval, és csak jelentéskészítési célokra szolgál.
  • Values korlátozza a tulajdonsághoz hozzárendelhető értékeket a(z) fájlban definiált értékek listájához ValueMap. További információ: Értéktérkép és Érték minősítői.
  • A beépített DSC-erőforrásokkal való konzisztens stílus fenntartása érdekében ajánlott az értékekkel Present és Absent az erőforrással együtt meghívni Ensure egy tulajdonságot.
  • Nevezze el az egyéni erőforrás sémafájlját a következőképpen: classname.schema.mof, ahol classname a sémadefinícióban szereplő kulcsszót követő class azonosító.

Az erőforrás-szkript írása

Az erőforrás-szkript implementálja az erőforrás logikáját. Ebben a modulban három függvényt Get-TargetResourcekell tartalmaznia: , Set-TargetResourceés Test-TargetResource. Mindhárom függvénynek olyan paraméterkészletet kell használnia, amely megegyezik az erőforráshoz létrehozott MOF-sémában definiált tulajdonságkészlettel. Ebben a dokumentumban ezt a tulajdonságkészletet "erőforrás-tulajdonságoknak" nevezzük. Tárolja ezt a három függvényt egy nevű <ResourceName>.psm1fájlban. Az alábbi példában a függvények egy nevű Demo_IISWebsite.psm1fájlban vannak tárolva.

Megjegyzés

Ha ugyanazt a konfigurációs szkriptet többször futtatja az erőforráson, nem kaphat hibaüzenetet, és az erőforrásnak ugyanabban az állapotban kell maradnia, mint a szkript egyszeri futtatása. Ehhez győződjön meg arról, hogy a Get-TargetResource és Test-TargetResource a függvények változatlanul hagyják az erőforrást, és hogy a Set-TargetResource függvény többször meghívása egy azonos paraméterértékekkel rendelkező sorozatban mindig egyenértékű az egyszeri meghívással.

A függvény implementációjában Get-TargetResource használja a paraméterekként megadott fő erőforrástulajdonság-értékeket a megadott erőforráspéldány állapotának ellenőrzéséhez. Ennek a függvénynek egy kivonattáblát kell visszaadnia, amely kulcsként listázza az összes erőforrás-tulajdonságot, a tulajdonságok tényleges értékeit pedig megfelelő értékekként. Az alábbi kód egy példát mutat be.

# DSC uses the Get-TargetResource function to fetch the status of the resource instance
# specified in the parameters for the target machine
function Get-TargetResource
{
    param
    (
        [ValidateSet("Present", "Absent")]
        [string]$Ensure = "Present",

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Name,

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$PhysicalPath,

        [ValidateSet("Started", "Stopped")]
        [string]$State = "Started",

        [string]$ApplicationPool,

        [string[]]$BindingInfo,

        [string[]]$Protocol
    )

        $getTargetResourceResult = $null;

        <#
          Insert logic that uses the mandatory parameter values to get the website and
          assign it to a variable called $Website
          Set $ensureResult to "Present" if the requested website exists and to "Absent" otherwise
        #>

        # Add all Website properties to the hash table
        # This simple example assumes that $Website is not null
        $getTargetResourceResult = @{
            Name = $Website.Name
            Ensure = $ensureResult
            PhysicalPath = $Website.physicalPath
            State = $Website.state
            ID = $Website.id
            ApplicationPool = $Website.applicationPool
            Protocol = $Website.bindings.Collection.protocol
            Binding = $Website.bindings.Collection.bindingInformation
        }

        $getTargetResourceResult
}

A konfigurációs szkript erőforrás-tulajdonságaihoz megadott értékektől függően a Set-TargetResource következő műveletek egyikét kell elvégeznie:

  • Új webhely létrehozása
  • Meglévő webhely frissítése
  • Meglévő webhely törlése

Az alábbi példa ezt szemlélteti.

# The Set-TargetResource function is used to create, delete or configure a website on the target machine.
function Set-TargetResource
{
    [CmdletBinding(SupportsShouldProcess=$true)]
    param
    (
        [ValidateSet("Present", "Absent")]
        [string]$Ensure = "Present",

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$Name,

        [Parameter(Mandatory)]
        [ValidateNotNullOrEmpty()]
        [string]$PhysicalPath,

        [ValidateSet("Started", "Stopped")]
        [string]$State = "Started",

        [string]$ApplicationPool,

        [string[]]$BindingInfo,

        [string[]]$Protocol
    )

    <#
        If Ensure is set to "Present" and the website specified in the mandatory input parameters
          does not exist, then create it using the specified parameter values
        Else, if Ensure is set to "Present" and the website does exist, then update its properties
          to match the values provided in the non-mandatory parameter values
        Else, if Ensure is set to "Absent" and the website does not exist, then do nothing
        Else, if Ensure is set to "Absent" and the website does exist, then delete the website
    #>
}

Végül a Test-TargetResource függvénynek ugyanazt a paraméterkészletet kell megadnia, mint a és Set-TargetResourcea paraméternekGet-TargetResource. A implementációjában Test-TargetResourceellenőrizze a kulcsparaméterekben megadott erőforráspéldány állapotát. Ha az erőforráspéldány tényleges állapota nem egyezik meg a paraméterkészletben megadott értékekkel, adja vissza a következőt $false: . Ellenkező esetben adja vissza a értéket $true.

Az alábbi kód implementálja a függvényt Test-TargetResource .

function Test-TargetResource
{
    [CmdletBinding()]
    [OutputType([System.Boolean])]
    param
    (
        [ValidateSet("Present","Absent")]
        [System.String]
        $Ensure,

        [parameter(Mandatory = $true)]
        [System.String]
        $Name,

        [parameter(Mandatory = $true)]
        [System.String]
        $PhysicalPath,

        [ValidateSet("Started","Stopped")]
        [System.String]
        $State,

        [System.String[]]
        $Protocol,

        [System.String[]]
        $BindingData,

        [System.String]
        $ApplicationPool
    )

    # Get the current state
    $currentState = Get-TargetResource -Ensure $Ensure -Name $Name -PhysicalPath $PhysicalPath -State $State -ApplicationPool $ApplicationPool -BindingInfo $BindingInfo -Protocol $Protocol

    # Write-Verbose "Use this cmdlet to deliver information about command processing."

    # Write-Debug "Use this cmdlet to write debug information while troubleshooting."

    # Include logic to
    $result = [System.Boolean]
    # Add logic to test whether the website is present and its status matches the supplied
    # parameter values. If it does, return true. If it does not, return false.
    $result
}

Megjegyzés

A könnyebb hibakeresés érdekében használja a Write-Verbose parancsmagot az előző három függvény implementációjában. Ez a parancsmag szöveget ír a részletes üzenetstreambe. Alapértelmezés szerint a részletes üzenetstream nem jelenik meg, de megjelenítheti a $VerbosePreference változó értékének módosításával, vagy a DSC-parancsmagok Részletes paraméterének használatával = új.

A moduljegyzék létrehozása

Végül a New-ModuleManifest parancsmaggal definiáljon egy <ResourceName>.psd1 fájlt az egyéni erőforrásmodulhoz. A parancsmag meghívásakor hivatkozzon az előző szakaszban ismertetett szkriptmodul -fájlra (.psm1). Az exportálandó függvények listájában szerepeljen Get-TargetResourcea , Set-TargetResourcea és Test-TargetResource a. Az alábbiakban egy példa jegyzékfájlt mutatunk be.

# Module manifest for module 'Demo.IIS.Website'
#
# Generated on: 1/10/2013
#

@{

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

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

# ID used to uniquely identify this module
GUID = '6AB5ED33-E923-41d8-A3A4-5ADDA2B301DE'

# Author of this module
Author = 'Contoso'

# Company or vendor of this module
CompanyName = 'Contoso'

# Copyright statement for this module
Copyright = 'Contoso. All rights reserved.'

# Description of the functionality provided by this module
Description = 'This Module is used to support the creation and configuration of IIS Websites through Get, Set and Test API on the DSC managed nodes.'

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

# Minimum version of the common language runtime (CLR) required by this module
CLRVersion = '4.0'

# Modules that must be imported into the global environment prior to importing this module
RequiredModules = @("WebAdministration")

# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
NestedModules = @("Demo_IISWebsite.psm1")

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

# Cmdlets to export from this module
#CmdletsToExport = '*'

# HelpInfo URI of this module
# HelpInfoURI = ''
}

PsDscRunAsCredential támogatása

Megjegyzés

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

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

Ha egyéni erőforráson belülről szeretné elérni a felhasználói környezetet, használja az automatikus változót $PsDscContext.

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

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

A csomópont újraindítása

Ha a függvényben Set-TargetResource végrehajtott műveletek újraindítást igényelnek, egy globális jelzővel jelezheti az LCM-nek, hogy indítsa újra a csomópontot. Ez az újraindítás közvetlenül a Set-TargetResource függvény befejeződése után következik be.

A függvényben Set-TargetResource adja hozzá a következő kódsort.

# Include this line if the resource requires a system reboot.
$global:DSCMachineStatus = 1

Ahhoz, hogy az LCM újraindítsa a csomópontot, a RebootNodeIfNeeded jelzőt a következőre kell állítani: $true. Az ActionAfterReboot beállítást is a ContinueConfiguration értékre kell állítani, amely az alapértelmezett érték. Az LCM konfigurálásáról további információt a Helyi Configuration Manager konfigurálása vagy a Helyi Configuration Manager konfigurálása (v4) című témakörben talál.