Verwenden von Import-DscResource

Gilt für: PowerShell 7, Das Azure Automanage-Computerkonfigurationsfeature

Import-DSCResourceist eine dynamische Schlüsselwort (keyword), die nur innerhalb eines Configuration Blocks verwendet werden kann, um alle Ressourcen zu importieren, die in Ihrer DSC-Konfiguration erforderlich sind. DSC-Ressourcen unter $PSHOME werden automatisch importiert. Es empfiehlt sich jedoch, alle DSC-Ressourcen, die in Ihrer DSC-Konfiguration verwendet werden, explizit zu importieren.

Die Syntax für Import-DSCResource ist unten dargestellt. Wenn Sie Module anhand des Namens angeben, ist es erforderlich, jedes in einer neuen Zeile aufzulisten.

Import-DscResource [-Name <ResourceName(s)>]
 [-ModuleName <ModuleName>]
 [-ModuleVersion <ModuleVersion>]

Parameter

• Name : Die Ressourcen, die Sie importieren müssen. Wenn der Modulname angegeben ist, sucht der Befehl in diesem Modul nach diesen DSC-Ressourcen. Andernfalls durchsucht der Befehl die DSC-Ressourcen in allen Modulen. Platzhalter werden unterstützt.
• ModuleName : Der Modulname oder die Modulspezifikation. Wenn Sie DSC-Ressourcen angeben, die aus einem Modul importiert werden sollen, versucht der Befehl, nur diese DSC-Ressourcen zu importieren. Wenn Sie nur das Modul angeben, importiert der Befehl alle DSC-Ressourcen im Modul.
• ModuleVersion : Sie können die Version eines Moduls angeben, das eine Konfiguration mit diesem Parameter verwenden soll. Standardmäßig wird die neueste verfügbare Version der DSC-Ressource importiert.

Import-DSCResource -ModuleName xActiveDirectory

Beispiel: Verwenden von Import-DSCResource innerhalb einer DSC-Konfiguration

Configuration MSDSCConfiguration {
    # Search for and imports two DSC Resources from the PSDscResources module.
    Import-DSCResource -ModuleName PSDscResources -Name Service, Registry

    # Search for and import Resource1 from the module that defines it. If only
    # the -Name parameter is used then resources can belong to different
    # PowerShell modules as well. TimeZone resource is from the
    # ComputerManagementDSC module which is not installed by default. As a best
    # practice, list each requirement on a different line if possible.  This
    # makes reviewing  multiple changes in source control a bit easier.
    Import-DSCResource -Name Service
    Import-DSCResource -Name TimeZone

    # Search for and import all DSC resources inside the PSDscResources module.
    # When specifying the ModuleName parameter, it is a requirement to list each
    # on a new line.
    Import-DSCResource -ModuleName PSDscResources
    # You can specify a ModuleVersion parameter
    Import-DSCResource -ModuleName ComputerManagementDsc -ModuleVersion 6.0.0.0
...

Hinweis

Das Angeben mehrerer Werte für DSC-Ressourcennamen und Modulnamen in demselben Befehl wird nicht unterstützt. Es kann ein nicht deterministisches Verhalten darüber aufweisen, welche DSC-Ressource aus welchem Modul geladen werden soll, wenn dieselbe DSC-Ressource in mehreren Modulen vorhanden ist. Der folgende Befehl gibt während der Kompilierung einen fehler zurück.

Import-DSCResource -Name Service, TimeZone -ModuleName PSDscResources, xPSDesiredStateConfiguration

Zu beachtende Punkte, wenn Sie nur den Name-Parameter verwenden:

• Es handelt sich um einen ressourcenintensiven Vorgang, der von der Anzahl der auf dem Computer installierten Module abhängt.
• Es wird die erste DSC-Ressource geladen, die mit dem angegebenen Namen gefunden wurde. Wenn mehr als eine DSC-Ressource mit demselben Namen installiert ist, kann die falsche DSC-Ressource geladen werden.

Die empfohlene Verwendung besteht darin, ModuleName mit dem Parameter Name anzugeben, wie unten beschrieben.

Dies bietet folgende Vorteile:

• Sie reduziert die Auswirkungen auf die Leistung, indem der Suchbereich für die angegebene DSC-Ressource eingeschränkt wird.
• Es definiert explizit das Modul, das die DSC-Ressource bereitstellt, und stellt sicher, dass die richtige DSC-Ressource geladen wird.

Hinweis

DSC-Ressourcen können mehrere Versionen haben, und Versionen können parallel auf einem Computer installiert werden. Dies wird durch mehrere Versionen eines DSC-Ressourcenmoduls implementiert, die im selben Modulordner enthalten sind.

IntelliSense mit Import-DSCResource

Beim Erstellen der DSC-Konfiguration in VS Code stellt PowerShell IntelliSense für DSC-Ressourcen und DSC-Ressourceneigenschaften bereit. Ressourcendefinitionen unter dem $PSHOME-Modulpfad werden automatisch geladen. Wenn Sie DSC-Ressourcen mithilfe des Import-DSCResource Schlüsselwort (keyword) importieren, werden die angegebenen DSC-Ressourcendefinitionen hinzugefügt, und IntelliSense wird erweitert, um die importierten DSC-Ressourcenschemas einzuschließen.

Beim Kompilieren der DSC-Konfiguration verwendet PowerShell die importierten DSC-Ressourcendefinitionen, um die DSC-Ressourcenblöcke im Configuration Block zu überprüfen. Jeder DSC-Ressourcenblock wird anhand der Schemadefinition der DSC-Ressource für die folgenden Regeln überprüft:

• Es werden nur eigenschaften angegeben, die im Schema definiert sind.
• Die Datentypen für jede Eigenschaft sind korrekt.
• Schlüsseleigenschaften werden angegeben.
• Es wird keine schreibgeschützte Eigenschaft angegeben.

Berücksichtigen Sie die folgende DSC-Konfiguration:

Configuration SchemaValidationInCorrectEnumValue {
    Import-DSCResource -Name User -Module PSDscResources

    User ExampleUser {
        UserName = 'ExampleDscUser'
        Ensure   = 'Invalid'
    }
}

Das Kompilieren dieser DSC-Konfiguration führt zu einem Fehler.

Write-Error: C:\code\dsc\sample.ps1:4:5
Line |
   4 |      User ExampleUser {
     |      ~~~~
     | At least one of the values 'Invalid' is not supported or   
     | valid for property 'Ensure' on class 'User'. Please specify
     | only supported values: Present, Absent.

InvalidOperation: Errors occurred while processing configuration
'SchemaValidationInCorrectEnumValue'.

IntelliSense und die Schemaüberprüfung ermöglichen es Ihnen, mehr Fehler während der Analyse- und Kompilierungszeit abzufangen, um zukünftige Komplikationen zu vermeiden.

Hinweis

Jede DSC-Ressource kann einen Namen und einen FriendlyName haben, der durch das Schema der DSC-Ressource definiert ist. Unten sind die ersten beiden Zeilen von MSFT_UserResource.schema.mofaufgeführt.

[ClassVersion("1.0.0"), FriendlyName("User")]
class MSFT_UserResource : OMI_BaseResource

Wenn Sie diese DSC-Ressource in einem Configuration Block verwenden, können Sie oder UserangebenMSFT_UserResource.

Weitere Informationen

• Ressourcen