DSC-Ressource „File“

Artikel
04/11/2023

Gilt für: Windows PowerShell 4.0, Windows PowerShell 5.x

Die Ressource File in Windows PowerShell DSC bietet einen Mechanismus zum Verwalten von Dateien und Verzeichnissen auf einem Zielknoten. Der Zielknoten muss auf DestinationPath und SourcePath zugreifen können.

Hinweis

Diese Dokumentation dieser DSC-Ressource behandelt die Version, die in PowerShell vor Version 7.2 enthalten ist. Das PSDscResources-Modul enthält neue und aktualisierte DSC-Ressourcen, die offiziell von Microsoft unterstützt werden. Das Modul PSDscResources ist im PowerShell-Katalog verfügbar.

Weitere Informationen und aktualisierte Dokumentation finden Sie in der Referenzdokumentation zu PSDscResources.

Syntax

File [string] #ResourceName
{
    DestinationPath = [string]
    [ Attributes = [string[]] { Archive | Hidden | ReadOnly | System }]
    [ Checksum = [string] { CreatedDate | ModifiedDate | SHA-1 | SHA-256 | SHA-512 } ]
    [ Contents = [string] ]
    [ Credential = [PSCredential] ]
    [ Force = [bool] ]
    [ Recurse = [bool] ]
    [ SourcePath = [string] ]
    [ Type = [string] { Directory | File } ]
    [ MatchSource = [bool] ]
    [ DependsOn = [string[]] ]
    [ Ensure = [string] { Absent | Present } ]
    [ PsDscRunAsCredential = [PSCredential] ]
}

Eigenschaften

Eigenschaft	BESCHREIBUNG
DestinationPath	Der Speicherort auf dem Zielknoten, den Sie sicherstellen möchten, ist Present oder Absent mit Ensure.
Attributes	Der gewünschte Status der Attribute der Zieldatei oder des Zielverzeichnisses. Gültige Werte sind Archive, Hidden, ReadOnly und System.
Checksum	Der zu verwendende Prüfsummentyp, wenn bestimmt wird, ob zwei Dateien identisch sind. Gültige Werte: SHA-1, SHA-256, SHA-512, createdDate, modifiedDate.
Contents	Nur bei der Verwendung mit TypeFile gültig. Gibt den Inhalt an, von dem sichergestellt werden soll (Ensure), ob er in der Zieldatei vorhanden (Present) oder nicht vorhanden (Absent) ist.
Anmeldeinformationen	Die Anmeldeinformationen, die für den Zugriff auf Ressourcen wie z.B. Quelldateien erforderlich sind.
Force	Setzt bestimmte Zugriffsoperationen außer Kraft, die zu einem Fehler führen würden (z.B. das Überschreiben einer Datei oder Löschen eines Verzeichnisses, das nicht leer ist). Der Standardwert ist `$false`.
Recurse	Nur bei der Verwendung mit TypeDirectory gültig. Führt den Statusvorgang rekursiv für den gesamten Verzeichnisinhalt, alle Unterverzeichnisse und den gesamten Unterverzeichnisinhalt aus. Der Standardwert ist `$false`.
SourcePath	Der Pfad, aus dem die Datei- oder Ordnerressource kopiert werden soll.
type	Der Typ der zu konfigurierenden Ressource. Gültige Werte sind Directory und File. Der Standardwert ist File.
MatchSource	Bestimmt, ob die Ressource überwachen sollte, ob dem Quellverzeichnis nach der ersten Kopie neue Dateien hinzugefügt werden. Der Wert `$true` gibt an, dass nach Erstellen der ersten Kopie alle neuen Quelldateien in das Ziel kopiert werden sollten. Bei Festlegung auf `$false` speichert die Ressource den Inhalt des Quellverzeichnisses zwischen und ignoriert alle Dateien, die nach der ersten Kopie hinzugefügt werden. Der Standardwert ist `$false`.

Warnung

Wenn Sie keinen Wert für Credential oder PSRunAsCredential angeben, greift die Ressource mithilfe des Computerkontos des Zielknotens auf den SourcePath zu. Wenn der SourcePath eine UNC-Freigabe ist, könnte dies zu einem „Zugriff verweigert“-Fehler führen. Vergewissern Sie sich, dass Ihre Berechtigungen entsprechend festgelegt sind, oder verwenden Sie die Credential bzw. PSRunAsCredential, um das Konto anzugeben, das verwendet werden sollte.

Allgemeine Eigenschaften

