Uri Clase

Definición

public ref class Uri

public ref class Uri : IEquatable<Uri ^>, ISpanFormattable, System::Runtime::Serialization::ISerializable

public ref class Uri : System::Runtime::Serialization::ISerializable

public ref class Uri : ISpanFormattable, System::Runtime::Serialization::ISerializable

public ref class Uri : MarshalByRefObject, System::Runtime::Serialization::ISerializable

public class Uri

public class Uri : IEquatable<Uri>, ISpanFormattable, System.Runtime.Serialization.ISerializable

public class Uri : System.Runtime.Serialization.ISerializable

public class Uri : ISpanFormattable, System.Runtime.Serialization.ISerializable

[System.Serializable]
public class Uri : MarshalByRefObject, System.Runtime.Serialization.ISerializable

[System.Serializable]
[System.ComponentModel.TypeConverter(typeof(System.UriTypeConverter))]
public class Uri : System.Runtime.Serialization.ISerializable

type Uri = class

type Uri = class
    interface IEquatable<Uri>
    interface IFormattable
    interface ISpanFormattable
    interface ISerializable

type Uri = class
    interface ISerializable

type Uri = class
    interface ISpanFormattable
    interface IFormattable
    interface ISerializable

type Uri = class
    interface IFormattable
    interface ISpanFormattable
    interface IEquatable<Uri>
    interface ISerializable

[<System.Serializable>]
type Uri = class
    inherit MarshalByRefObject
    interface ISerializable

[<System.Serializable>]
[<System.ComponentModel.TypeConverter(typeof(System.UriTypeConverter))>]
type Uri = class
    interface ISerializable

Public Class Uri

Public Class Uri
Implements IEquatable(Of Uri), ISerializable, ISpanFormattable

Public Class Uri
Implements ISerializable

Public Class Uri
Implements ISerializable, ISpanFormattable

Public Class Uri
Inherits MarshalByRefObject
Implements ISerializable

Herencia

Object

Uri

Herencia

Object

MarshalByRefObject

Uri

Atributos

SerializableAttribute TypeConverterAttribute

Implementaciones

IEquatable<Uri> IFormattable ISpanFormattable ISerializable

Ejemplos

En el ejemplo siguiente se crea una instancia de la Uri clase y se usa para realizar una solicitud GET con HttpClient.

Uri siteUri = new Uri("http://www.contoso.com/");

// HttpClient lifecycle management best practices:
// https://learn.microsoft.com/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-use
HttpClient client = new HttpClient();
HttpRequestMessage request = new HttpRequestMessage(HttpMethod.Get, siteUri);
HttpResponseMessage response = client.Send(request);

let siteUri = Uri "http://www.contoso.com/"

// HttpClient lifecycle management best practices:
// https://learn.microsoft.com/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-use
use client = new HttpClient ()
use request = new HttpRequestMessage (HttpMethod.Get, siteUri)
use response = client.Send request

Dim siteUri As New Uri("http://www.contoso.com/")

' HttpClient lifecycle management best practices:
' https://learn.microsoft.com/dotnet/fundamentals/networking/http/httpclient-guidelines#recommended-use
Dim client As New HttpClient()
Dim request As New HttpRequestMessage(HttpMethod.Get, siteUri)
Dim response As HttpResponseMessage = client.Send(request)

En el fragmento de código siguiente se muestran valores de ejemplo de las distintas propiedades de la clase .

Uri uri = new Uri("https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName");

Console.WriteLine($"AbsolutePath: {uri.AbsolutePath}");
Console.WriteLine($"AbsoluteUri: {uri.AbsoluteUri}");
Console.WriteLine($"DnsSafeHost: {uri.DnsSafeHost}");
Console.WriteLine($"Fragment: {uri.Fragment}");
Console.WriteLine($"Host: {uri.Host}");
Console.WriteLine($"HostNameType: {uri.HostNameType}");
Console.WriteLine($"IdnHost: {uri.IdnHost}");
Console.WriteLine($"IsAbsoluteUri: {uri.IsAbsoluteUri}");
Console.WriteLine($"IsDefaultPort: {uri.IsDefaultPort}");
Console.WriteLine($"IsFile: {uri.IsFile}");
Console.WriteLine($"IsLoopback: {uri.IsLoopback}");
Console.WriteLine($"IsUnc: {uri.IsUnc}");
Console.WriteLine($"LocalPath: {uri.LocalPath}");
Console.WriteLine($"OriginalString: {uri.OriginalString}");
Console.WriteLine($"PathAndQuery: {uri.PathAndQuery}");
Console.WriteLine($"Port: {uri.Port}");
Console.WriteLine($"Query: {uri.Query}");
Console.WriteLine($"Scheme: {uri.Scheme}");
Console.WriteLine($"Segments: {string.Join(", ", uri.Segments)}");
Console.WriteLine($"UserEscaped: {uri.UserEscaped}");
Console.WriteLine($"UserInfo: {uri.UserInfo}");

