New-Uri¶
SYNOPSIS¶
Constructs a URI from base, paths, query parameters, and fragment.
SYNTAX¶
AsUri (Default)¶
New-Uri [-BaseUri] <Object> [[-Path] <String[]>] [-Query <Object>] [-Fragment <String>] [-MergeQueryParameters]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
AsString¶
New-Uri [-BaseUri] <Object> [[-Path] <String[]>] [-Query <Object>] [-Fragment <String>] [-MergeQueryParameters]
[-AsString] [-ProgressAction <ActionPreference>] [<CommonParameters>]
AsUriBuilder¶
New-Uri [-BaseUri] <Object> [[-Path] <String[]>] [-Query <Object>] [-Fragment <String>] [-MergeQueryParameters]
[-AsUriBuilder] [-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION¶
Builds a URI string or object by combining a base URI with additional path segments,
query parameters, and an optional fragment.
Ensures proper encoding (per RFC3986)
and correct placement of '/' in paths, handles query parameter merging, and appends
fragment identifiers.
By default, returns a [System.Uri] object.
EXAMPLES¶
EXAMPLE 1¶
# Simple usage with base and path
New-Uri -BaseUri 'https://example.com' -Path 'products/item'
Output:
AbsolutePath : /products/item
AbsoluteUri : https://example.com/products/item
LocalPath : /products/item
Authority : example.com
HostNameType : Dns
IsDefaultPort : True
IsFile : False
IsLoopback : False
PathAndQuery : /products/item
Segments : {/, products/, item}
IsUnc : False
Host : example.com
Port : 443
Query :
Fragment :
Scheme : https
OriginalString : https://example.com:443/products/item
DnsSafeHost : example.com
IdnHost : example.com
IsAbsoluteUri : True
UserEscaped : False
UserInfo :
Constructs a URI with the given base and path.
EXAMPLE 2¶
# Adding query parameters via hashtable
New-Uri 'https://example.com/api' -Path 'search' -Query @{ q = 'test search'; page = @(2, 4) } -AsUriBuilder
Output:
Scheme : https
UserName :
Password :
Host : example.com
Port : 443
Path : /api/search
Query : ?q=test%20search&page=2&page=4
Fragment :
Uri : https://example.com/api/search?q=test search&page=2&page=4
Adds query parameters to the URI, automatically encoding values.
EXAMPLE 3¶
# Merging with existing query and using -MergeQueryParameter
New-Uri 'https://example.com/data?year=2023' -Query @{ year = 2024; sort = 'asc' } -MergeQueryParameters -AsString
Output:
https://example.com/data?sort=asc&year=2023&year=2024
Merges new query parameters with the existing ones instead of replacing them.
PARAMETERS¶
-BaseUri¶
The base URI (string or [System.Uri]) to start from.
Type: Object
Parameter Sets: (All)
Aliases: Uri
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Path¶
One or more path segments to append to the base URI.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Query¶
Query parameters to add to the URI.
Type: Object
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Fragment¶
A URI fragment to append (the part after '#').
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-MergeQueryParameters¶
If set, allows duplicate query keys instead of overriding.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-AsString¶
Outputs the resulting URI as a string.
Type: SwitchParameter
Parameter Sets: AsString
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-AsUriBuilder¶
Outputs the resulting URI as a System.UriBuilder object.
Type: SwitchParameter
Parameter Sets: AsUriBuilder
Aliases:
Required: True
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction¶
{{ Fill ProgressAction Description }}
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters¶
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
INPUTS¶
OUTPUTS¶
System.Uri¶
System.UriBuilder¶
string¶
NOTES¶
- Merging query parameters allows keeping multiple values for the same key.