about_IOInfoExtensions.PowerShell_GetFile.help.txt
|
TOPIC
about_IOInfoExtensions.PowerShell_GetFile SHORT DESCRIPTION Returns a [FileInfo] object for the child file with the specified name. SYNTAX GetFile(string name, [bool resolve = False], [bool ignoreCase = True]) LONG DESCRIPTION Creates a new [FileInfo] object referencing a child file of the calling object. The newly created [FileInfo] object will have the given 'name' and be validated against the remaining parameters. Specifying nested files in 'name' is supported. PARAMETERS name <System.String> The name of the child file to return. Required: True Default Value: Accepts Wildcard Characters: False resolve <System.Boolean> If set to true the child file's existance will be validated. Required: False Default Value: False Accepts Wildcard Characters: False ignoreCase <System.Boolean> If set to true the search for the child file will be case in-sensitive. Required: False Default Value: True Accepts Wildcard Characters: False OUTPUTS [System.IO.FileInfo] referencing the desired child file. EXCEPTIONS System.ArgumentException If the System.Exception If the System.IO.FileNotFoundException If the EXAMPLES --------------------- Example 1 --------------------- Get an existing child file. $directory = New-Object System.IO.DirectoryInfo 'C:\Demo' Write-Host "First level children:" $directory.GetFileSystemInfos().FullName | ForEach-Object { Write-Host "`t$_" } $child = $directory.GetFile('ChildFile1.txt') Write-Host "Child FullName:`n`t$($child.FullName)" Write-Host "Child Type:`n`t$($child.GetType().FullName)" Write-Host "Child Exists:`n`t$($child.Exists)" <# Output: First level children: C:\Demo\ChildDir1 C:\Demo\ChildDir2 C:\Demo\ChildFile1.txt C:\Demo\ChildFile2.txt Child FullName: C:\Demo\ChildFile1.txt Child Type: System.IO.FileInfo Child Exists: True #> This returns a [FileInfo] object for the child file named "ChildFile1.txt". It uses default values for the 'resolve' and 'ignoreCase' parameters. --------------------- Example 2 --------------------- Get a non-existing nested child file. $directory = New-Object System.IO.DirectoryInfo 'C:\Demo' Write-Host "Children:" $directory.GetFileSystemInfos("*", [System.IO.SearchOption]::AllDirectories).FullName | ForEach-Object { Write-Host "`t$_" } $child = $directory.GetFile('ChildDir3\ChildFile3.txt') Write-Host "Child FullName:`n`t$($child.FullName)" Write-Host "Child Type:`n`t$($child.GetType().FullName)" Write-Host "Child Exists:`n`t$($child.Exists)" <# Output: Children: C:\Demo\ChildDir1 C:\Demo\ChildDir2 C:\Demo\ChildFile1.txt C:\Demo\ChildFile2.txt C:\Demo\ChildDir2\ChildFile1.txt C:\Demo\ChildDir2\ChildFile2.txt Child FullName: C:\Demo\ChildDir3\ChildFile3.txt Child Type: System.IO.FileInfo Child Exists: False #> This returns a [FileInfo] object for the nested child file named "ChildDir3\ChildFile3.txt". It uses default values for the 'resolve' and 'ignoreCase' parameters. --------------------- Example 3 --------------------- Resolve a child file using case sensitivity. $directory = New-Object System.IO.DirectoryInfo 'C:\Demo' Write-Host "First level children:" $directory.GetFileSystemInfos().FullName | ForEach-Object { Write-Host "`t$_" } try { $null = $directory.GetFile('childfile1.txt', $true, $false) } catch { $stringArgs = @( $_.Exception.GetType().ToString(), $_.Exception.Message, $_.Exception.StackTrace.Substring(0, $_.Exception.StackTrace.IndexOf([Environment]::NewLine)) ) Write-Host ("`nError: {0}: {1}`n{2}`n" -f $stringArgs) $error.Clear() } <# Output: First level children: C:\Demo\ChildDir1 C:\Demo\ChildDir2 C:\Demo\ChildFile1.txt C:\Demo\ChildFile2.txt Error: System.IO.FileNotFoundException: A child named 'childfile1.txt' already exists but with a different case: ChildFile1.txt. at IOInfoExtensions.DirectoryInfoExtensions.GetFile(DirectoryInfo directory, String name, Boolean resolve, Boolean ignoreCase) #> Throws an exception because the existance and case sensitivity validations failed. KEYWORDS IOInfoExtensions, IOInfoExtensions.PowerShell, System.IO.DirectoryInfo, DirectoryInfo, GetFile SEE ALSO about_IOInfoExtensions.PowerShell about_IOInfoExtensions.PowerShell_GetDirectory about_IOInfoExtensions.PowerShell_GetFile about_IOInfoExtensions.PowerShell_DeleteContent about_IOInfoExtensions.PowerShell_CopyContentTo about_IOInfoExtensions.PowerShell_MoveFrom about_IOInfoExtensions.PowerShell_CopyFrom about_IOInfoExtensions.PowerShell_TryDelete |