// AbsolutePath: /Home/Index.htm
// AbsoluteUri: https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName
// DnsSafeHost: www.contoso.com
// Fragment: #FragmentName
// Host: www.contoso.com
// HostNameType: Dns
// IdnHost: www.contoso.com
// IsAbsoluteUri: True
// IsDefaultPort: False
// IsFile: False
// IsLoopback: False
// IsUnc: False
// LocalPath: /Home/Index.htm
// OriginalString: https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName
// PathAndQuery: /Home/Index.htm?q1=v1&q2=v2
// Port: 80
// Query: ?q1=v1&q2=v2
// Scheme: https
// Segments: /, Home/, Index.htm
// UserEscaped: False
// UserInfo: user:password

let uri = Uri "https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName"

printfn $"AbsolutePath: {uri.AbsolutePath}"
printfn $"AbsoluteUri: {uri.AbsoluteUri}"
printfn $"DnsSafeHost: {uri.DnsSafeHost}"
printfn $"Fragment: {uri.Fragment}"
printfn $"Host: {uri.Host}"
printfn $"HostNameType: {uri.HostNameType}"
printfn $"IdnHost: {uri.IdnHost}"
printfn $"IsAbsoluteUri: {uri.IsAbsoluteUri}"
printfn $"IsDefaultPort: {uri.IsDefaultPort}"
printfn $"IsFile: {uri.IsFile}"
printfn $"IsLoopback: {uri.IsLoopback}"
printfn $"IsUnc: {uri.IsUnc}"
printfn $"LocalPath: {uri.LocalPath}"
printfn $"OriginalString: {uri.OriginalString}"
printfn $"PathAndQuery: {uri.PathAndQuery}"
printfn $"Port: {uri.Port}"
printfn $"Query: {uri.Query}"
printfn $"Scheme: {uri.Scheme}"
printfn $"""Segments: {String.Join(", ", uri.Segments)}"""
printfn $"UserEscaped: {uri.UserEscaped}"
printfn $"UserInfo: {uri.UserInfo}"

// AbsolutePath: /Home/Index.htm
// AbsoluteUri: https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName
// DnsSafeHost: www.contoso.com
// Fragment: #FragmentName
// Host: www.contoso.com
// HostNameType: Dns
// IdnHost: www.contoso.com
// IsAbsoluteUri: True
// IsDefaultPort: False
// IsFile: False
// IsLoopback: False
// IsUnc: False
// LocalPath: /Home/Index.htm
// OriginalString: https://user:password@www.contoso.com:80/Home/Index.htm?q1=v1&q2=v2#FragmentName
// PathAndQuery: /Home/Index.htm?q1=v1&q2=v2
// Port: 80
// Query: ?q1=v1&q2=v2
// Scheme: https
// Segments: /, Home/, Index.htm
// UserEscaped: False
// UserInfo: user:password

Comentarios

Un identificador uniforme de recursos (URI) es una representación compacta de un recurso disponible para la aplicación en la intranet o En Internet. La Uri clase define las propiedades y los métodos para controlar los URI, incluido el análisis, la comparación y la combinación. Las Uri propiedades de clase son de solo lectura; para crear un objeto modificable, use la UriBuilder clase .

Los URI relativos (por ejemplo, "/new/index.htm") deben expandirse con respecto a un URI base para que sean absolutos. El MakeRelativeUri método se proporciona para convertir los URI absolutos en URI relativos cuando sea necesario.

Los constructores Uri no escapan a las cadenas de URI si la cadena es un URI bien formado, incluido un identificador de esquema.

Las Uri propiedades devuelven una representación de datos canónica en codificación con escape, con todos los caracteres con valores Unicode mayores que 127 reemplazados por sus equivalentes hexadecimales. Para colocar el URI en forma canónica, el Uri constructor realiza los pasos siguientes:

