CIM_DataFile - powershell.one

CIM_DataFile represents (any) file on (any) accessible drive. This is why CIM_DataFile is an extremely useful and at the same time dangerous WMI class. When you query for CIM_DataFile without any constraints, WMI enumerates all files which can be hundreds of thousands of instances. This may take a long time or even error out due to missing resources.

The same applies when you do add constraints but use the WQL operator LIKE. For fast results, it is of utmost importance to use fixed constraints on Name or Path. The examples below illustrate this.

Examples

Let’s start with a line of code that you should never execute: it takes a very long time to complete and yields hundreds of thousands of instances, one per accessible file:

# don't run this:
Get-CimInstance -ClassName CIM_DataFile

For fast results, always make sure you specify a constraint on Name or Path. Name is the full path name of a file (including drive and filename) whereas Path is the path component only (without drive and filename).

Accessing Individual File

To access an individual file, use a constraint on Name:

# access a single file
$path = 'c:\windows\explorer.exe'
# escape backslash for wmi
$wmipath = $path.Replace('\','\\')
Get-CimInstance -Class Cim_DataFile -Filter "Name='$wmipath'"

The backslash is a special escape character in WQL which is why in paths, a literal backslash needs to be escaped. In essence, each backslash needs to be replaced by two backslashes.

Accessing Folder Content

To access the files in a folder, use a constraint on Path:

# access all files in a folder
$path = 'c:\windows'
$drive = Split-Path -Path $path -Qualifier
$folder = Split-Path -Path $path -NoQualifier
# escape backslash for wmi and make sure the folder ends with a backslash:
$wmifolder = ($folder.TrimEnd('\') + "\").Replace('\','\\')
Get-CimInstance -Class Cim_DataFile -Filter "Drive='$drive' and Path='$wmifolder'"

The property Path contains the path component only (without drive and filename). This path must start and end with a backslash.

Files And Subfolders

Since CIM_DataFile represents files only, the result are just the files in the folder. Subfolders are not listed. If you want to return both files and subfolders, use the parent class CIM_LogicalFile which represents both files and folders:

# access files and subfolders in a folder
$path = 'c:\windows'
$drive = Split-Path -Path $path -Qualifier
$folder = Split-Path -Path $path -NoQualifier
# escape backslash for wmi and make sure the folder ends with a backslash:
$wmifolder = ($folder.TrimEnd('\') + "\").Replace('\','\\')
Get-CimInstance -Class Cim_LogicalFile -Filter "Drive='$drive' and Path='$wmifolder'"

Subfolders Only

To list only subfolders and exclude files, use Win32_Directory instead:

# access files and subfolders in a folder
$path = 'c:\windows'
$drive = Split-Path -Path $path -Qualifier
$folder = Split-Path -Path $path -NoQualifier
# escape backslash for wmi and make sure the folder ends with a backslash:
$wmifolder = ($folder.TrimEnd('\') + "\").Replace('\','\\')
Get-CimInstance -Class Win32_Directory -Filter "Drive='$drive' and Path='$wmifolder'"

Careful With LIKE

WMI queries come with powerful query operators such as LIKE which (theoretically) allow you to recursively search for files. This example lists all files with extension .log anywhere in your windows folder:

# warning: this is not recommended and takes a long time to complete
Get-CimInstance -ClassName CIM_DataFile -Filter 'Drive="c:" and Path LIKE "\\windows\\%" and Extension="log"'

While this line will eventually return the requested information, it will take a very long time, and you may even run out of resources. The CPU load is high. This is because when your query does not use explicit filters on Name or Path, WMI always first retrieves all instances of CIM_DataFile. In essence, it first collects every single file on your system. Only then will it apply the filter and return the requested log files.

A query like the one above can run a couple of minutes and use 100% CPU time for one core at that time.

So you should avoid the WQL operator LIKE on the properties Name and Path. You can safely use it for any other property, but either Name or Path should always specified as a fixed constraint:

# finding all files with extension that starts with L in Windows folder:
Get-CimInstance -ClassName CIM_DataFile -Filter 'Drive="c:" and Path="\\windows\\" and Extension LIKE "l%"'

Because of this limitation, you cannot easily query multiple folders recursively in WMI.

Searching Recursively

First of all: WMI is not a perfect solution for recursive searches. Classes like CIM_DataFile are extremely useful for accessing or testing the existence of individual files, or dumping the direct content of one folder.

Once you want to search for a file across multiple folders, WMI becomes very slow. Still, if you must use WMI to find files, the first step is not to use wildcard queries and the WMI operator LIKE. As pointed out already, in order to use wildcard queries, WMI always enumerates all files on your system first which is prohibitive.

A more realistic approach is implementing the recursion yourself. This still takes much more execution time than using local commands such as Get-ChildItem, but it is faster than wildcard queries.

Here is an example of such a self-implemented recursion: Get-LogicalFile dumps the content of a folder and optionally supports a parameter -Recurse. When specified, the function calls itself whenever it hits a subfolder.

function Get-LogicalFile
{
  [CmdletBinding(DefaultParameterSetName='AutomaticSession')]
  param
  (
    # path to file
    [Parameter(Mandatory)]
    [string]
    $FilePath,

    # search recursively
    [switch]
    $Recurse,

    # return files only
    [switch]
    $File,
    
    # return directories only
    [switch]
    $Directory,
    
    # additional custom filters
    [string]
    $FilterString,
    
    # optional remoting session
    [Parameter(ParameterSetName='ReusableSession')]
    [CimSession[]]
    $CimSession,
    
    # optional computer name(s)
    [Parameter(ParameterSetName='AutomaticSession')]
    [Alias('CN','ServerName')]
    [string[]]
    $ComputerName,
    
    # maximum time for query in seconds
    [Alias('OT')]
    [uint32]
    $OperationTimeoutSec,
    
    # properties to return. When omitted, all properties are returned:
    [Alias('SelectProperties')]
    [string[]]
    $Property
  )
  
  # escape backslash
  $FilePath = $FilePath.Replace('\','\\')
  # identify our own parameters;
  $blacklist = 'filepath','recurse','file','directory','filterstring'
  # reuse parameters for WMI via splatting for recursive calling
  $parameters = $PSBoundParameters.Keys | 
  # exclude our own parameters...
  Where-Object { $blacklist -notcontains $_ } | 
  # ...and copy the remainder to a hashtable for splatting:
  ForEach-Object { $clone = @{}} { $clone[$_] = $PSBoundParameters[$_] } { $clone}
  
  # search by drive and path
  $drive = $FilePath | Split-Path -Qualifier
  $path = (($FilePath | Split-Path -NoQualifier).TrimEnd('\') + '\\')
  
  # if -File was specified, search for files:
  if (!$Directory.IsPresent)
  {
    if (![string]::IsNullOrWhiteSpace($FilterString))
    {
      $parameters["Filter"] = "Drive='$drive' and Path='$path' and $FilterString"
    }
    else
    {
      $parameters["Filter"] = "Drive='$drive' and Path='$path'"
    } 
    Get-CimInstance -ClassName CIM_DataFile @parameters
  }
  # if -Directory is specified, search for subfolders:
  if ($Directory.IsPresent -or $Recurse.IsPresent)
  {
    # do not use custom filtering for subfolders
    $parameters["Filter"] = "Drive='$drive' and Path='$path'" 
    Get-CimInstance -ClassName Win32_Directory @parameters |
    ForEach-Object {
      if (!$File.IsPresent) { $_ }
        
      # do recursion
      if ($Recurse.isPresent)
      {
        $PSBoundParameters['FilePath'] = $_.Name
        Get-LogicalFile @PSBoundParameters 
      }
    }
  }
}

To find all files with extension .log anywhere in the folder Security inside your Windows folder, run it like this:

Get-LogicalFile -FilePath "$env:windir\security" -Recurse -FilterString 'Extension="log"' -File | Select-Object -Property Name, FileSize

Recursion works great and takes only a few seconds when you traverse a few subfolders. Once you traverse large folder structures, i.e. the entire windows folder, it, too, becomes painfully slow.

The result looks similar to this:

Name                                    FileSize
----                                    --------
C:\Windows\security\database\edb.log     1048576
C:\Windows\security\database\edbtmp.log  1048576
C:\Windows\security\logs\scecomp.log         930
C:\Windows\security\logs\scesetup.log      13404

Resolving Paths

Sometimes, even though you don’t know the exact file location, you can still pinpoint the location using wildcards. For example, PowerShell comes with Resolve-Path to resolve paths like this one:

# find location of winword.exe
Resolve-Path -Path "C:\Program Files*\Microsoft Office\root\Office*\WINWORD.EXE"

This command would find winword.exe regardless of whether it is installed as a 32-bit or 64-bit application, and regardless of version, provided it is installed at all and stored in the general path scheme you resolved:

Path                                                             
----                                                             
C:\Program Files (x86)\Microsoft Office\root\Office16\WINWORD.EXE

Some Office versions do not use the subfolder root so as you see, this is not a catch-all solution, and you may have to resolve multiple potential paths. This is still faster than searching the entire folder structure recursively.

WMI can also locally and remotely resolve paths for you: Resolve-WmiPath starts at the root of a path and then examines each subfolder and replaces wildcards with the actual subfolders WMI found:

function Resolve-WmiPath
{
  [CmdletBinding(DefaultParameterSetName='AutomaticSession')]
  param
  (
    # path to resolve. May contain wildcards (*)
    [String]
    [Parameter(Mandatory,ValueFromPipeline)]
    $Path,
    
    # optional remoting session
    [Parameter(ParameterSetName='ReusableSession')]
    [CimSession[]]
    $CimSession,
    
    # optional computer name(s)
    [Parameter(ParameterSetName='AutomaticSession')]
    [Alias('CN','ServerName')]
    [string[]]
    $ComputerName
  )
  
  process
  {
    # forward parameters less private parameters
    # we are forwarding any optional remoting session or computername
    $null = $PSBoundParameters.Remove('Path')
    
    # no more wildcards? We are done:
    if ($Path -notmatch '\*') { 
      # check to see if this path exists:
      $wmiPath = $Path.Replace('\','\\').Replace('_','\_')
      $exists = @(Get-CimInstance -ClassName CIM_LogicalFile -Property Name -Filter "Name='$wmiPath'" @PSBoundParameters).Count -gt 0
      # emit it only if it exists:
      if ($exists) { return $Path }
    }
    
    # get path components:
    $drive = Split-Path -Path $Path -Qualifier
    $paths = Split-Path -Path $Path -NoQualifier
    # examine each folder in path separately:
    $folders = $paths.Trim('\') -split '\\'
  
    # construct the current path as we go
    # the loop investigates each additional subfolder and recurses:
    $parentPath = $drive
    $relativePath = '\\'
    # this is the number of characters we read into the
    # string with folders so we can add the remaining folders
    # later:
    $offset = 0
    
    # examine each folder:
    foreach($folder in $folders)
    {
      # calculate the string offset in the remainder of the folders string:
      $offset += ($folder.length + 1)
      # if the current folder has wildcards...
      if ($folder -match '\*')
      {
        # use WMI to get the actual folders at this location
        
        # use WMI wildcard: % in place of *
        $currentPath = (Join-Path $parentPath -ChildPath $folder).Replace('*','%').Replace('\','\\').Replace('_','\_')
        $remainder = $paths.Substring($offset)
        
        # add the optional remoting session or computer name infos:
        Get-CimInstance -ClassName Cim_LogicalFile -Property Name -Filter "Drive='$drive' and Path='$relativePath' and Name LIKE '$currentPath'" @PSBoundParameters | 
          # add the remainder (unexamined) folders to the identified paths:
          ForEach-Object { Join-Path -Path $_.Name -ChildPath $remainder } |
          # call the function again with the path(s) that have been resolved so far: 
          Resolve-WmiPath @PSBoundParameters
      }
      else
      {
        # folder has no wildcards, just add and continue:
        $relativePath += ($folder + '\\')
        $parentPath = Join-Path -Path $parentPath -ChildPath $folder
      }
    }
  }
}

In contrast to Resolve-Path, Resolve-WmiPath comes with built-in remoting, so it can be used to resolve paths on remote machines as well:

# testing against own machine. Replace computername with target machine name.
$computerName = $env:computerName

Resolve-WmiPath -Path "C:\Program Files*\Microsoft Office\root\Office*\WINWORD.EXE" -ComputerName $computername

The resolved paths can then be used to directly specify the files and paths you need to work with, and to speed up WMI queries this way.

Remote Access

To access remote system(s), use the parameter -ComputerName:

Get-CimInstance -ClassName CIM_DataFile -Filter 'Name="c:\\windows\\explorer.exe"' -ComputerName webserver12

Learn more about accessing remote computers.

Get-ChildItem is the equivalent of a built-in cmdlet to list files and folders. This cmdlet has no remoting capabilities. It is much faster than WMI, though, because it has considerably less overhead.

Methods

CIM_DataFile has 14 methods:

Method	Description
ChangeSecurityPermissions	Changes the security permissions for the logical file specified in the object path. Implemented by WMI.
ChangeSecurityPermissionsEx	Changes the security permissions for the logical file specified in the object path. Implemented by WMI.
Compress	Uses NTFS compression to compress the logical file (or directory) specified in the object path. Implemented by WMI.
CompressEx	Compresses the logical file (or directory) specified in the object path. Implemented by WMI.
Copy	Copies the logical file (or directory) specified in the object path to the location specified by the input parameter. Implemented by WMI.
CopyEx	Copies the logical file (or directory) specified in the object path to the location specified by the input parameter. Implemented by WMI.
Delete	Deletes the logical file (or directory) specified in the object path. Implemented by WMI.
DeleteEx	Deletes the logical file (or directory) specified in the object path. Implemented by WMI.
GetEffectivePermission	Determines whether the caller has the aggregated permissions specified by the Permission argument. Implemented by WMI.
Rename	Renames the logical file (or directory) specified in the object path. Implemented by WMI.
TakeOwnerShip	Obtains ownership of the logical file specified in the object path. Implemented by WMI.
TakeOwnerShipEx	Obtains ownership of the logical file specified in the object path. Implemented by WMI.
Uncompress	Uncompresses the logical file (or directory) specified in the object path. Implemented by WMI.
UncompressEx	Uncompresses the logical file (or directory) specified in the object path. Implemented by WMI.

Learn more about Invoke-CimMethod and how to invoke commands. Click any of the methods listed above to learn more about their purpose, parameters, and return value.

Properties

CIM_DataFile returns 32 properties:

'AccessMask','Caption','Compressed','CompressionMethod','CreationClassName',
'CreationDate','CSCreationClassName','CSName','Description','Drive','EightDotThreeFileName',
'Encrypted','EncryptionMethod','Extension','FileName','FileSize','FileType','FSCreationClassName',
'FSName','Hidden','InstallDate','InUseCount','LastAccessed','LastModified','Manufacturer',
'Name','Path','Readable','Status','System','Version','Writeable'

Unless explicitly marked as WRITEABLE, all properties are read-only.

AccessMask

UINT32

Bitmask that represents the access rights required to access or perform specific operations on the file.

Note: On FAT volumes, the FULL_ACCESS value is returned instead, which indicates no security has been set on the object.

AccessMask returns a numeric value. To translate it into a meaningful text, use any of the following approaches:

Use Update-Type

Update-Type tells PowerShell how to interpret the property. This command needs to be executed only once per PowerShell session:

Update-TypeData -MemberName AccessMask -TypeName "Microsoft.Management.Infrastructure.CimInstance#root/cimv2/cim_datafile" -MemberType ScriptProperty  -Value {
  [Flags()] Enum EnumAccessMask
  {
    READDATA_LISTDIRECTORY   = 1
    WRITEDATA_ADDFILE        = 2
    APPENDDATA_ADDSUBDIR     = 4
    READEA                   = 8
    WRITEEA                  = 16
    EXECUTE_TRAVERSE         = 32
    DELETECHILD              = 64
    READATTRIBUTES           = 128
    WRITEATTRIBUTES          = 256
    UNKNOWN512               = 512
    UNKNOWN1024              = 1024
    UNKNOWN2048              = 2048
    UNKNOWN4196              = 4096
    UNKNOWN8192              = 8192
    UNKNOWN16384             = 16384
    UNKNOWN32768             = 32768
    DELETE                   = 65536
    READCONTROL              = 131072
    WRITEDAC                 = 262144
    WRITEOWNER               = 524288
    SYNCHRONIZE              = 1048576
    UNKNOWN2097152           = 2097152
    UNKNOWN4194304           = 4194304
    UNKNOWN8388608           = 8388608
  }

  [EnumAccessMask]($this.PSBase.CimInstanceProperties['AccessMask'].Value)
} -Force

Get-CimInstance -ClassName CIM_DataFile -Filter "Name='c:\\windows\\explorer.exe'" | Select-Object -Property Name, AccessMask

Use Select-Object

Select-Object supports calculated properties. When you submit a hashtable, PowerShell dynamically calculates the result:

$AccessMask = @{
  Name = 'AccessMaskText'
  Expression = {
    [Flags()] Enum EnumAccessMask
    {
      READDATA_LISTDIRECTORY   = 1
      WRITEDATA_ADDFILE        = 2
      APPENDDATA_ADDSUBDIR     = 4
      READEA                   = 8
      WRITEEA                  = 16
      EXECUTE_TRAVERSE         = 32
      DELETECHILD              = 64
      READATTRIBUTES           = 128
      WRITEATTRIBUTES          = 256
      UNKNOWN512               = 512
      UNKNOWN1024              = 1024
      UNKNOWN2048              = 2048
      UNKNOWN4196              = 4096
      UNKNOWN8192              = 8192
      UNKNOWN16384             = 16384
      UNKNOWN32768             = 32768
      DELETE                   = 65536
      READCONTROL              = 131072
      WRITEDAC                 = 262144
      WRITEOWNER               = 524288
      SYNCHRONIZE              = 1048576
      UNKNOWN2097152           = 2097152
      UNKNOWN4194304           = 4194304
      UNKNOWN8388608           = 8388608
    }
    
    [EnumAccessMask][int]$_.AccessMask
  }  
}

Get-CimInstance -ClassName CIM_DataFile | Select-Object -Property Name, AccessMask, $AccessMask

Use a PowerShell Hashtable

You can use a PowerShell hashtable to decode numeric values. Use a hashtable like this one:

$AccessMask_map = @{
      1 = 'READDATA_LISTDIRECTORY'
      2 = 'WRITEDATA_ADDFILE'
      4 = 'APPENDDATA_ADDSUBDIR'
      8 = 'READEA'
     16 = 'WRITEEA'
     32 = 'EXECUTE_TRAVERSE'
     64 = 'DELETECHILD'
    128 = 'READATTRIBUTES'
    256 = 'WRITEATTRIBUTES'
    512 = 'UNKNOWN512'
   1024 = 'UNKNOWN1024'
   2048 = 'UNKNOWN2048'
   4096 = 'UNKNOWN4196'
   8192 = 'UNKNOWN8192'
  16384 = 'UNKNOWN16384'
  32768 = 'UNKNOWN32768'
  65536 = 'DELETE'
 131072 = 'READCONTROL'
 262144 = 'WRITEDAC'
 524288 = 'WRITEOWNER'
1048576 = 'SYNCHRONIZE'
2097152 = 'UNKNOWN2097152'
4194304 = 'UNKNOWN4194304'
8388608 = 'UNKNOWN8388608'
}

Use Enum structure

You can cast the raw property values to a new enum type to translate raw numeric values into friendly text. Use an enum like this one:

[Flags()] Enum EnumAccessMask
{
  READDATA_LISTDIRECTORY   = 1
  WRITEDATA_ADDFILE        = 2
  APPENDDATA_ADDSUBDIR     = 4
  READEA                   = 8
  WRITEEA                  = 16
  EXECUTE_TRAVERSE         = 32
  DELETECHILD              = 64
  READATTRIBUTES           = 128
  WRITEATTRIBUTES          = 256
  UNKNOWN512               = 512
  UNKNOWN1024              = 1024
  UNKNOWN2048              = 2048
  UNKNOWN4196              = 4096
  UNKNOWN8192              = 8192
  UNKNOWN16384             = 16384
  UNKNOWN32768             = 32768
  DELETE                   = 65536
  READCONTROL              = 131072
  WRITEDAC                 = 262144
  WRITEOWNER               = 524288
  SYNCHRONIZE              = 1048576
  UNKNOWN2097152           = 2097152
  UNKNOWN4194304           = 4194304
  UNKNOWN8388608           = 8388608
}

Caption

STRING MAX 64 CHAR

A short textual description of the object.

# returning class instances:
Get-CimInstance -ClassName CIM_DataFile -Filter "Drive='c:' and Path='\\windows\\system32\\'" | Select-Object -Property Name, Caption

# reading property value:
Get-CimInstance -ClassName CIM_DataFile -Filter "Drive='c:' and Path='\\windows\\system32\\'" | Select-Object -Property Name, Caption | Foreach-Object {

  $Name = $_.Name
  $value = $_.Caption
  "${Name}: Caption = $value"
}

Compressed

BOOL

If $true, the file is compressed.

# returning class instances:
Get-CimInstance -ClassName CIM_DataFile -Filter "Drive='c:' and Path='\\windows\\system32\\'" | Select-Object -Property Name, Compressed

# filtering all instances with Compressed set to $true:
Get-CimInstance -ClassName CIM_DataFile | Where-Object Compressed -eq $true | Select-Object -Property Name, Compressed

Examples

Accessing Individual File

Accessing Folder Content

Files And Subfolders

Subfolders Only

Careful With LIKE

Searching Recursively

Resolving Paths

Remote Access

Related Information

Methods

Properties

AccessMask

Caption

Compressed

CompressionMethod

CreationClassName

CreationDate

CSCreationClassName

CSName

Description

Drive

EightDotThreeFileName

Encrypted

EncryptionMethod

Extension

FileName

FileSize

FileType

FSCreationClassName

FSName

Hidden

InstallDate

InUseCount

LastAccessed

LastModified

Manufacturer

Name

Path

Readable

Status

System

Version

Writeable

CDXML Definition

Type Extensions for PowerShell

Requirements

PowerShell

Operating System

Namespace

Implementation