System.UriBuilder Class

public class UriBuilder

Base Types

Object
  UriBuilder

Assembly

System

Library

Networking

Summary

Provides a mutable version of the Uri class.

Description

The Uri and UriBuilder classes both represent a Uniform Resource Identifier (URI). Instances of the Uri type are immutable: once the underlying URI is specified, neither it nor its components, or constituent parts, can be changed. The UriBuilder type permits modifications to the components of the URI it represents. The System.UriBuilder.Uri property provides the current contents of a UriBuilder as a Uri instance.

[Note: For more information on URI, see IETF RFC 2396.]

See Also

System Namespace

Members

UriBuilder Constructors

UriBuilder(System.String, System.String, int, System.String, System.String) Constructor
UriBuilder() Constructor
UriBuilder(System.String) Constructor
UriBuilder(System.Uri) Constructor
UriBuilder(System.String, System.String) Constructor
UriBuilder(System.String, System.String, int) Constructor
UriBuilder(System.String, System.String, int, System.String) Constructor

UriBuilder Methods

UriBuilder.Equals Method
UriBuilder.GetHashCode Method
UriBuilder.ToString Method

UriBuilder Properties

UriBuilder.Fragment Property
UriBuilder.Host Property
UriBuilder.Password Property
UriBuilder.Path Property
UriBuilder.Port Property
UriBuilder.Query Property
UriBuilder.Scheme Property
UriBuilder.Uri Property
UriBuilder.UserName Property

Constructs and initializes a new instance of the UriBuilder class with the specified scheme, host, port number, path, and query string or fragment identifier.

Parameters

scheme

A String containing the name of an Internet access protocol.

host

A String containing a DNS host name or IP address.

port

A Int32 containing an IP port number.

path

A String containing the path for the resource.

extraValue

A String containing a query or fragment component.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	port is less than zero.
ArgumentException	extraValue is not null or System.String.Empty, and does not have as its first character a number sign ('#') indicating a fragment, or a question mark ('?') indicating a query.

Description

This constructor creates a new instance of the UriBuilder class with its properties initialized as follows:

Property	Initial value
Fragment	If extraValue begins with a "#", extraValue; otherwise System.String.Empty .
Host	host
Password	System.String.Empty
Path	path
Port	port
Query	If extraValue begins with a "?", extraValue; otherwise System.String.Empty .
Scheme	scheme
UserName	System.String.Empty

Before setting the System.UriBuilder.Path property, this constructor converts any backward slashes in path to forward slashes, and calls System.Uri.EscapeString(System.String)(path).

See Also

System.UriBuilder Class, System Namespace

Constructs and initializes a new instance of the UriBuilder class.

Description

This constructor creates a new instance of the UriBuilder class with its properties initialized as follows:

Property	Initial value
Fragment	System.String.Empty
Host	"loopback"
Password	System.String.Empty
Path	"/"
Port	80
Query	System.String.Empty
Scheme	System.Uri.UriSchemeHttp
UserName	System.String.Empty

See Also

System.UriBuilder Class, System Namespace

Constructs and initializes a new instance of the UriBuilder class using the specified URI.

Parameters

uri

A String containing a URI.

Exceptions

Exception Type	Condition
ArgumentNullException	uri is null .
UriFormatException	uri is a zero length string or contains only spaces. -or- The parsing routine detected a scheme in an invalid form. -or- The parser detected more than two consecutive slashes in a URI that does not use the "file" scheme. -or- uri is in an invalid form and cannot be parsed.

Description

This constructor checks for the presence of a scheme in uri. If no scheme is found, System.Uri.UriSchemeHttp + System.Uri.SchemeDelimiter are prepended to uri. The Uri(String) constructor is passed uri, and the components of the new Uri instance are used to initialize the properties of the UriBuilder instance being constructed.

If uri.Fragment is not equal to System.String.Empty, uri.Fragment is copied to the System.UriBuilder.Fragment property of the current instance, otherwise uri.Query is copied to the System.UriBuilder.Query property of the current instance.

