Sdílet prostřednictvím

Zápis vlastního prostředku DSC pomocí MOF

  • Článek

Platí pro: Windows PowerShell 4.0, Windows PowerShell 5.0

V tomto článku definujeme schéma pro vlastní prostředek Windows PowerShell Desired State Configuration (DSC) v souboru MOF a implementujeme prostředek do souboru Windows PowerShell skriptu. Tento vlastní prostředek slouží k vytváření a údržbě webu.

Vytvoření schématu MOF

Schéma definuje vlastnosti prostředku, které lze nakonfigurovat konfiguračním skriptem DSC.

Struktura složek pro prostředek MOF

Pokud chcete implementovat vlastní prostředek DSC se schématem MOF, vytvořte následující strukturu složek. Schéma MOF je definováno v souboru Demo_IISWebsite.schema.mofa skript prostředku je definován v Demo_IISWebsite.psm1souboru . Volitelně můžete vytvořit soubor manifestu modulu (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)

Poznámka

Je nutné vytvořit složku s názvem DSCResources ve složce nejvyšší úrovně a že složka pro každý prostředek musí mít stejný název jako prostředek.

Obsah souboru MOF

Následuje příklad souboru MOF, který lze použít pro vlastní prostředek webu. Pokud chcete postupovat podle tohoto příkladu, uložte toto schéma do souboru a zavolejte soubor 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;
};

Všimněte si následujících informací o předchozím kódu:

  • FriendlyName definuje název, který můžete použít k odkazování na tento vlastní prostředek v konfiguračních skriptech DSC. V tomto příkladu Website je ekvivalentem popisného názvu Archive integrovaného prostředku archivu.
  • Třída, kterou definujete pro vlastní prostředek, musí být odvozena z OMI_BaseResource.
  • Kvalifikátor typu u vlastnosti označuje, [Key]že tato vlastnost jednoznačně identifikuje instanci prostředku. Vyžaduje se alespoň jedna [Key] vlastnost.
  • Kvalifikátor [Required] označuje, že vlastnost je povinná (hodnota musí být zadána v každém konfiguračním skriptu, který tento prostředek používá).
  • Kvalifikátor [write] označuje, že tato vlastnost je volitelná při použití vlastního prostředku v konfiguračním skriptu. Kvalifikátor [read] označuje, že vlastnost nemůže být nastavena konfigurací a slouží pouze pro účely generování sestav.
  • Values omezuje hodnoty, které lze přiřadit vlastnosti na seznam hodnot definovaných v nástroji ValueMap. Další informace najdete v tématech ValueMap a Value Kvalifikátory.
  • Jako způsob zachování konzistentního stylu s integrovanými prostředky DSC se doporučuje zahrnout vlastnost s hodnotami EnsurePresent a Absent do prostředku.
  • Soubor schématu pro vlastní prostředek pojmenujte takto: classname.schema.mof, kde classname je identifikátor, který následuje za klíčovým slovem class v definici schématu.

Psaní skriptu prostředků

Skript prostředku implementuje logiku prostředku. V tomto modulu musíte zahrnout tři funkce s názvem Get-TargetResource, Set-TargetResourcea Test-TargetResource. Všechny tři funkce musí mít sadu parametrů, která je shodná se sadou vlastností definovaných ve schématu MOF, které jste vytvořili pro váš prostředek. V tomto dokumentu se tato sada vlastností označuje jako "vlastnosti prostředku". Tyto tři funkce uložte do souboru s názvem <ResourceName>.psm1. V následujícím příkladu jsou funkce uložené v souboru s názvem Demo_IISWebsite.psm1.

Poznámka

Při více než jednom spuštění stejného konfiguračního skriptu u prostředku by se neměly zobrazit žádné chyby a prostředek by měl zůstat ve stejném stavu jako spuštění skriptu jednou. Abyste toho dosáhli, ujistěte se, že funkce Get-TargetResource a Test-TargetResource ponechají prostředek beze změny a že vyvolání Set-TargetResource funkce více než jednou v posloupnosti se stejnými hodnotami parametrů je vždy ekvivalentní volání jednou.

V implementaci Get-TargetResource funkce pomocí klíčových hodnot vlastností prostředku, které jsou zadané jako parametry, zkontrolujte stav zadané instance prostředku. Tato funkce musí vrátit hashovací tabulku, která uvádí všechny vlastnosti prostředku jako klíče a skutečné hodnoty těchto vlastností jako odpovídající hodnoty. Následující kód poskytuje příklad.

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

V závislosti na hodnotách, které jsou zadány pro vlastnosti prostředku v konfiguračním Set-TargetResource skriptu, musí provést jednu z následujících akcí:

  • Vytvoření nového webu
  • Aktualizace existujícího webu
  • Odstranění existujícího webu

Toto dokládá následující příklad.

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

Test-TargetResource Nakonec musí funkce převzít stejnou sadu parametrů jako Get-TargetResource a Set-TargetResource. V implementaci Test-TargetResourcezkontrolujte stav instance prostředku, která je zadána v klíčových parametrech. Pokud skutečný stav instance prostředku neodpovídá hodnotám zadaným v sadě parametrů, vraťte $false. V opačném případě vraťte $true.

Následující kód implementuje Test-TargetResource funkci.

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
}

Poznámka

Pro snadnější ladění použijte rutinu Write-Verbose v implementaci předchozích tří funkcí. Tato rutina zapisuje text do podrobného datového proudu zpráv. Ve výchozím nastavení se podrobný datový proud zpráv nezobrazuje, ale můžete ho zobrazit změnou hodnoty proměnné $VerbosePreference nebo pomocí parametru Verbose v rutinách DSC = new.

Vytvoření manifestu modulu

Nakonec pomocí rutiny New-ModuleManifest definujte <ResourceName>.psd1 soubor pro modul vlastních prostředků. Při vyvolání této rutiny se odkažte na soubor modulu skriptu (.psm1) popsaný v předchozí části. Do seznamu funkcí, které chcete exportovat, zahrňte Get-TargetResource, aTest-TargetResource. Set-TargetResource Následuje příklad souboru manifestu.

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

Podpora PsDscRunAsCredential

Poznámka

PsDscRunAsCredential se podporuje v PowerShellu 5.0 a novějších verzích.

Vlastnost PsDscRunAsCredential lze použít v bloku prostředků konfigurace DSC k určení, že se prostředek má spustit pod zadanou sadou přihlašovacích údajů. Další informace najdete v tématu Spuštění DSC s přihlašovacími údaji uživatele.

Pokud chcete získat přístup k kontextu uživatele z vlastního prostředku, můžete použít automatickou proměnnou $PsDscContext.

Například následující kód zapíše kontext uživatele, ve kterém je prostředek spuštěný, do podrobného výstupního streamu:

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

Restartování uzlu

Pokud akce provedené ve vaší Set-TargetResource funkci vyžadují restartování, můžete pomocí globálního příznaku informovat LCM o restartování uzlu. K tomuto restartování dojde přímo po Set-TargetResource dokončení funkce.

Do funkce Set-TargetResource přidejte následující řádek kódu.

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

Aby mohl LCM restartovat uzel, musí být příznak RebootNodeIfNeeded nastavený na $true. Nastavení ActionAfterReboot by také mělo být nastaveno na ContinueConfiguration, což je výchozí nastavení. Další informace o konfiguraci LCM najdete v tématu Konfigurace místního Configuration Manager nebo Konfigurace místního Configuration Manager (v4).