Type: System.UriBuilder

System.UriBuilder Class

Assembly: System.dll
Namespace: System

Summary: Provides a custom constructor for uniform resource indentifiers (URIs) and modifies URIs for the Uri class.

C# Syntax:


        public class UriBuilder

Remarks

The UriBuilder class provides a convenient way to modify the contents of a Uri instance without creating a new Uri instance for each modification.

The UriBuilder properties provide read/write access to the read-only Uri properties so that they can be modified.

See also:

System Namespace | Uri

System.UriBuilder Member List:

Public Constructors

ctor #1	Overloaded: `.ctor()`Default constructor. This constructor is called by derived class constructors to initialize state in this type. Initializes a new instance of the UriBuilder class.
ctor #2	Overloaded: `.ctor(string uri)` Initializes a new instance of the UriBuilder class with the specified URI.
ctor #3	Overloaded: `.ctor(Uri uri)` Initializes a new instance of the UriBuilder class with the specified Uri instance.
ctor #4	Overloaded: `.ctor(string schemeName, string hostName)` Initializes a new instance of the UriBuilder class with the specified scheme and host.
ctor #5	Overloaded: `.ctor(string scheme, string host, int portNumber)` Initializes a new instance of the UriBuilder class with the specified scheme, host, and port.
ctor #6	Overloaded: `.ctor(string scheme, string host, int port, string pathValue)` Initializes a new instance of the UriBuilder class with the specified scheme, host, port number, and path.
ctor #7	Overloaded: `.ctor(string scheme, string host, int port, string path, string extraValue)` Initializes a new instance of the UriBuilder class with the specified scheme, host, port number, path and query string or fragment identifier.

Public Properties

Fragment	Read-write Gets or sets the fragment portion of the URI.
Host	Read-write Gets or sets the Domain Name System (DNS) host name or IP address of a server.
Password	Read-write Gets or sets the password associated with the user accessing the URI.
Path	Read-write Gets or sets the path to the resource referenced by the URI.
Port	Read-write Gets or sets the port number of the URI.
Query	Read-write Gets or sets any query information included in the URI.
Scheme	Read-write Gets or sets the scheme name of the URI.
Uri	Read-only Gets the Uri instance constructed by the specified UriBuilder instance.
UserName	Read-write The user name associated with the user accessing the URI.

Public Methods

Equals	Overridden: Compares an existing Uri instance with the contents of the UriBuilder for equality.
GetHashCode	Overridden: Returns the hash code for the URI.
GetType (inherited from System.Object)	See base class member description: System.Object.GetType Derived from System.Object, the primary base class for all objects.
ToString	Overridden: Returns the display string for the specified UriBuilder instance.

Protected Methods

Finalize (inherited from System.Object)	See base class member description: System.Object.Finalize Derived from System.Object, the primary base class for all objects.
MemberwiseClone (inherited from System.Object)	See base class member description: System.Object.MemberwiseClone Derived from System.Object, the primary base class for all objects.

Hierarchy:

System.Object

System.UriBuilder

System.UriBuilder Member Details

Overloaded ctor #1

Summary: Initializes a new instance of the UriBuilder class.

Default constructor. This constructor is called by derived class constructors to initialize state in this type.

C# Syntax:


            public UriBuilder();

Remarks

The default constructor creates a new instance of the UriBuilder class with all properties empty.

Return to top

Overloaded ctor #2

Summary: Initializes a new instance of the UriBuilder class with the specified URI.

C# Syntax:


            public UriBuilder(
   string uri
);

Parameters:

uri

A URI string.

Exceptions

Exception Type	Condition
UriFormatException	uri is not a valid URI.

Remarks

This constructor initializes a new instance of the UriBuilder class with the UriBuilder.Fragment, UriBuilder.Host, UriBuilder.Path, UriBuilder.Port, UriBuilder.Query, UriBuilder.Scheme, and UriBuilder.Uri properties set as specified in uri.

Return to top

Overloaded ctor #3

Summary: Initializes a new instance of the UriBuilder class with the specified Uri instance.

C# Syntax:


            public UriBuilder(
   Uri uri
);

Parameters:

uri

An instance of the Uri class.

Remarks

Return to top

Overloaded ctor #4

Summary: Initializes a new instance of the UriBuilder class with the specified scheme and host.

C# Syntax:


            public UriBuilder(
   string schemeName,
   string hostName
);

Parameters:

schemeName