Eigenschaft	BESCHREIBUNG
DependsOn	Gibt an, dass die Konfiguration einer anderen Ressource ausgeführt werden muss, bevor diese Ressource konfiguriert wird. Wenn beispielsweise die ID des Skriptblocks mit der Ressourcenkonfiguration, den Sie zuerst ausführen möchten, „ResourceName“ und dessen Typ „ResourceType“ ist, lautet die Syntax für das Verwenden dieser Eigenschaft `DependsOn = "[ResourceType]ResourceName"`.
Ensure	Legt fest, ob die Datei und Inhalte (Contents) am Ziel (Destination) vorhanden sein sollen oder nicht. Legen Sie diese Eigenschaft auf Present fest, um sicherzustellen, dass die Datei vorhanden ist. Legen Sie sie auf Absent fest, um sicherzustellen, dass der Inhalt nicht vorhanden ist. Der Standardwert ist Present.
PsDscRunAsCredential	Legt die Anmeldeinformationen für die Ausführung der gesamten Ressource fest.

Hinweis

Die allgemeine Eigenschaft PsDscRunAsCredential wurde in WMF 5.0 hinzugefügt, um das Ausführen einer beliebigen DSC-Ressource in Verbindung mit anderen Anmeldeinformationen zu ermöglichen. Weitere Informationen finden Sie unter Use Credentials with DSC Resources (Verwenden von Anmeldeinformationen mit DSC-Ressourcen).

Zusätzliche Informationen

Wenn Sie nur einen Zielpfad (DestinationPath) angeben, stellt die Ressource sicher, ob der Pfad vorhanden (Present) oder nicht vorhanden ist (Absent).
Wenn Sie einen Quellpfad SourcePath und einen Zielpfad (DestinationPath) mit dem Type-Wert Directory angeben, kopiert die Ressource das Quellverzeichnis in den Zielpfad. Die Eigenschaften Recurse, Force und MatchSource ändern den Typ des ausgeführten Kopiervorgangs, während Credential bestimmt, welches Konto für den Zugriff auf das Quellverzeichnis verwendet wird.
Wenn Sie die Eigenschaft Recurse beim Kopieren eines Verzeichnisses nicht auf $true festlegen, wird keinerlei Inhalt des vorhandenen Verzeichnisses kopiert. Es wird nur das angegebene Verzeichnis kopiert.
Wenn Sie den Wert von ReadOnly für die Eigenschaft Attributes neben einem Zielpfad (DestinationPath) angegeben haben, stellen Sie sicher (Ensure), dass Present den angegebenen Pfad erstellt, während mit Contents die Inhalte der Datei festgelegt werden. Die Einstellung mit EnsureAbsent würde die Attributes-Eigenschaft vollständig ignorieren und jede Datei im angegebenen Pfad entfernen.

Beispiel

Im folgenden Beispiel werden ein Verzeichnis und seine Unterverzeichnisse unter Verwendung der Ressource „File“ von einem Pullserver auf einen Zielknoten kopiert. Wenn der Vorgang erfolgreich ist, schreibt die Ressource „Log“ eine Bestätigungsmeldung in das Ereignisprotokoll.

Das Quellverzeichnis ist ein auf dem Pullserver freigegebener UNC-Pfad (\\PullServer\DemoSource). Die Recurse-Eigenschaft gewährleistet, dass auch alle Unterverzeichnisse kopiert werden.

Wichtig

Der LCM auf dem Zielknoten wird standardmäßig im Kontext des lokalen Systemkontos ausgeführt. Um Zugriff auf den SourcePath zu gewähren, erteilen Sie dem Computerkonto des Zielknotens entsprechende Berechtigungen. Credential und PSDSCRunAsCredential ändern beide den Kontext, den der LCM für den Zugriff auf den SourcePath verwendet. Sie müssen weiterhin Zugriff auf das Konto gewähren, das für den Zugriff auf den SourcePath verwendet wird.

Configuration FileResourceDemo
{
    Import-DscResource -ModuleName 'PSDesiredStateConfiguration'

    Node "localhost"
    {
        File DirectoryCopy
        {
            Ensure = "Present" # Ensure the directory is Present on the target node.
            Type = "Directory" # The default is File.
            Recurse = $true # Recursively copy all subdirectories.
            SourcePath = "\\PullServer\DemoSource"
            DestinationPath = "C:\Users\Public\Documents\DSCDemo\DemoDestination"
        }

        Log AfterDirectoryCopy
        {
            # The message below gets written to the Microsoft-Windows-Desired State Configuration/Analytic log
            Message = "Finished running the file resource with ID DirectoryCopy"
            DependsOn = "[File]DirectoryCopy" # Depends on successful execution of the File resource.
        }
    }
}

Weitere Informationen zur Verwendung von Credentials in DSC finden Sie unter Verwenden von Anmeldeinformationen mit DSC-Ressourcen oder Optionen für Anmeldeinformationen in den Konfigurationsdaten.

Freigeben über