Table of contents
TOC
Collapse the table of content
Expand the table of content

DSC File Resource

Eric Slesar|Last Updated: 7/12/2016
|
1 Contributor

Applies To: Windows PowerShell 4.0, Windows PowerShell 5.0

The File resource in Windows PowerShell Desired State Configuration (DSC) provides a mechanism to manage files and folders on the target node.

Note: If the MatchSource property is set to $false (which is the default value), the contents to be copied are cached the first time the configuration is applied. Subsequent applications of the configuration will not check for updated files and/or folders in the path specified by SourcePath. If you want to check for updates to the files and/or folders in SourcePath every time the configuration is applied, set MatchSource to $true.

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] ]
    [ Ensure = [string] { Absent | Present } ] 
    [ Force = [bool] ]
    [ Recurse = [bool] ]
    [ DependsOn = [string[]] ]
    [ SourcePath = [string] ]
    [ Type = [string] { Directory | File } ] 
    [ MatchSource = [bool] ]
}

Properties

PropertyDescription
DestinationPathIndicates the location where you want to ensure the state for a file or directory.
AttributesSpecifies the desired state of the attributes for the targeted file or directory.
ChecksumIndicates the checksum type to use when determining whether two files are the same. If Checksum is not specified, only the file or directory name is used for comparison. Valid values include: SHA-1, SHA-256, SHA-512, createdDate, modifiedDate.
ContentsSpecifies the contents of a file, such as a particular string.
CredentialIndicates the credentials that are required to access resources, such as source files, if such access is required.
EnsureIndicates if the file or directory exists. Set this property to "Absent" to ensure that the file or directory does not exist. Set it to "Present" to ensure that the file or directory does exist. The default is "Present".
ForceCertain file operations (such as overwriting a file or deleting a directory that is not empty) will result in an error. Using the Force property overrides such errors. The default value is $false.
RecurseIndicates if subdirectories are included. Set this property to $true to indicate that you want subdirectories to be included. The default is $false. Note: This property is only valid when the Type property is set to Directory.
DependsOnIndicates that the configuration of another resource must run before this resource is configured. For example, if the ID of the resource configuration script block that you want to run first is ResourceName and its type is ResourceType, the syntax for using this property is DependsOn = "[ResourceType]ResourceName".
SourcePathIndicates the path from which to copy the file or folder resource.
TypeIndicates if the resource being configured is a directory or a file. Set this property to "Directory" to indicate that the resource is a directory. Set it to "File" to indicate that the resource is a file. The default value is “File”.
MatchSourceIf set to the default value of $false, then any files on the source (say, files A, B, and C) will be added to the destination the first time the configuration is applied. If a new file (D) is added to the source, it will not be added to the destination, even when the configuration is re-applied later. If the value is $true, then each time the configuration is applied, new files subsequently found on the source (such as file D in this example) are added to the destination. The default value is $false.

Example

The following example shows how to use the File resource to ensure that a directory with the path C:\Users\Public\Documents\DSCDemo\DemoSource on a source computer (such as the “pull” server) is also present (along with all subdirectories) on the target node. It also writes a confirmatory message to the log when complete and includes a statement to ensure that the file-checking operation runs prior to the logging operation.

Configuration FileResourceDemo
{
    Node "localhost"
    {
        File DirectoryCopy
        {
            Ensure = "Present"  # You can also set Ensure to "Absent"
            Type = "Directory" # Default is "File".
            Recurse = $true # Ensure presence of subdirectories, too
            SourcePath = "C:\Users\Public\Documents\DSCDemo\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" # This means run "DirectoryCopy" first.
        }
    }
}
© 2016 Microsoft