An Internet access protocol.

hostName

A DNS-style domain name or IP address.

Remarks

The UriBuilder instance is initialized with the UriBuilder.Scheme property set to schemeName and the UriBuilder.Host property set to hostName. UriBuilder.Port is initialized to the value -1 to indicate the default port for the scheme should be used, and the UriBuilder.Path property is set to the slash character (/).

Example

The following example creates a UriBuilder instance containing the URI http://www.contoso.com/.

UriBuilder myUri = new UriBuilder("http","www.contoso.com");

Return to top

Overloaded ctor #5

Summary: Initializes a new instance of the UriBuilder class with the specified scheme, host, and port.

C# Syntax:


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

Parameters:

scheme

An Internet access protocol.

host

A DNS-style domain name or IP address.

portNumber

An IP port number for the service.

Remarks

The UriBuilder instance is initialized with the UriBuilder.Scheme property set to schemeName, the UriBuilder.Host property set to hostName, and the UriBuilder.Port property set to portNumber. The UriBuilder.Path property is set to the slash character (/).

Example

The following example creates a UriBuilder instance containing the URI http://www.contoso.com:8080/ .

UriBuilder myUri = new UriBuilder("http","www.contoso.com",8080);

Return to top

Overloaded ctor #6

Summary: Initializes a new instance of the UriBuilder class with the specified scheme, host, port number, and path.

C# Syntax:


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

Parameters:

scheme

An Internet access protocol.

host

A DNS-style domain name or IP address.

port

An IP port number for the service.

pathValue

The path to the Internet resource.

Remarks

Example

The following example creates a UriBuilder instance containing the URI http://www.contoso.com:8080/index.htm .

UriBuilder myUri = new UriBuilder("http","www.contoso.com",8080,"index.htm");

Return to top

Overloaded ctor #7

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

C# Syntax:


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

Parameters:

scheme

An Internet access protocol.

host

A DNS-style domain name or IP address.

port

An IP port number for the service.

path

The path to the Internet resource.

extraValue

A query string or fragment identifier.

Exceptions

