#requires -version 2.0

Function Get-CIMFile {

<#
.Synopsis
Get a file object via WMI.

.Description
This command uses WMI and the CIM_DataFile class to find a file or files on a
computer. The command by default searches drive C: on the local computer for 
the specified file. The wildcard character (*) is permitted anywhere in the
filename. You can also run this as a background job because these types of
queries can take a long time to run, especially when using wildcards.

.Parameter Name
The name of the file to find. Wildcards (*) in the name are permitted but they
will make the search run a little longer.
.Parameter Drive
The name of the drive to search. The default is C:. You do not need to include
the trailing \.
.Parameter Computername
The name of the computer to search. The default is the local computer. 
.Parameter Credential
The name of an alternate credential, or a saved credential object.
.Parameter AsJob
Run the search as a background job.
.Parameter ThrottleLimit
Specifies the maximum number of WMI operations that can be executed simultaneously. 
This parameter is valid only when the AsJob parameter is used in the command.

.Example
PS C:\> Get-Cimfile hidden.txt
.Example
PS C:\> Get-Cimfile myapp.dll -comp $computers -asjob
.Example
PS C:\> Get-Cimfile myapp.dll -comp $computers -asjob -credential MyDomain\Admin -throttle 16

.Notes
Version     : 2.0
Last Updated: 02/01/2013
Author      : Jeffery Hicks (@JeffHicks)

Read PowerShell:
Learn Windows PowerShell 3 in a Month of Lunches
Learn PowerShell Toolmaking in a Month of Lunches
PowerShell in Depth: An Administrator's Guide

  ****************************************************************
  * DO NOT USE IN A PRODUCTION ENVIRONMENT UNTIL YOU HAVE TESTED *
  * THOROUGHLY IN A LAB ENVIRONMENT. USE AT YOUR OWN RISK.  IF   *
  * YOU DO NOT UNDERSTAND WHAT THIS SCRIPT DOES OR HOW IT WORKS, *
  * DO NOT USE IT OUTSIDE OF A SECURE, TEST SETTING.             *
  ****************************************************************

.Link
Get-WmiObject

.Inputs
String

.Outputs
System.Management.ManagementObject#root\cimv2\CIM_DataFile
#>

[cmdletbinding(DefaultParameterSetName="Default")]
Param(
[Parameter(Position=0,Mandatory=$True,HelpMessage="What is the name of the file?")]
[ValidateNotNullorEmpty()]
[alias("file")]
[string]$Name,
[ValidateNotNullorEmpty()]
[string]$Drive="C:",
[ValidateNotNullorEmpty()]
[string[]]$Computername=$env:computername,
[System.Management.Automation.Credential()]$Credential = [System.Management.Automation.PSCredential]::Empty,
[Parameter(ParameterSetName="Job")]
[switch]$AsJob,
[Parameter(ParameterSetName="Job")]
[int32]$ThrottleLimit=32
)

<#
 strip off any trailing characters to drive parameter 
 that might have been passed.
#>
If ($Drive.Length -gt 2) {
    $Drive=$Drive.Substring(0,2)
}

Write-Verbose "Searching for $Name on Drive $Drive on computer $Computername."

<#
Normally you might think to simply split the name on the . character. But
you might have a filename like myfile.v2.dll so that won't work. In a case 
like this the extension would be everything after the last . and the filename
everything before.

So instead I'll use the substring method to "split" the filename string.
#>

#get the index of the last .
$index = $name.LastIndexOf(".")
#get the first part of the name
$filename=$Name.Substring(0,$index)
#get the last part of the name
$extension=$name.Substring($index+1)

#if there is * in the filename or extension, replace it with %
#and change the comparison operator for the WMI query
if ($filename -match "\*" ) { 
    Write-Verbose "Wildcard search on filename"
    $filename = $filename.Replace("*","%")
    $fileOp="LIKE"
}
else {
    $fileOp="="
}
if ($extension -match "\*") {
    Write-Verbose "Wildcard search on extension"
    $extension = $extension.Replace("*","%")
    $extOp="LIKE"
}
else {
    $extOp="="
}
$filter = "Filename $fileOp '$filename' AND extension $extOp '$extension' AND Drive='$drive'"
Write-Verbose $filter

#build the core command
$cmd="Get-WmiObject -Class CIM_Datafile -Filter ""$filter"" -ComputerName $Computername"

if ($credential) {
  write-Verbose "Adding credential for $($credential.username)"
  $cmd+=" -credential `$credential"

} #if credential

#get all instances of the file and write the WMI object to the pipeline
if ($AsJob) {
    Write-Verbose "Running query as a job"
     $cmd+=" -Asjob -ThrottleLimit $ThrottleLimit"
}
else {
    #record the start time
    $start=Get-Date    
}

Write-Verbose $cmd
Invoke-Expression -Command $cmd

#display how long this took if not running as a job
if ($start) {
    #get the end time and report how long the search took
    $end=Get-Date
    Write-Verbose "Search completed in $($end-$start)"
}

} #end Get-CIMFile