Vytváření prostředku DSC založeného na MOF

Článek
03/08/2024

Tento článek ukazuje, jak můžete vytvořit prostředek DSC založený na MOF napsáním schématu a vývojem modulu skriptu pro správu webu služby IIS.

Důležité

Od verze DSC 3.0 se nepodporují prostředky DSC založené na MOF. Pokud píšete nový prostředek DSC a chcete, aby fungoval s budoucími verzemi, napište místo toho prostředek DSC založený na třídě .

Vytvoření schématu MOF

Prostředek DSC založený na MOF musí mít soubor schématu (.mof), který definuje spravovatelná nastavení pro softwarovou komponentu.

Vytvoření požadované struktury složek

Vytvořte následující strukturu složek. Schéma je definováno v souboru Demo_IISWebsite.schema.mofa požadované funkce jsou definovány v Demo_IISWebsite.psm1souboru . Volitelně můžete vytvořit soubor manifestu (.psd1) modulu.

$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

Ve složce nejvyšší úrovně modulu musíte vytvořit složku s názvem DSCResources . Složka pro každý prostředek DSC musí mít stejný název jako prostředek DSC.

Obsah souboru MOF

Následuje příklad souboru MOF, který popisuje vlastnosti webu pro prostředek DSC. Pokud chcete postupovat podle tohoto příkladu, uložte toto schéma do souboru s názvem 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 pro odkaz na tento prostředek DSC. V tomto příkladu je WebsiteFriendlyName .
Třída prostředku DSC musí být odvozena z OMI_BaseResource.
Kvalifikátor typu u vlastnosti označuje, [Key]že tato vlastnost jednoznačně identifikuje instanci prostředku. Každý prostředek DSC musí mít aspoň jednu [Key] vlastnost.
Kvalifikátor [Required] označuje, že vlastnost je při použití tohoto prostředku DSC povinná.
Kvalifikátor [write] označuje, že tato vlastnost je volitelná.
Kvalifikátor [read] označuje, že prostředek DSC nemůže nastavit vlastnost a slouží pouze pro účely generování sestav.
Hodnoty omezují hodnoty, které lze přiřadit vlastnosti na seznam hodnot definovaných v ValueMap. Další informace najdete v tématech ValueMap a Value Kvalifikátory.
Pro prostředky DSC, které může uživatel přidat a odebrat ze systému, se doporučuje zahrnout vlastnost s názvem Zajistit s hodnotami Present a Absent ve vašem prostředku DSC.
Pojmenujte soubor schématu pro prostředek DSC takto: <classname>.schema.mof, kde <classname> je identifikátor, který následuje za klíčovým slovem class v definici schématu.

Psaní modulu skriptu

Skriptovací modul prostředku DSC založený na MOF implementuje logiku prostředku DSC. 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 identická se sadou vlastností definovaných ve schématu prostředku DSC. Uložte tyto tři funkce do souboru s názvem <ResourceName>.psm1. V následujícím příkladu jsou funkce uloženy v souboru s názvem Demo_IISWebsite.psm1.

Poznámka

Pokud použijete Invoke-DscResource k nastavení požadovaného stavu se stejnými vlastnostmi více než jednou, neměly by se zobrazit žádné chyby a systém by měl zůstat ve stejném stavu jako po prvním použití. Chcete-li to provést, ujistěte se, že funkce Get-TargetResource a Test-TargetResource ponechá systém beze změny a že vyvolání Set-TargetResource funkce více než jednou v sekvenci se stejnými hodnotami parametrů je vždy stejné jako vyvolání jednou.

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

# The Get-TargetResource function is used to retrieve the current state of a
# website on the system.
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 hashtable
        # This 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é uživatel zadá pro vlastnosti prostředku DSC, Set-TargetResource musí provést jednu z následujících věcí:

Přidání nového webu
Aktualizace existujícího webu
Odebrání existujícího webu

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

# The Set-TargetResource function is used to add, update, or remove a website
# on the system.
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 doesn't exist, then add 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-TargetResourcenástroje ověřte aktuální stav systému podle hodnot zadaných v sadě parametrů. Pokud aktuální stav neodpovídá požadovanému stavu, 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
    $getParameters = @{
        Ensure          = $Ensure 
        Name            = $Name 
        PhysicalPath    = $PhysicalPath 
        State           = $State 
        ApplicationPool = $ApplicationPool 
        BindingInfo     = $BindingInfo 
        Protocol        = $Protocol
    }
    $currentState = Get-TargetResource @getParameters

    # 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 $VerbosePreference zobrazit změnou hodnoty proměnné nebo použitím parametru Verbose s Invoke-DscResource.

Vytvoření manifestu modulu

Nakonec pomocí rutiny New-ModuleManifest definujte <ResourceName>.psd1 soubor pro modul prostředků DSC. Jako hodnotu parametru NestedModules použijte soubor modulu skriptu (.psm1) popsaný v předchozí části. Set-TargetResourceJako hodnoty parametru FunctionsToExport zahrňte Get-TargetResource, aTest-TargetResource.

$ManifestParameters = @{
    Path              = 'Demo_IISWebsite.psd1'
    NestedModules     = 'Demo_IISWebsite.psm1'
    FunctionsToExport = @(
        'Get-TargetResource'
        'Set-TargetResource'
        'Test-TargetResource'
    )
}
New-ModuleManifest @ManifestParameters

@{

# 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 = 'Create and configure IIS websites with DSC.'

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

# 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'
)

}

Restartování systému

Pokud akce provedené ve vaší Set-TargetResource funkci vyžadují restartování, můžete pomocí globálního příznaku říct volajícímu, aby systém restartil.

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

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

Sdílet prostřednictvím

Vytváření prostředku DSC založeného na MOF

Vytvoření schématu MOF

Vytvoření požadované struktury složek

Obsah souboru MOF

Psaní modulu skriptu

Vytvoření manifestu modulu

Restartování systému

Další materiály