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] [<CommonParameters>]

AsString

New-Uri [-BaseUri] <Object> [[-Path] <string[]>] -AsString [-Query <Object>] [-Fragment <string>]
 [-MergeQueryParameters] [<CommonParameters>]

AsUriBuilder

New-Uri [-BaseUri] <Object> [[-Path] <string[]>] -AsUriBuilder [-Query <Object>]
 [-Fragment <string>] [-MergeQueryParameters] [<CommonParameters>]

ALIASES

This cmdlet has the following aliases, {{Insert list of aliases}}

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

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

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

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

-AsString

Outputs the resulting URI as a string.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: AsString
  Position: Named
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-AsUriBuilder

Outputs the resulting URI as a System.UriBuilder object.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: AsUriBuilder
  Position: Named
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-BaseUri

The base URI (string or [System.Uri]) to start from.

Type: System.Object
DefaultValue: ''
SupportsWildcards: false
Aliases:
- Uri
ParameterSets:
- Name: (All)
  Position: 0
  IsRequired: true
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Fragment

A URI fragment to append (the part after '#').

Type: System.String
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-MergeQueryParameters

If set, allows duplicate query keys instead of overriding.

Type: System.Management.Automation.SwitchParameter
DefaultValue: False
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Path

One or more path segments to append to the base URI.

Type: System.String[]
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: 1
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

-Query

Query parameters to add to the URI.

Type: System.Object
DefaultValue: ''
SupportsWildcards: false
Aliases: []
ParameterSets:
- Name: (All)
  Position: Named
  IsRequired: false
  ValueFromPipeline: false
  ValueFromPipelineByPropertyName: false
  ValueFromRemainingArguments: false
DontShow: false
AcceptedValues: []
HelpMessage: ''

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Uri

{{ Fill in the Description }}

System.UriBuilder

{{ Fill in the Description }}

string

{{ Fill in the Description }}

System.String

{{ Fill in the Description }}

NOTES

• Merging query parameters allows keeping multiple values for the same key.

RELATED LINKS