Skriva en anpassad DSC-resurs med MOF

  • Artikel

Gäller för: Windows PowerShell 4.0, Windows PowerShell 5.0

I den här artikeln definierar vi schemat för en anpassad Windows PowerShell Desired State Configuration(DSC) i en MOF-fil och implementerar resursen i en Windows PowerShell skriptfil. Den här anpassade resursen används för att skapa och underhålla en webbplats.

Skapa MOF-schemat

Schemat definierar egenskaperna för resursen som kan konfigureras av ett DSC-konfigurationsskript.

Mappstruktur för en MOF-resurs

Om du vill implementera en anpassad DSC-resurs med ett MOF-schema skapar du följande mappstruktur. MOF-schemat definieras i filen Demo_IISWebsite.schema.mofoch resursskriptet definieras i Demo_IISWebsite.psm1. Du kan också skapa en modulmanifestfil (psd1).

$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)

Anteckning

Det är nödvändigt att skapa en mapp med namnet DSCResources under mappen på den översta nivån och att mappen för varje resurs måste ha samma namn som resursen.

Innehållet i MOF-filen

Följande är ett exempel på en MOF-fil som kan användas för en anpassad webbplatsresurs. Om du vill följa det här exemplet sparar du schemat i en fil och anropar filen 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;
};

Observera följande om föregående kod:

  • FriendlyName definierar namnet som du kan använda för att referera till den här anpassade resursen i DSC-konfigurationsskript. I det här exemplet Website motsvarar det egna namnet Archive för den inbyggda arkivresursen.
  • Klassen som du definierar för din anpassade resurs måste härledas från OMI_BaseResource.
  • Typkvalificeraren, [Key], på en egenskap anger att den här egenskapen unikt identifierar resursinstansen. Minst en [Key] egenskap krävs.
  • Kvalificeraren [Required] anger att egenskapen krävs (ett värde måste anges i alla konfigurationsskript som använder den här resursen).
  • Kvalificeraren [write] anger att den här egenskapen är valfri när du använder den anpassade resursen i ett konfigurationsskript. Kvalificeraren [read] anger att en egenskap inte kan anges av en konfiguration och endast är avsedd för rapportering.
  • Values begränsar de värden som kan tilldelas egenskapen till listan med värden som definierats i ValueMap. Mer information finns i ValueMap och Value Qualifiers.
  • Att inkludera en egenskap som anropas Ensure med värden Present och Absent i resursen rekommenderas som ett sätt att upprätthålla ett konsekvent format med inbyggda DSC-resurser.
  • Namnge schemafilen för din anpassade resurs på följande sätt: classname.schema.mof, där classname är identifieraren som följer nyckelordet i schemadefinitionen class .

Skriva resursskriptet

Resursskriptet implementerar resursens logik. I den här modulen måste du inkludera tre funktioner som heter Get-TargetResource, Set-TargetResourceoch Test-TargetResource. Alla tre funktionerna måste ha en parameteruppsättning som är identisk med den uppsättning egenskaper som definierats i det MOF-schema som du skapade för resursen. I det här dokumentet kallas den här uppsättningen egenskaper för "resursegenskaper". Lagra dessa tre funktioner i en fil med namnet <ResourceName>.psm1. I följande exempel lagras funktionerna i en fil med namnet Demo_IISWebsite.psm1.

Anteckning

När du kör samma konfigurationsskript på resursen mer än en gång bör du inte få några fel och resursen ska förbli i samma tillstånd som när skriptet körs en gång. Det gör du genom att se till att dina Get-TargetResource och Test-TargetResource -funktioner lämnar resursen oförändrad, och att anrop av Set-TargetResource funktionen mer än en gång i en sekvens med samma parametervärden alltid motsvarar att anropa den en gång.

I funktionsimplementeringen Get-TargetResource använder du de viktiga resursegenskapsvärden som anges som parametrar för att kontrollera statusen för den angivna resursinstansen. Den här funktionen måste returnera en hash-tabell som visar alla resursegenskaper som nycklar och de faktiska värdena för dessa egenskaper som motsvarande värden. Följande kod innehåller ett exempel.

# 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
}

Beroende på de värden som anges för resursegenskaperna i konfigurationsskriptet Set-TargetResource måste du göra något av följande:

  • Skapa en ny webbplats
  • Uppdatera en befintlig webbplats
  • Ta bort en befintlig webbplats

Följande exempel illustrerar detta.

# 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
    #>
}

Slutligen Test-TargetResource måste funktionen ha samma parameteruppsättning som Get-TargetResource och Set-TargetResource. I implementeringen av Test-TargetResourcekontrollerar du statusen för resursinstansen som anges i nyckelparametrarna. Om resursinstansens faktiska status inte matchar de värden som anges i parameteruppsättningen returnerar du $false. Annars returnerar du $true.

Följande kod implementerar Test-TargetResource funktionen.

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
}

Anteckning

För enklare felsökning använder du cmdleten Write-Verbose i implementeringen av de föregående tre funktionerna. Den här cmdleten skriver text till den utförliga meddelandeströmmen. Som standard visas inte den utförliga meddelandeströmmen, men du kan visa den genom att ändra värdet för variabeln $VerbosePreference eller med hjälp av parametern Verbose i DSC-cmdletarna = ny.

Skapa modulmanifestet

Använd slutligen cmdleten New-ModuleManifest för att definiera en <ResourceName>.psd1 fil för din anpassade resursmodul. När du anropar den här cmdleten refererar du till skriptmodulfilen (.psm1) som beskrivs i föregående avsnitt. Inkludera Get-TargetResource, Set-TargetResourceoch Test-TargetResource i listan över funktioner som ska exporteras. Följande är en exempelmanifestfil.

# 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 = ''
}

Stöd för PsDscRunAsCredential

Anteckning

PsDscRunAsCredential stöds i PowerShell 5.0 och senare.

Egenskapen PsDscRunAsCredential kan användas i resursblocket för DSC-konfigurationer för att ange att resursen ska köras under en angiven uppsättning autentiseringsuppgifter. Mer information finns i Köra DSC med användarautentiseringsuppgifter.

Om du vill komma åt användarkontexten inifrån en anpassad resurs kan du använda den automatiska variabeln $PsDscContext.

Följande kod skulle till exempel skriva användarkontexten under vilken resursen körs till den utförliga utdataströmmen:

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

Starta om noden

Om de åtgärder som vidtas i funktionen Set-TargetResource kräver en omstart kan du använda en global flagga för att instruera LCM att starta om noden. Den här omstarten Set-TargetResource sker direkt när funktionen har slutförts.

Set-TargetResource Lägg till följande kodrad i funktionen.

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

För att LCM ska kunna starta om noden måste flaggan RebootNodeIfNeeded vara inställd på $true. Inställningen ActionAfterReboot bör också anges till ContinueConfiguration, vilket är standardinställningen. Mer information om hur du konfigurerar LCM finns i Konfigurera den lokala Configuration Manager eller Konfigurera den lokala Configuration Manager (v4).