The Host , Port and Scheme properties of the Uri instance are used to initialize the corresponding properties in the current instance. The AbsolutePath property of the Uri instance is used to initialize the Path property of the current instance.

The UserInfo property of the Uri instance is used to initialize the UserName and Password properties of the current instance.

See Also

System.UriBuilder Class, System Namespace

Constructs and initializes a new instance of the UriBuilder class with the specified Uri instance.

Parameters

uri

An instance of the Uri class.

Exceptions

Exception Type	Condition
NullReferenceException	uri is null .

Description

The components of the specified Uri instance are used to initialize the properties of the UriBuilder instance being constructed.

If uri.Fragment is not equal to System.String.Empty, uri.Fragment is copied to the System.UriBuilder.Fragment property of the current instance, otherwise uri.Query is copied to the System.UriBuilder.Query property of the current instance.

The Host , Port and Scheme properties of the Uri instance are used to initialize the corresponding properties in the current instance. The AbsolutePath property of the Uri instance is used to initialize the Path property of the current instance.

The UserInfo property of the Uri instance is used to initialize the UserName and Password properties of the current instance.

See Also

System.UriBuilder Class, System Namespace

Constructs and initializes a new instance of the UriBuilder class with the specified scheme and host.

Parameters

schemeName

A String containing the name of an Internet access protocol.

hostName

A String containing a DNS host name or IP address.

Description

This constructor creates a new instance of the UriBuilder class with its properties initialized as follows:

Property	Initial value
Fragment	System.String.Empty
Host	hostName
Password	System.String.Empty
Path	"/"
Port	-1
Query	System.String.Empty
Scheme	schemeName
UserName	System.String.Empty

[Note: System.UriBuilder.Port is initialized to the value -1 to indicate the default port for the scheme should be used.]

See Also

System.UriBuilder Class, System Namespace

Constructs and initializes a new instance of the UriBuilder class with the specified scheme, host, and port.

Parameters

scheme

A String containing the name of an Internet access protocol.

host

A String containing a DNS host name or IP address.

portNumber

A Int32 containing an IP port number.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	portNumber is less than zero.

Description

This constructor creates a new instance of the UriBuilder class with its properties initialized as follows:

Property	Initial value
Fragment	System.String.Empty
Host	host
Password	System.String.Empty
Path	"/"
Port	portNumber
Query	System.String.Empty
Scheme	scheme
UserName	System.String.Empty

See Also

System.UriBuilder Class, System Namespace

Constructs and initializes a new instance of the UriBuilder class with the specified scheme, host, port number, and path.

Parameters

scheme

A String containing the name of an Internet access protocol.

host

A String containing a DNS host name or IP address.

port

A Int32 containing an IP port number.

pathValue

A String containing the path for the resource.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	port is less than zero.

Description

This constructor creates a new instance of the UriBuilder class with its properties initialized as follows:

Property	Initial value
Fragment	System.String.Empty
Host	host
Password	System.String.Empty
Path	pathValue
Port	port
Query	System.String.Empty
Scheme	scheme
UserName	System.String.Empty

Before setting the System.UriBuilder.Path property, this constructor converts any backward slashes in pathValue to forward slashes, and calls System.Uri.EscapeString(System.String)(pathValue).

See Also

System.UriBuilder Class, System Namespace

rparam

The object to compare with the current instance. The string representation of this argument is used to construct a Uri for comparison.

Return Value

true if rparam represents the same URI as the current instance. If rparam is null , returns false .

Description

This method invokes System.Uri.Equals(System.Object)(rparam.ToString()) on the Uri instance returned by the System.UriBuilder.Uri property of the current instance.

[Note: This method overrides System.Object.Equals(System.Object).]

See Also

System.UriBuilder Class, System Namespace

A Int32 containing the hash code for this instance.

Description

The hash code is generated without the fragment component. For example, the URIs "http://www.contoso.com/index.htm#search" and "http://www.contoso.com/index.htm" produce the same hash code.

The algorithm used to generate the hash code is unspecified.

[Note: This method overrides System.Object.GetHashCode. ]

