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() 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(System.String, System.String, int, System.String, 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


UriBuilder() Constructor

public UriBuilder();

Summary

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:

PropertyInitial value
FragmentSystem.String.Empty
Host"loopback"
PasswordSystem.String.Empty
Path"/"
Port80
QuerySystem.String.Empty
SchemeSystem.Uri.UriSchemeHttp
UserNameSystem.String.Empty

See Also

System.UriBuilder Class, System Namespace

UriBuilder(System.String) Constructor

public UriBuilder(string uri);

Summary

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

Parameters

uri
A String containing a URI.

Exceptions

Exception TypeCondition
ArgumentNullExceptionuri is null .

UriFormatExceptionuri 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

UriBuilder(System.Uri) Constructor

public UriBuilder(Uri uri);

Summary

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 TypeCondition
NullReferenceExceptionuri 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

UriBuilder(System.String, System.String) Constructor

public UriBuilder(string schemeName, string hostName);

Summary

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:

PropertyInitial value
FragmentSystem.String.Empty
HosthostName
PasswordSystem.String.Empty
Path"/"
Port-1
QuerySystem.String.Empty
SchemeschemeName
UserNameSystem.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

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

public UriBuilder(string scheme, string host, int portNumber);

Summary

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 TypeCondition
ArgumentOutOfRangeExceptionportNumber is less than zero.

Description

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

PropertyInitial value
FragmentSystem.String.Empty
Hosthost
PasswordSystem.String.Empty
Path"/"
PortportNumber
QuerySystem.String.Empty
Schemescheme
UserNameSystem.String.Empty

See Also

System.UriBuilder Class, System Namespace

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

public UriBuilder(string scheme, string host, int port, string pathValue);

Summary

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 TypeCondition
ArgumentOutOfRangeExceptionport is less than zero.

Description

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

PropertyInitial value
FragmentSystem.String.Empty
Hosthost
PasswordSystem.String.Empty
PathpathValue
Portport
QuerySystem.String.Empty
Schemescheme
UserNameSystem.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

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

public UriBuilder(string scheme, string host, int port, string path, string extraValue);

Summary

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 TypeCondition
ArgumentOutOfRangeExceptionport is less than zero.
ArgumentExceptionextraValue 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:

PropertyInitial value
FragmentIf extraValue begins with a "#", extraValue; otherwise System.String.Empty .
Hosthost
PasswordSystem.String.Empty
Pathpath
Portport
QueryIf extraValue begins with a "?", extraValue; otherwise System.String.Empty .
Schemescheme
UserNameSystem.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

UriBuilder.Equals Method

public override bool Equals(object rparam);

Summary

Compares the current instance and the specified object for equality.

Parameters

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

UriBuilder.GetHashCode Method

public override int GetHashCode();

Summary

Generates a hash code for the current instance.

Return Value

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

UriBuilder.ToString Method

public override string ToString();

Summary

Returns the escaped form of the URI represented by the current instance.

Return Value

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

UriBuilder.Fragment Property

public string Fragment { get; set; }

Summary

Gets or sets the fragment component of the current instance.

Property Value

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

UriBuilder.Host Property

public string Host { get; set; }

Summary

Gets or sets the Domain Name System (DNS) host name or IP address of a machine that provides access to the resource identified by the current instance.

Property Value

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

UriBuilder.Password Property

public string Password { get; set; }

Summary

Gets or sets the password information used to access the resource represented by the current instance.

Property Value

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

UriBuilder.Path Property

public string Path { get; set; }

Summary

Gets or sets the path to the resource represented by the current instance.

Property Value

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

UriBuilder.Port Property

public int Port { get; set; }

Summary

Gets or sets the port number used to connect to the System.UriBuilder.Host referenced by the current instance.

Property Value

A Int32 containing a non-negative port number .

Exceptions

Exception TypeCondition
ArgumentOutOfRangeExceptionThe 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

UriBuilder.Query Property

public string Query { get; set; }

Summary

Gets or sets the query component of the current instance.

Property Value

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

UriBuilder.Scheme Property

public string Scheme { get; set; }

Summary

Gets or sets the scheme component of the current instance.

Property Value

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

UriBuilder.Uri Property

public Uri Uri { get; }

Summary

Gets a Uri instance constructed using the current instance.

Property Value

A Uri containing the URI components of the current instance.

Exceptions

Exception TypeCondition
UriFormatExceptionThe 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

UriBuilder.UserName Property

public string UserName { get; set; }

Summary

Gets or sets the user name information used to access the resource identified by the current instance.

Property Value

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