Pisanie niestandardowego zasobu DSC za pomocą narzędzia MOF

  • Artykuł

Dotyczy: Windows PowerShell 4.0, Windows PowerShell 5.0

W tym artykule zdefiniujemy schemat zasobu niestandardowego Windows PowerShell Desired State Configuration (DSC) w pliku MOF i zaimplementujemy zasób w pliku skryptu Windows PowerShell. Ten zasób niestandardowy służy do tworzenia i obsługi witryny sieci Web.

Tworzenie schematu MOF

Schemat definiuje właściwości zasobu, które można skonfigurować za pomocą skryptu konfiguracji DSC.

Struktura folderów dla zasobu MOF

Aby zaimplementować zasób niestandardowy DSC przy użyciu schematu MOF, utwórz następującą strukturę folderów. Schemat MOF jest zdefiniowany w pliku Demo_IISWebsite.schema.mof, a skrypt zasobu jest zdefiniowany w pliku Demo_IISWebsite.psm1. Opcjonalnie możesz utworzyć plik manifestu modułu (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)

Uwaga

Należy utworzyć folder o nazwie DSCResources w folderze najwyższego poziomu, a folder dla każdego zasobu musi mieć taką samą nazwę jak zasób.

Zawartość pliku MOF

Poniżej znajduje się przykładowy plik MOF, którego można użyć dla niestandardowego zasobu witryny internetowej. Aby skorzystać z tego przykładu, zapisz ten schemat w pliku i wywołaj plik 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;
};

Zwróć uwagę na następujące informacje o poprzednim kodzie:

  • FriendlyName definiuje nazwę, której można użyć do odwoływania się do tego zasobu niestandardowego w skryptach konfiguracji DSC. W tym przykładzie Website jest odpowiednikiem przyjaznej nazwy Archive wbudowanego zasobu Archiwum.
  • Klasa zdefiniowana dla zasobu niestandardowego musi pochodzić z klasy OMI_BaseResource.
  • Kwalifikator typu , [Key]we właściwości wskazuje, że ta właściwość będzie jednoznacznie identyfikować wystąpienie zasobu. Wymagana jest co najmniej jedna [Key] właściwość.
  • [Required] Kwalifikator wskazuje, że właściwość jest wymagana (wartość musi być określona w dowolnym skrypcie konfiguracji, który używa tego zasobu).
  • [write] Kwalifikator wskazuje, że ta właściwość jest opcjonalna w przypadku używania zasobu niestandardowego w skry skrycie konfiguracji. [read] Kwalifikator wskazuje, że nie można ustawić właściwości przez konfigurację i służy tylko do celów raportowania.
  • Values Ogranicza wartości, które można przypisać do właściwości do listy wartości zdefiniowanych w ValueMappliku . Aby uzyskać więcej informacji, zobacz ValueMap and Value Qualifiers (Kwalifikatory wartości).
  • Dołączenie właściwości o nazwie Ensure z wartościami Present i Absent w zasobie jest zalecane jako sposób zachowania spójnego stylu z wbudowanymi zasobami DSC.
  • Nazwij plik schematu zasobu niestandardowego w następujący sposób: classname.schema.mof, gdzie classname jest identyfikatorem zgodnym ze class słowem kluczowym w definicji schematu.

Pisanie skryptu zasobu

Skrypt zasobu implementuje logikę zasobu. W tym module należy uwzględnić trzy funkcje o nazwie Get-TargetResource, Set-TargetResourcei Test-TargetResource. Wszystkie trzy funkcje muszą przyjmować zestaw parametrów identyczny z zestawem właściwości zdefiniowanych w schemacie MOF utworzonym dla zasobu. W tym dokumencie ten zestaw właściwości jest określany jako "właściwości zasobu". Przechowuj te trzy funkcje w pliku o nazwie <ResourceName>.psm1. W poniższym przykładzie funkcje są przechowywane w pliku o nazwie Demo_IISWebsite.psm1.

Uwaga

Po uruchomieniu tego samego skryptu konfiguracji w zasobie więcej niż raz, nie powinien zostać wyświetlony żaden błąd, a zasób powinien pozostawać w tym samym stanie co uruchomienie skryptu raz. Aby to osiągnąć, upewnij się, że funkcje Get-TargetResource i Test-TargetResource pozostawiają zasób bez zmian, a wywołanie Set-TargetResource funkcji więcej niż raz w sekwencji z tymi samymi wartościami parametrów jest zawsze równoważne wywołaniu go raz.

