diff --git a/xml/System/Uri.xml b/xml/System/Uri.xml index 4c197337191..63aeb0e702e 100644 --- a/xml/System/Uri.xml +++ b/xml/System/Uri.xml @@ -187,24 +187,28 @@ The following code snippet shows example values of the various properties on the - A string that identifies the resource to be represented by the instance. Note that an IPv6 address in string form must be enclosed within brackets. For example, "http://[2607:f8b0:400d:c06::69]". + A string that identifies the resource to be represented by the instance. Initializes a new instance of the class with the specified URI. instance from a URI string. It parses the URI, puts it in canonical format, and makes any required escape encodings. - This constructor does not ensure that the refers to an accessible resource. +This constructor creates a instance from a URI string. It parses the URI, puts it in canonical format, and makes any required escape encodings. - This constructor assumes that the `string` parameter references an absolute URI and is equivalent to calling the constructor with set to . If the `string` parameter passed to the constructor is a relative URI, this constructor will throw a . +This constructor does not ensure that the refers to an accessible resource. + +If the `uriString` represents an IPv6 address, it must be enclosed within brackets, for example, "http://[2607:f8b0:400d:c06::69]". + +This constructor assumes that the `string` parameter references an absolute URI and is equivalent to calling the constructor with set to . If the `string` parameter passed to the constructor is a relative URI, this constructor throws a . ## Examples - The following example creates a instance with the URI `http://www.contoso.com/`. - :::code language="csharp" source="~/snippets/csharp/System/Uri/.ctor/source.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Uri/.ctor/source.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/Uri/.ctor/source.vb" id="Snippet1"::: +The following example creates a instance with the URI `http://www.contoso.com/`. + +:::code language="csharp" source="~/snippets/csharp/System/Uri/.ctor/source.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Uri/.ctor/source.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System/Uri/.ctor/source.vb" id="Snippet1"::: ]]> @@ -224,31 +228,19 @@ The following code snippet shows example values of the various properties on the -or- - The password specified in is not valid. - - -or- - - The host name specified in is not valid. - - -or- - - The file name specified in is not valid. - - -or- - - The user name specified in is not valid. + The password, host name, file name, or user name specified in is not valid. -or- - The host or authority name specified in cannot be terminated by backslashes. + The host or authority name specified in is terminated by backslashes. -or- - The port number specified in is not valid or cannot be parsed. + The port number specified in is not valid or can't be parsed. -or- - The length of exceeds 65519 characters. + The length of exceeds 65519 characters (.NET 9 and earlier versions only). -or- @@ -256,11 +248,11 @@ The following code snippet shows example values of the various properties on the -or- - There is an invalid character sequence in . + There's an invalid character sequence in . -or- - The MS-DOS path specified in must start with c:\\\\. + The MS-DOS path specified in doesn't start with c:\\\\. @@ -310,8 +302,8 @@ The following code snippet shows example values of the various properties on the - An instance of the class containing the information required to serialize the new instance. - An instance of the class containing the source of the serialized stream associated with the new instance. + The information required to serialize the new instance. + The source of the serialized stream associated with the new instance. Initializes a new instance of the class from the specified instances of the and classes. + The MS-DOS path specified in the URI doesn't start with c:\\\\. XML and SOAP Serialization @@ -440,20 +420,22 @@ The following code snippet shows example values of the various properties on the instance from a URI string. It parses the URI and puts it in canonical format. - The `dontEscape` parameter controls whether reserved characters are translated into escape sequences. This parameter should be set to `true` only if you are certain that all reserved characters in the URI have been escaped. Setting the value to `true` for a URI that has not been completely escaped can cause unexpected behavior. It is strongly recommended that you always set this parameter to `false`. +This constructor creates a instance from a URI string. It parses the URI and puts it in canonical format. - If `dontEscape` is set to `false`, the constructor escapes any reserved characters by checking that all occurrences of percent (%) are followed by a valid escape sequence. If the character sequence following a percent is not valid, the percent is replaced by %25. +The `dontEscape` parameter controls whether reserved characters are translated into escape sequences. This parameter should be set to `true` only if you are certain that all reserved characters in the URI have been escaped. Setting the value to `true` for a URI that has not been completely escaped can cause unexpected behavior. It is strongly recommended that you always set this parameter to `false`. - This constructor does not ensure that the refers to an accessible resource. +If `dontEscape` is set to `false`, the constructor escapes any reserved characters by checking that all occurrences of percent (%) are followed by a valid escape sequence. If the character sequence following a percent is not valid, the percent is replaced by %25. + +This constructor does not ensure that the refers to an accessible resource. ## Examples - The following example creates a instance for the URI `http://www.contoso.com/Hello%20World.htm`. Because the contained URI is completely escaped and is in canonical form, the `dontEscape` parameter can be set to `true`. - :::code language="csharp" source="~/snippets/csharp/System/Uri/.ctor/source1.cs" id="Snippet1"::: - :::code language="fsharp" source="~/snippets/fsharp/System/Uri/.ctor/source1.fs" id="Snippet1"::: - :::code language="vb" source="~/snippets/visualbasic/System/Uri/.ctor/source1.vb" id="Snippet1"::: +The following example creates a instance for the URI `http://www.contoso.com/Hello%20World.htm`. Because the contained URI is completely escaped and is in canonical form, the `dontEscape` parameter can be set to `true`. + +:::code language="csharp" source="~/snippets/csharp/System/Uri/.ctor/source1.cs" id="Snippet1"::: +:::code language="fsharp" source="~/snippets/fsharp/System/Uri/.ctor/source1.fs" id="Snippet1"::: +:::code language="vb" source="~/snippets/visualbasic/System/Uri/.ctor/source1.vb" id="Snippet1"::: ]]> @@ -472,31 +454,19 @@ The following code snippet shows example values of the various properties on the -or- - The password specified in is not valid. + The password, host name, file name, or user name specified in is not valid. -or- - The host name specified in is not valid. + The host or authority name specified in is terminated by backslashes. -or- - The file name specified in is not valid. + The port number specified in is not valid or can't be parsed. -or- - The user name specified in is not valid. - - -or- - - The host or authority name specified in cannot be terminated by backslashes. - - -or- - - The port number specified in is not valid or cannot be parsed. - - -or- - - The length of exceeds 65519 characters. + The length of exceeds 65519 characters (.NET 9 and earlier versions only). -or- @@ -508,7 +478,7 @@ The following code snippet shows example values of the various properties on the -or- - The MS-DOS path specified in must start with c:\\\\. + The MS-DOS path specified in doesn't start with c:\\\\. @@ -605,14 +575,17 @@ The following code snippet shows example values of the various properties on the - A string that identifies the resource to be represented by the instance. Note that an IPv6 address in string form must be enclosed within brackets. For example, "http://[2607:f8b0:400d:c06::69]". + A string that identifies the resource to be represented by the instance. Specifies whether the URI string is a relative URI, absolute URI, or is indeterminate. Initializes a new instance of the class with the specified URI. This constructor allows you to specify if the URI string is a relative URI, absolute URI, or is indeterminate. is specified, the URI string can be relative or absolute. + +Relative and absolute URIs have different restrictions on their format. For example, a relative URI does not require a scheme or an authority. The value you specify in `uriKind` must match the type of URI passed in `uriString`. However, if is specified, the URI string can be relative or absolute. + +For `uriString`, an IPv6 address in string form must be enclosed within brackets, for example, "http://[2607:f8b0:400d:c06::69]". ]]> @@ -642,23 +615,11 @@ The following code snippet shows example values of the various properties on the -or- - The password specified in is not valid. + The password, host name, file name, or user name specified in is not valid. -or- - The host name specified in is not valid. - - -or- - - The file name specified in is not valid. - - -or- - - The user name specified in is not valid. - - -or- - - The host or authority name specified in cannot be terminated by backslashes. + The host or authority name specified in is terminated by backslashes. -or- @@ -666,7 +627,7 @@ The following code snippet shows example values of the various properties on the -or- - The length of exceeds 65519 characters. + The length of exceeds 65519 characters (.NET 9 and earlier versions only). -or- @@ -678,7 +639,7 @@ The following code snippet shows example values of the various properties on the -or- - The MS-DOS path specified in must start with c:\\\\. + The MS-DOS path specified in doesn't start with c:\\\\. @@ -737,6 +698,7 @@ The following code snippet shows example values of the various properties on the instance by combining the `baseUri` and the `relativeUri`. If `relativeUri` is an absolute URI (containing a scheme, host name, and optionally a port number), the instance is created using only `relativeUri`. If the `baseUri` has relative parts (like `/api`), then the relative part must be terminated with a slash, (like `/api/`), if the relative part of `baseUri` is to be preserved in the constructed . @@ -746,6 +708,7 @@ The following code snippet shows example values of the various properties on the This constructor does not ensure that the refers to an accessible resource. ## Examples + The following example creates a new instance of the class by combining the relative URIs `http://www.contoso.com` and `catalog/shownew.htm` to form the absolute URI `http://www.contoso.com/catalog/shownew.htm`. :::code language="csharp" source="~/snippets/csharp/System/Uri/.ctor/source2.cs" interactive="try-dotnet-method" id="Snippet1"::: @@ -772,23 +735,11 @@ The following code snippet shows example values of the various properties on the -or- - The password specified in the URI formed by combining and is not valid. + The password, host name, file name, or user name specified in the URI formed by combining and is not valid. -or- - The host name specified in the URI formed by combining and is not valid. - - -or- - - The file name specified in the URI formed by combining and is not valid. - - -or- - - The user name specified in the URI formed by combining and is not valid. - - -or- - - The host or authority name specified in the URI formed by combining and cannot be terminated by backslashes. + The host or authority name specified in the URI formed by combining and is terminated by backslashes. -or- @@ -796,7 +747,7 @@ The following code snippet shows example values of the various properties on the -or- - The length of the URI formed by combining and exceeds 65519 characters. + The length of the URI formed by combining and exceeds 65519 characters (.NET 9 and earlier versions only). -or- @@ -808,7 +759,7 @@ The following code snippet shows example values of the various properties on the -or- - The MS-DOS path specified in must start with c:\\\\. + The MS-DOS path specified in doesn't start with c:\\\\. @@ -858,15 +809,17 @@ The following code snippet shows example values of the various properties on the instance by combining an absolute instance, `baseUri`, with a relative instance, `relativeUri`. If `relativeUri` is an absolute instance (containing a scheme, host name, and optionally a port number), the instance is created using only `relativeUri`. If the `baseUri` has relative parts (like `/api`), then the relative part must be terminated with a slash, (like `/api/`), if the relative part of `baseUri` is to be preserved in the constructed . - Additionally, if the `relativeUri` begins with a slash, then it will replace any relative part of the `baseUri` + Additionally, if the `relativeUri` begins with a slash, then it will replace any relative part of the `baseUri`. This constructor does not ensure that the refers to an accessible resource. ## Examples + This example creates an absolute instance, `absoluteUri`, and a relative instance, `relativeUri`. A new instance, `combinedUri`, is then created from these two instances. :::code language="csharp" source="~/snippets/csharp/System/Uri/.ctor/nclurienhancements.cs" interactive="try-dotnet-method" id="Snippet2"::: @@ -895,23 +848,11 @@ The URI formed by combining and and is not valid. - - -or- - - The host name specified in the URI formed by combining and is not valid. + The password, host name, file name, or user name specified in the URI formed by combining and is not valid. -or- - The file name specified in the URI formed by combining and is not valid. - - -or- - - The user name specified in the URI formed by combining and is not valid. - - -or- - - The host or authority name specified in the URI formed by combining and cannot be terminated by backslashes. + The host or authority name specified in the URI formed by combining and is terminated by backslashes. -or- @@ -919,7 +860,7 @@ The URI formed by combining and and exceeds 65519 characters. + The length of the URI formed by combining and exceeds 65519 characters (.NET 9 and earlier versions only). -or- @@ -931,7 +872,7 @@ The URI formed by combining and must start with c:\\\\. + The MS-DOS path specified in doesn't start with c:\\\\. @@ -1003,6 +944,7 @@ The URI formed by combining and instance by combining `baseUri` and `relativeUri`. If the URI passed in `relativeUri` is an absolute URI (containing a scheme, host name, and optionally a port number), the instance is created using only `relativeUri`. The `dontEscape` parameter controls whether reserved characters are translated into escape sequences. This parameter should be set to `true` only if you are certain that all reserved characters in the URI have been escaped. Setting the value to `true` for a URI that has not been completely escaped can cause unexpected behavior. It is strongly recommended that you always set this parameter to `false`. If `dontEscape` is set to `false`, the constructor escapes any reserved characters by checking that all occurrences of percent (%) are followed by a valid escape sequence. If the character sequence following a percent is not valid, the percent is replaced by %25. @@ -1010,6 +952,7 @@ The URI formed by combining and and and is not valid. - - -or- - - The host name specified in the URI formed by combining and is not valid. - - -or- - - The file name specified in the URI formed by combining and is not valid. - - -or- - - The user name specified in the URI formed by combining and is not valid. + The password, host name, file name, or user name specified in the URI formed by combining and is not valid. -or- - The host or authority name specified in the URI formed by combining and cannot be terminated by backslashes. + The host or authority name specified in the URI formed by combining and is terminated by backslashes. -or- @@ -1058,7 +989,7 @@ The URI formed by combining and and exceeds 65519 characters. + The length of the URI formed by combining and exceeds 65519 characters (.NET 9 and earlier versions only). -or- @@ -1070,7 +1001,7 @@ The URI formed by combining and must start with c:\\\\. + The MS-DOS path specified in doesn't start with c:\\\\. Because of security concerns, your application should not call this constructor with URI strings from untrusted sources and with set to . Alternately, you can check a URI string for validity by calling the method prior to calling this constructor.