• Convierte el esquema URI en minúsculas.
• Convierte el nombre de host en minúsculas.
• Si el nombre de host es una dirección IPv6, se usa la dirección IPv6 canónica. ScopeId y otros datos IPv6 opcionales se quitan.
• Quita los números de puerto predeterminados y vacíos.
• Convierte rutas de acceso implícitas de archivo sin el esquema de file:// (por ejemplo, "C:\my\file") en rutas de acceso de archivo explícitas con el esquema file://.
• Los caracteres de escape (también conocidos como octetos codificados por porcentaje) que no tienen un propósito reservado se descodifican (también conocidos como sin escape). Estos caracteres no reservados incluyen letras mayúsculas y minúsculas (%41-%5A y %61-%7A), dígitos decimales (%30-%39), guion (%2D), punto (%2E), guion bajo (%5F) y tilde (%7E).
• Crea la versión canónica de la ruta para las URI jerárquicas mediante la compactación de secuencias como /./ y /../ (independientemente de si la secuencia está escapada). Tenga en cuenta que hay algunos esquemas para los que estas secuencias no están compactadas.
• En el caso de los URI jerárquicos, si el host no finaliza con una barra diagonal (/), se agrega una.
• De forma predeterminada, los caracteres reservados del URI se escapan de acuerdo con RFC 2396. Este comportamiento cambia si los identificadores de recursos internacionales o el análisis de nombres de dominio internacional están habilitados en cuyo caso los caracteres reservados en el URI se escapan de acuerdo con RFC 3986 y RFC 3987.

Como parte de la canonicalización en el constructor de algunos esquemas, los segmentos de puntos (/./ y /../) se compactan, por lo tanto, se eliminan. Los esquemas en los que Uri compacta segmentos incluyen http, https, tcp, net.pipe y net.tcp. Para algunos otros esquemas, estas secuencias no se compactan. En el siguiente fragmento de código se muestra cómo se ve la compactación en la práctica. Las secuencias de escape están sin escape, si es necesario, y luego se compactan.

var uri = new Uri("http://myUrl/../.."); // http scheme, unescaped
OR
var uri = new Uri("http://myUrl/%2E%2E/%2E%2E"); // http scheme, escaped
OR
var uri = new Uri("ftp://myUrl/../.."); // ftp scheme, unescaped
OR
var uri = new Uri("ftp://myUrl/%2E%2E/%2E%2E"); // ftp scheme, escaped

Console.WriteLine($"AbsoluteUri: {uri.AbsoluteUri}");
Console.WriteLine($"PathAndQuery: {uri.PathAndQuery}");

Cuando se ejecuta este código, devuelve una salida similar al texto siguiente.

AbsoluteUri: http://myurl/
PathAndQuery: /

Puede transformar el contenido de la Uri clase de una referencia de URI codificada con escape a una referencia de URI legible mediante el ToString método . Tenga en cuenta que es posible que algunos caracteres reservados todavía se escapen en la salida del ToString método . Esto es para admitir la reconstrucción inequívoca de un URI a partir del valor devuelto por ToString.