Exception Type	Condition
ArgumentException	extraValue is neither a valid fragment indentifier containing a number sign (#) nor a valid query string containing a question mark (?).

Remarks

The UriBuilder instance is initialized with the UriBuilder.Scheme property set to schemeName, the UriBuilder.Host property set to hostName, the UriBuilder.Port property set to portNumber, and the UriBuilder.Path property is set to pathValue. If extraValue contains a number sign (#), then UriBuilder.Fragment is set to extraValue. If extraValue contains a question mark (?), then UriBuilder.Query is set to extraValue.

Example

The following example creates a UriBuilder instance containing the URI http://www.contoso.com:8080/index.htm#top.

UriBuilder myUri = new UriBuilder("http","www.contoso.com",8080,"index.htm","#top");

Return to top

Property: Fragment (read-write)

Summary: Gets or sets the fragment portion of the URI.

C# Syntax:


            public string Fragment {get; set;}

Remarks

The UriBuilder.Fragment property contains any text following a fragment marker (#) in the URI, including the marker itself. When setting the UriBuilder.Fragment property, the fragment marker is added to its value. Setting the UriBuilder.Fragment property to any value, including null, clears the UriBuilder.Query property. Setting the UriBuilder.Fragment property to null or to String.Empty clears the property.

Example

The following example creates the URI "http://www.contoso.com/index.htm#main".

UriBuilder uBuild = new UriBuilder("http://www.contoso.com/");
uBuild.Path = "index.htm";
uBuild.Fragment = "main";

Uri myUri = uBuild.Uri;

Return to top

Property: Host (read-write)

Summary: Gets or sets the Domain Name System (DNS) host name or IP address of a server.

C# Syntax:


            public string Host {get; set;}

Remarks

The UriBuilder.Host property contains the fully qualified DNS host name or IP address (in dotted-quad notation) of the server.

Return to top

Property: Password (read-write)

Summary: Gets or sets the password associated with the user accessing the URI.

C# Syntax:


            public string Password {get; set;}

Return to top

Property: Path (read-write)

Summary: Gets or sets the path to the resource referenced by the URI.

C# Syntax:


            public string Path {get; set;}

Remarks

The UriBuilder.Path property contains the path information that the server uses to resolve requests for information. Typically this is the path to the desired information on the server's file system, although it also can indicate the application or script that the server must run to provide the information.

The path information does not include the scheme, host name, or query portion of the URI. The UriBuilder.Path property always returns at least a slash (/).

Return to top

Property: Port (read-write)

Summary: Gets or sets the port number of the URI.

C# Syntax:


            public int Port {get; set;}

Remarks

The port number defines the protocol port for contacting the server referenced in the URI. If a port is not specified as part of the URI, the Uri.Port property returns the value -1 to indicate that the server uses the default value for the protocol.

Return to top

Property: Query (read-write)

Summary: Gets or sets any query information included in the URI.

C# Syntax:


            public string Query {get; set;}

Remarks

The Uri.Query property contains any query information included in the URI. Query information is separated from the path information by a question mark (?) and continues to the end of the URI. The query information returned includes the leading question mark.

The query information is escaped according to RFC 2396.

Setting the UriBuilder.Query property to any value, including null, clears the UriBuilder.Fragment property. Setting the UriBuilder.Query property to null or to String.Empty clears the property.

Example

The following example writes the query ?date= today to the console.

Uri baseUri = new Uri("http://www.contoso.com/");
 Uri myUri = new Uri(baseUri, "catalog/shownew.htm?date=today");
 
 Console.WriteLine(myUri.Query);
   
	. . . 
Uri baseUri = new Uri("http://www.contoso.com/");
 Uri myUri = new Uri(baseUri, "catalog/shownew.htm?date=today");
 
 Console.WriteLine(myUri.Query);

Return to top

Property: Scheme (read-write)

Summary: Gets or sets the scheme name of the URI.

C# Syntax:


            public string Scheme {get; set;}

Remarks

The following table lists the valid scheme names for the Uri.Scheme property.

Scheme	Description
file	The resource is a file on the local computer.
ftp	The resource is accessed through FTP.
gopher	The resource is accessed through the Gopher protocol.
http	The resource is accessed through HTTP.
https	The resource is accessed through secure HTTP.
mailto	The resource is an e-mail address and is accessed through SMTP.
news	The resources is accessed through NNTP.

Return to top

Property: Uri (read-only)

Summary: Gets the Uri instance constructed by the specified UriBuilder instance.

C# Syntax:


            public Uri Uri {get;}

Exceptions

Exception Type	Condition
UriFormatException	The URI constructed by the UriBuilder properties is invalid.

Remarks

The UriBuilder.Uri property contains the Uri created by the UriBuilder. Any changes made to the UriBuilder properties are reflected in the UriBuilder.Uri property.

Return to top

Property: UserName (read-write)

Summary: The user name associated with the user accessing the URI.

C# Syntax:


            public string UserName {get; set;}

Return to top

Overridden Method: Equals(
object rparam
)

Summary: Compares an existing Uri instance with the contents of the UriBuilder for equality.

C# Syntax:


            public override bool Equals(
   object rparam
);

Parameters:

rparam

The Uri instance to compare with the current instance.

Return Value:: true if the specified Uri is equal to the Uri constructed by this UriBuilder instance; otherwise, false.

Remarks

The UriBuilder.Equals method compares a specified Uri instance with the Uri instance built by the UriBuilder instance. If the two are the same, the UriBuilder.Equals method returns true.

Return to top

Method: Finalize()

Inherited
See base class member description: System.Object.Finalize

C# Syntax:


            ~UriBuilder();

For more information on members inherited from System.Object click on the link above.

Return to top

Overridden Method: GetHashCode()

Summary: Returns the hash code for the URI.

C# Syntax:


            public override int GetHashCode();

Return Value:: The hash code generated for the URI.

Remarks

The hash code is generated without including any fragment included. The URIs http://www.contoso.com/index.htm#search and http://www.contoso.com/index.htm generate the same hash code.

The hash codes for Uri A and B are guaranteed to be the same when A.Equals(B) is true.

This method implements Object.GetHashCode.

Return to top

Method: GetType()

Inherited
See base class member description: System.Object.GetType

C# Syntax:


            public Type GetType();

For more information on members inherited from System.Object click on the link above.

Return to top

Method: MemberwiseClone()

Inherited
See base class member description: System.Object.MemberwiseClone

C# Syntax:


            protected object MemberwiseClone();

For more information on members inherited from System.Object click on the link above.

Return to top

Overridden Method: ToString()

Summary: Returns the display string for the specified UriBuilder instance.

C# Syntax:


            public override string ToString();

Return Value:: The string containing the unescaped display name of the UriBuilder.