# Get-VaultFile

Retrieves a File from Vault.\
It can also be used to download a file to a local directory.

## Syntax

```powershell
Get-VaultFile [-File <String>] [-FileId <Long>] [-Properties <Hashtable>] [-DownloadPath <String>] [<CommonParameters>]
```

## Parameters

| Type      | Name         | Description                                                                    | Optional |
|-----------|--------------|--------------------------------------------------------------------------------|----------|
| String    | File         | Absolute Vault path to a file                                                  | yes      |
| Long      | FileId       | Id or MasterId of the file                                                     | yes      |
| Hashtable | Properties   | Search for the file with matching properties                                   | yes      |
| String    | DownloadPath | This is the location where the file and all it's references will be downloaded | yes      |

## Return type

[File](</code_reference/objects/file>) ← on success\
**empty** ← on failure. When `-DownloadPath` is used the Exception/ErrorMessage can be accessed using [\$Error](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#error>).  

## Remarks

If the search criteria's passed to the **-Properties** argument matches more than one file, then *only the first* file is returned.\
In case you want to get multiple files use the [Get-VaultFiles](< get-vaultfiles>) Cmdlet.

In order to search a file by properties the **-Properties** argument allows to search the values of user defined properties and system properties which can be passed using their:
- *display names* (e.g. `@{'Title' = ...}` can be used with English Vault or `@{'Titel' = ...}` can be used with german Vault environments).


The **-DownloadPath** parameter allows downloading the file along with all it's references into the specified directory.\
One of its main purposes is to make sure that files, such as Inventor assemblies, can be opened without issues from that location. To support this, the original Vault folder structure is preserved.\
Because of this, the downloaded file may not be placed directly in the target directory. It might be stored in a subfolder instead.\
To retrieve the actual location, use the additional `LocalPath` property.

:::{note}
For more advanced download options, use the [Save-VaultFile](</code_reference/commandlets/save-vaultfile>) cmdlet.

**Important:** All files downloaded with this cmdlet are marked as *read-only* in Windows because they are not checked out from Vault. This means you cannot modify or delete them directly!\
To delete these files anyway, run `Remove-Item $file.LocalPath -Force` in PowerShell to bypass the read-only protection.
:::

## Examples

**Get File via absolute Vault path**

```powershell
$file = Get-VaultFile -File '$/PowerVaultTestFiles/pV_6.idw'
```

**Get File that matches certain search criteria's**

```powershell
$file = Get-VaultFile -Properties @{"Description" = "TEMPLATE"; "Part Number" = "Dial"}
```

### Downloading the file

```powershell
$file = Get-VaultFile -File '$/Assemblies/Catch Assembly.iam' -DownloadPath "C:\Temp\Test\Download" # Note: if this directory doesn't exist, it will be created
$actualDownloadLocation = $file.LocalPath
```



**Error handling: Check if an error appeared by using [\$?](<https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_automatic_variables?view=powershell-5.1#section-1>) and analyze why file could not be downloaded using \$Error**

```powershell

$file = Get-VaultFile -File '$/Restriced/Reatiner.idw' -DownloadPath "C:\Temp\Test\Download"

if([string]::IsNullOrEmpty($file.LocalPath)){
   if($? -eq $false){
     $Error[0].Exception #Returns: "You don't have permission to download the file. Please check the file's permissions in the Details dialog under the Security tab."
   }
}
```