W implementacji Get-TargetResource funkcji użyj wartości właściwości zasobu klucza, które są podane jako parametry, aby sprawdzić stan określonego wystąpienia zasobu. Ta funkcja musi zwrócić tabelę skrótów, która wyświetla wszystkie właściwości zasobu jako klucze i rzeczywiste wartości tych właściwości jako odpowiednie wartości. Poniższy kod zawiera przykład.

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

W zależności od wartości określonych dla właściwości zasobu w skry skrycie Set-TargetResource konfiguracji należy wykonać jedną z następujących czynności:

  • Tworzenie nowej witryny internetowej
  • Aktualizowanie istniejącej witryny internetowej
  • Usuwanie istniejącej witryny internetowej

Ilustruje to poniższy przykład.

# 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 Na koniec funkcja musi przyjmować ten sam zestaw parametrów co Get-TargetResource i Set-TargetResource. W implementacji programu Test-TargetResourcesprawdź stan wystąpienia zasobu określonego w kluczowych parametrach. Jeśli rzeczywisty stan wystąpienia zasobu nie jest zgodny z wartościami określonymi w zestawie parametrów, zwróć wartość $false. W przeciwnym razie zwróć wartość $true.

Poniższy kod implementuje Test-TargetResource funkcję .

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
}

Uwaga

Aby ułatwić debugowanie, użyj Write-Verbose polecenia cmdlet w implementacji poprzednich trzech funkcji. To polecenie cmdlet zapisuje tekst do pełnego strumienia komunikatów. Domyślnie pełny strumień komunikatów nie jest wyświetlany, ale można go wyświetlić, zmieniając wartość zmiennej $VerbosePreference lub używając parametru Verbose w poleceniach cmdlet DSC = nowe.

Tworzenie manifestu modułu

Na koniec użyj New-ModuleManifest polecenia cmdlet , aby zdefiniować <ResourceName>.psd1 plik dla niestandardowego modułu zasobów. Po wywołaniu tego polecenia cmdlet należy odwołać się do pliku modułu skryptu (psm1) opisanego w poprzedniej sekcji. Uwzględnij Get-TargetResourcefunkcje , Set-TargetResourcei Test-TargetResource na liście funkcji do wyeksportowania. Poniżej znajduje się przykładowy plik 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 = ''
}

Obsługa elementu PsDscRunAsCredential

Uwaga

Program PsDscRunAsCredential jest obsługiwany w programie PowerShell 5.0 lub nowszym.

Właściwość PsDscRunAsCredential może być używana w bloku zasobów konfiguracji DSC , aby określić, że zasób powinien być uruchamiany w ramach określonego zestawu poświadczeń. Aby uzyskać więcej informacji, zobacz Running DSC with user credentials (Uruchamianie rozszerzenia DSC przy użyciu poświadczeń użytkownika).

Aby uzyskać dostęp do kontekstu użytkownika z poziomu zasobu niestandardowego, możesz użyć zmiennej automatycznej $PsDscContext.

Na przykład poniższy kod będzie zapisywać kontekst użytkownika, w którym zasób jest uruchomiony do pełnego strumienia wyjściowego:

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

Ponowne uruchamianie węzła

Jeśli akcje wykonywane w Set-TargetResource funkcji wymagają ponownego uruchomienia, możesz użyć flagi globalnej, aby poinformować narzędzie LCM o ponownym uruchomieniu węzła. Ten ponowny rozruch odbywa się bezpośrednio po zakończeniu Set-TargetResource działania funkcji.

Set-TargetResource Wewnątrz funkcji dodaj następujący wiersz kodu.

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

Aby program LCM mógł ponownie uruchomić węzeł, flaga RebootNodeIfNeeded musi być ustawiona na $truewartość . Ustawienie ActionAfterReboot powinno być również ustawione na Wartość KontynuujKonfiguracja, która jest wartością domyślną. Aby uzyskać więcej informacji na temat konfigurowania programu LCM, zobacz Konfigurowanie Configuration Manager lokalnego lub Konfigurowanie lokalnej Configuration Manager (wersja 4).