Algunos URI incluyen un identificador de fragmento o una consulta o ambas. Un identificador de fragmento es cualquier texto que siga un signo de número (#), no incluido el signo de número; el texto del fragmento se almacena en la Fragment propiedad . La información de consulta es cualquier texto que siga un signo de interrogación (?) en el URI; el texto de la consulta se almacena en la Query propiedad .

Compatibilidad con identificadores de recursos internacionales

Las direcciones web normalmente se expresan mediante URI que constan de un conjunto de caracteres muy restringido:

• Letras ASCII mayúsculas y minúsculas del alfabeto inglés.
• Dígitos de 0 a 9.
• Un pequeño número de otros símbolos ASCII.

Las especificaciones de los URI se documentan en RFC 2396, RFC 2732, RFC 3986 y RFC 3987 publicados por internet Engineering Task Force (IETF).

Los identificadores que facilitan la necesidad de identificar recursos que usan idiomas distintos del inglés y permiten caracteres no ASCII (caracteres en el juego de caracteres Unicode/ISO 10646) se conocen como identificadores de recursos internacionales (IRIs). Las especificaciones de las IRIs se documentan en RFC 3987 publicado por IETF. El uso de IRIs permite que una dirección URL contenga caracteres Unicode. La normalización y la comprobación de caracteres se realizan según las últimas reglas de IRI en RFC 3986 y RFC 3987.

El procesamiento de IRI e IDN en la Uri clase se puede controlar mediante las System.Configuration.IriParsingElementclases de configuración , System.Configuration.IdnElementy System.Configuration.UriSection . La System.Configuration.IriParsingElement configuración habilita o deshabilita el procesamiento de IRI en la Uri clase . La System.Configuration.IdnElement configuración habilita o deshabilita el procesamiento de IDN en la Uri clase .

El valor de configuración de System.Configuration.IriParsingElement y System.Configuration.IdnElement se leen una vez cuando se construye la primera System.Uri clase. Los cambios en las opciones de configuración después de ese tiempo se omiten.

La System.GenericUriParser clase también se ha ampliado para permitir la creación de un analizador personalizable que admita IRI e IDN. El comportamiento de un System.GenericUriParser objeto se especifica pasando una combinación bit a bit de los valores disponibles en la System.GenericUriParserOptions enumeración al System.GenericUriParser constructor. El GenericUriParserOptions.IriParsing tipo indica que el analizador admite las reglas de análisis especificadas en RFC 3987 para identificadores de recursos internacionales (IRI).

El tipo GenericUriParserOptions.Idn indica que el analizador admite el análisis del Nombre de dominio internacionalizado (IDN) de los nombres de host. En .NET (Core) y .NET Framework 4.5+, siempre se usa IDN. En versiones anteriores, una opción de configuración determina si se usa IDN.

Compatibilidad con ruta de archivo implícita

Uri también se puede usar para representar rutas de acceso del sistema de archivos locales. Estas rutas de acceso se pueden representar explícitamente en los URI que comienzan con el esquema de file:// y implícitamente en los URI que no tienen el esquema file://. Como ejemplo concreto, los dos URI siguientes son válidos y representan la misma ruta de acceso de archivo:

Uri uri1 = new Uri("C:/test/path/file.txt") // Implicit file path.
Uri uri2 = new Uri("file:///C:/test/path/file.txt") // Explicit file path.

Estas rutas de acceso implícitas de archivo no son compatibles con la especificación de URI y deben evitarse siempre que sea posible. Cuando se usa .NET Core en sistemas basados en Unix, las rutas de acceso implícitas a archivos pueden ser especialmente problemáticas, ya que una ruta de acceso de archivo implícita absoluta es indistinguible desde una ruta de acceso relativa. Cuando haya tal ambigüedad, Uri se debe interpretar por defecto la ruta de acceso como un URI absoluto.

Consideraciones de seguridad

Debido a problemas de seguridad, su aplicación debe tener precaución al aceptar Uri instancias de orígenes que no son de confianza y con dontEscape establecido a true en el constructor. Puede comprobar una cadena de URI para comprobar la validez llamando al IsWellFormedOriginalString método .

Al tratar con la entrada de usuario que no es de confianza, compruebe las suposiciones sobre la instancia recién creada Uri antes de confiar en sus propiedades. Esto se puede hacer de la siguiente manera:

string userInput = ...;

Uri baseUri = new Uri("https://myWebsite/files/");

if (!Uri.TryCreate(baseUri, userInput, out Uri newUri))
{
    // Fail: invalid input.
}

if (!baseUri.IsBaseOf(newUri))
{
    // Fail: the Uri base has been modified - the created Uri is not rooted in the original directory.
}

Esta validación se puede usar en otros casos, como cuando se trabaja con rutas UNC, simplemente cambiando :baseUri

Uri baseUri = new Uri(@"\\host\share\some\directory\name\");

Para obtener más información sobre el diseño y las consideraciones de seguridad de Uri y UriBuilder, revise los siguientes documentos del modelo de amenazas:

• Modelo de amenazas System.Uri
• Modelo de amenazas de System.UriBuilder

Consideraciones sobre el rendimiento

Si usa un archivo Web.config que contiene URI para inicializar la aplicación, se requiere tiempo adicional para procesar los URI si sus identificadores de esquema no son estándar. En tal caso, inicialice las partes afectadas de la aplicación cuando se necesiten los URI, no a la hora de inicio.

Seguridad para subprocesos

Todos los miembros de Uri son seguros para subprocesos y se pueden usar simultáneamente desde varios subprocesos.

Consulte también

• IdnElement
• IriParsingElement
• UriSection
• DnsSafeHost
• MakeRelative(Uri)
• IsWellFormedOriginalString()
• UriBuilder
• Cambios en el espacio de nombres System.Uri de la versión 2.0
• Compatibilidad con identificadores de recursos internacionales en System.UriSystem.Uri
• Programación de red en .NET Framework