See Also

System.UriBuilder Class, System Namespace

A String containing the escaped URI contained in the current UriBuilder instance.

Description

The string returned by this method (shown here as uriString) is constructed as follows:

uriString = scheme + scheme delimiter + host.

If port != -1 and host != "", then uriString = uriString + ":" + port.

If host != "" and path != "" and path != "/", then uriString = uriString + "/".

uriString = uriString + path.

If fragment != "", then uriString = uriString + fragment, else uriString = uriString + query.

[Note: This method overrides System.Object.ToString.]

See Also

System.UriBuilder Class, System Namespace

A String containing the fragment component of the URI represented by the current instance.

Description

The System.UriBuilder.Fragment property contains any text following a fragment marker ('#') in the URI, including the marker itself. When setting the System.UriBuilder.Fragment property, the property value does not include the fragment marker as it is added to the property value by the set operation. Specifying null for the System.UriBuilder.Fragment property value sets the property to System.String.Empty. If null or System.String.Empty are specified in a set operation, the fragment marker is not added to the property value. The set operation does not escape the fragment value.

Setting the System.UriBuilder.Fragment property to any value, including null , sets the System.UriBuilder.Query property to System.String.Empty .

See Also

System.UriBuilder Class, System Namespace

A String containing the DNS host name or IP address of the host machine.

Description

Specifying null for a set operation sets this property to System.String.Empty .

See Also

System.UriBuilder Class, System Namespace

A String containing the password used to access the resource represented by the current instance.

Description

Specifying null for a set operation sets this property to System.String.Empty .

See Also

System.UriBuilder Class, System Namespace

A String containing the path to the resource represented by the current instance.

Description

This property returns the escaped form of the path information in the current instance. Values specified for set operations are escaped, and any backslashes are converted to forward slashes.

Specifying null or System.String.Empty for a set operation sets this property to "/" .

See Also

System.UriBuilder Class, System Namespace

A Int32 containing a non-negative port number or -1.

Exceptions

Exception Type	Condition
ArgumentOutOfRangeException	The value specified for a set operation was less than zero.

Description

If no port was specified, the System.Uri.Port property returns the default port as determined by the scheme of the current instance. A port value of -1 indicates that the current scheme does not use a port, as is the case when the scheme of the current instance is the System.Uri.UriSchemeFile scheme.

[Note: For the list of default ports used with each scheme, see System.Uri.Port .]

See Also

System.UriBuilder Class, System Namespace

A String containing the query component of the URI represented by the current instance.

Description

The System.UriBuilder.Query property contains any text following a query marker ('?') in the URI, including the marker itself. When setting the System.UriBuilder.Query property, the property value does not include the query marker as it is added to the property value by the set operation. Specifying null for the System.UriBuilder.Query property value sets the property to System.String.Empty. If null or System.String.Empty are specified in a set operation, the query marker is not added to the property value. The set operation does not escape the query value.

Setting the System.UriBuilder.Query property to any value, including null , sets the System.UriBuilder.Fragment property to System.String.Empty .

See Also

System.UriBuilder Class, System Namespace

A String containing the scheme component of the current instance.

Description

Specifying null for a set operation sets this property to System.String.Empty . If the value specified for a set operation contains a colon (":"), the scheme is set using the substring that includes all characters from the start of the value up to, but not including the colon. The characters in the value are converted to lower case.

See Also

System.UriBuilder Class, System Namespace

Gets a Uri instance constructed using the current instance.

Property Value

A Uri containing the URI components of the current instance.

Exceptions

Exception Type	Condition
UriFormatException	The URI constructed using the string representation of the current instance is in an invalid form.

Description

This property returns the same Uri instance until modifications are made to the current instance, at which time a new Uri instance is constructed by passing the string representation of the current instance to the Uri(String ) constructor.

See Also

System.UriBuilder Class, System Namespace

A String containing the user name used to access the resource identified by the current instance.

Description

Specifying null for a set operation sets this property to System.String.Empty .

See Also

System.UriBuilder Class, System Namespace