Erstellen einer MOF-basierten DSC-Ressource
In diesem Artikel erfahren Sie, wie Sie eine MOF-basierte DSC-Ressource erstellen können, indem Sie ein Schema schreiben und ein Skriptmodul zum Verwalten einer IIS-Website entwickeln.
Wichtig
Ab DSC 3.0 werden MOF-basierte DSC-Ressourcen nicht unterstützt. Wenn Sie eine neue DSC-Ressource schreiben und möchten, dass sie mit zukünftigen Versionen funktioniert, schreiben Sie stattdessen eine klassenbasierte DSC-Ressource .
Schreiben des MOF-Schemas
Eine MOF-basierte DSC-Ressource muss über eine Schemadatei (.mof) verfügen, die die verwaltbaren Einstellungen für eine Softwarekomponente definiert.
Erstellen der erforderlichen Ordnerstruktur
Erstellen Sie die folgende Ordnerstruktur. Das Schema ist in der Datei Demo_IISWebsite.schema.mofdefiniert, und die erforderlichen Funktionen werden in Demo_IISWebsite.psm1definiert.
Optional können Sie eine Modulmanifestdatei (.psd1) erstellen.
$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)
Hinweis
Sie müssen einen Ordner mit dem Namen DSCResources unter dem Ordner der obersten Ebene Ihres Moduls erstellen. Der Ordner für jede DSC-Ressource muss denselben Namen wie die DSC-Ressource haben.
Inhalt der MOF-Datei
Im Folgenden finden Sie eine MOF-Beispieldatei, die die Eigenschaften einer Website für die DSC-Ressource beschreibt. Um diesem Beispiel zu folgen, speichern Sie dieses Schema in einer Datei mit dem Namen 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;
};
Beachten Sie Folgendes im Zusammenhang mit dem vorherigen Code:
- FriendlyName definiert den Namen, den Sie verwenden können, um auf diese DSC-Ressource zu verweisen. In diesem Beispiel ist
WebsitefriendlyName . - Die Klasse Ihrer DSC-Ressource muss von abgeleitet werden
OMI_BaseResource. - Der Typqualifizierer (
[Key]) für eine Eigenschaft gibt an, dass diese Eigenschaft die Ressource instance eindeutig identifiziert. Jede DSC-Ressource muss mindestens eine[Key]Eigenschaft aufweisen. - Der
[Required]Qualifizierer gibt an, dass die -Eigenschaft bei Verwendung dieser DSC-Ressource obligatorisch ist. - Der
[write]Qualifizierer gibt an, dass diese Eigenschaft optional ist. - Der
[read]Qualifizierer gibt an, dass eine Eigenschaft nicht von der DSC-Ressource festgelegt werden kann, und dient nur zu Berichterstellungszwecken. - Werte schränkt die Werte, die der Eigenschaft zugewiesen werden können, auf die Liste der werte ein, die in valueMap definiert sind. Weitere Informationen finden Sie unter Die Qualifizierer „ValueMap“ und „Value“.
- Für DSC-Ressourcen, die ein Benutzer hinzufügen und aus einem System entfernen kann, wird empfohlen, eine Eigenschaft namens Ensure mit den Werten
PresentundAbsentin Ihrer DSC-Ressource hinzuzufügen. - Benennen Sie die Schemadatei für Ihre DSC-Ressource wie folgt:
<classname>.schema.mof, wobei<classname>der Bezeichner ist, der demclassSchlüsselwort (keyword) in Ihrer Schemadefinition folgt.
Schreiben des Skriptmoduls
Das Skriptmodul einer MOF-basierten DSC-Ressource implementiert die Logik der DSC-Ressource. In diesem Modul fügen Sie die drei Funktionen Get-TargetResource, Set-TargetResource, und Test-TargetResource hinzu. Alle drei Funktionen müssen einen Parametersatz annehmen, der mit dem Satz von Eigenschaften identisch ist, der im Schema der DSC-Ressource definiert ist. Speichern Sie diese drei Funktionen in einer Datei mit dem Namen <ResourceName>.psm1. Im folgenden Beispiel werden die Funktionen in einer Datei namens Demo_IISWebsite.psm1gespeichert.
Hinweis
Wenn Sie verwenden Invoke-DscResource , um den gewünschten Zustand mit den gleichen Eigenschaften mehrmals festzulegen, sollten Sie keine Fehler erhalten, und das System sollte im gleichen Zustand wie nach der ersten Verwendung verbleiben. Stellen Sie dazu sicher, dass die Get-TargetResource Funktionen und Test-TargetResource das System unverändert bleiben und dass das Aufrufen der Set-TargetResource Funktion mehrmals in einer Sequenz mit denselben Parameterwerten immer mit dem einmaligen Aufrufen der Funktion identisch ist.
Verwenden Sie in der Get-TargetResource Funktionsimplementierung die Key-Eigenschaftswerte, die als Parameter bereitgestellt werden, um den Zustand der angegebenen instance der DSC-Ressource zu überprüfen. Diese Funktion muss eine Hashtabelle zurückgeben, die alle DSC-Ressourceneigenschaften als Schlüssel und die tatsächlichen Werte dieser Eigenschaften als entsprechende Werte auflistet. Der folgende Code gibt ein Beispiel.
# 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
}
Abhängig von den Werten, die ein Benutzer für die Eigenschaften der DSC-Ressource angibt, Set-TargetResource muss eine der folgenden Aktionen ausgeführt werden:
- Hinzufügen einer neuen Website
- Aktualisieren einer vorhandenen Website
- Entfernen einer vorhandenen Website
Dies wird anhand des folgenden Beispiels veranschaulicht.
# 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
#>
}
Schließlich muss die Funktion Test-TargetResource den gleichen Parametersatz verwenden wie Get-TargetResource und Set-TargetResource. Überprüfen Sie in Ihrer Implementierung von Test-TargetResourceden im Parametersatz angegebenen Werten den aktuellen Zustand des Systems. Wenn der aktuelle Zustand nicht mit dem gewünschten Zustand übereinstimmt, geben Sie zurück $false. Andernfalls wird $true zurückgegeben.
Der folgende Code implementiert die Funktion 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
$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
}
Hinweis
Verwenden Sie zum einfacheren Debuggen in Ihrer Implementierung der vorherigen drei Funktionen das Cmdlet Write-Verbose. Dieses Cmdlet schreibt Text in den Stream für ausführliche Meldungen. Standardmäßig wird der ausführliche Nachrichtenstream nicht angezeigt. Sie können ihn jedoch anzeigen, indem Sie den Wert der $VerbosePreference Variablen ändern oder den Verbose-Parameter mit Invoke-DscResourceverwenden.
Erstellen das Modulmanifest
Verwenden Sie schließlich das New-ModuleManifest Cmdlet, um eine <ResourceName>.psd1 Datei für Ihr DSC-Ressourcenmodul zu definieren. Verwenden Sie die im vorherigen Abschnitt beschriebene Skriptmoduldatei (.psm1) als Wert des NestedModules-Parameters . Schließen Sie Get-TargetResource, Set-TargetResourceund Test-TargetResource als Werte für den FunctionsToExport-Parameter ein.
$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'
)
}
Neustarten des Systems
Wenn die in Ihrer Set-TargetResource Funktion ausgeführten Aktionen einen Neustart erfordern, können Sie ein globales Flag verwenden, um den Aufrufer anzufordern, das System neu zu starten.
Fügen Sie die folgende Codezeile in Ihre Set-TargetResource-Funktion ein.
# Include this line if the system requires a reboot.
$global:DSCMachineStatus = 1
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für