Resolve-DbaPath

Synopsis

Validates and resolves file system paths with enhanced error handling and provider verification.

Description

Validates and resolves file system paths with additional safety checks beyond PowerShell’s built-in Resolve-Path cmdlet. This function ensures paths exist and are accessible before performing database operations like backups, restores, or log file management. It provides enhanced error handling, provider validation (FileSystem, Registry, etc.), and supports both existing paths and parent directories for new file creation. DBAs can use this to validate backup destinations, database file locations, and script paths before running maintenance operations, preventing failures due to invalid or inaccessible paths.

Syntax

Resolve-DbaPath
    [-Path] <String[]>
    [[-Provider] <String>]
    [-SingleItem]
    [-NewChild]
    [<CommonParameters>]

Examples

Example: 1

PS C:\> Resolve-DbaPath -Path report.log -Provider FileSystem -NewChild -SingleItem

Ensures the resolved path is a FileSystem path.
This will resolve to the current folder and the file report.log.
Will not ensure the file exists or doesn’t exist.
If the current path is in a different provider, it will throw an exception.

Example: 2

PS C:\> Resolve-DbaPath -Path ..\*

This will resolve all items in the parent folder, whatever the current path or drive might be.

Required Parameters

-Path

Specifies the file system path to validate and resolve, supporting both absolute and relative paths.
Use this to verify backup destinations, database file locations, or script paths before database operations.
Accepts wildcards for pattern matching and can validate multiple paths when passed as an array.

Optional Parameters

-Provider

Validates that the resolved path belongs to the specified PowerShell provider type.
Use ‘FileSystem’ to ensure database backup paths or data file locations are on disk storage, not registry or other providers.
Prevents accidental operations on wrong provider types like ‘Registry’, ‘Certificate’, or ‘ActiveDirectory’.

-SingleItem

Requires the path to resolve to exactly one location, preventing wildcard expansion.
Use when specifying a unique backup file destination or single database file path where multiple matches would cause errors.
Will throw an error if wildcards or patterns resolve to multiple paths.

-NewChild

Validates the parent directory exists for creating new files, without requiring the target file to exist.
Use when specifying backup file destinations, new database file paths, or log file locations that will be created.
The parent folder must be accessible, but the final filename can be new.

Outputs

System.String

Returns one or more resolved file system paths as strings. Each input path that resolves successfully is output as a separate string value. When processing multiple paths via pipeline or array, each path is returned individually to the pipeline, enabling pipeline chaining with other commands like Copy-Item or Remove-Item. The returned paths are fully qualified file system paths in the format expected by PowerShell cmdlets and .NET APIs. When using -NewChild, returns the constructed path for the new file even if it does not yet exist, but the parent directory must be accessible.