Classe System.Uri

Cet article vous offre des remarques complémentaires à la documentation de référence pour cette API.

Un URI est une représentation compacte d’une ressource disponible pour votre application sur l’intranet ou Internet. La Uri classe définit les propriétés et les méthodes de gestion des URI, notamment l’analyse, la comparaison et la combinaison. Les Uri propriétés de classe sont en lecture seule ; pour créer un objet modifiable, utilisez la UriBuilder classe.

Les URI relatifs (par exemple, « /new/index.htm ») doivent être développés par rapport à un URI de base afin qu’ils soient absolus. La MakeRelativeUri méthode est fournie pour convertir des URI absolus en URI relatifs si nécessaire.

Les Uri constructeurs n’échappent pas aux chaînes d’URI si la chaîne est un URI bien formé, y compris un identificateur de schéma.

Les Uri propriétés retournent une représentation de données canonique dans l’encodage en échappement, avec tous les caractères avec des valeurs Unicode supérieures à 127 remplacées par leurs équivalents hexadécimaux. Pour placer l’URI sous forme canonique, le Uri constructeur effectue les étapes suivantes :

• Convertit le schéma d’URI en minuscules.

• Convertit le nom d’hôte en minuscules.

• Si le nom d’hôte est une adresse IPv6, l’adresse IPv6 canonique est utilisée. ScopeId et d’autres données IPv6 facultatives sont supprimées.

• Supprime les numéros de port par défaut et vides.

• Convertit les chemins de fichier implicites sans le schéma de file:// (par exemple, « C :\my\file ») en chemins de fichier explicites avec le schéma de file://.

• Les caractères échapés (également appelés octets encodés en pourcentage) qui n’ont pas d’objectif réservé sont décodés (également appelés « sans boucage »). Ces caractères non réservés incluent les lettres majuscules et minuscules (%41-%5A et %61-%7A), les chiffres décimaux (%30-%39), le trait d’union (%2D), la période (%2E), le trait de soulignement (%5F) et le tilde (%7E).

• Canonicalise le chemin d’accès pour les URI hiérarchiques en compactant des séquences telles que /./, /.. /, et // (indique si la séquence est échappée ou non). Notez qu’il existe certains schémas pour lesquels ces séquences ne sont pas compactées.

• Pour les URI hiérarchiques, si l’hôte n’est pas arrêté avec une barre oblique (/), une barre oblique est ajoutée.

• Par défaut, tous les caractères réservés dans l’URI sont placés dans une séquence d’échappement conformément à la norme RFC 2396. Ce comportement change si l’analyse International Resource Identifiers ou International Domain Name est activée, auquel cas les caractères réservés dans l’URI sont échappés conformément à RFC 3986 et RFC 3987.

Dans le cadre de la canonisation dans le constructeur pour certains schémas, segments de points et segments vides (, /../et //) sont compactés (/./en d’autres termes, ils sont supprimés). Les schémas pour lesquels Uri les segments compacts incluent http, https, tcp, net.pipe et net.tcp. Pour d’autres schémas, ces séquences ne sont pas compactées. L’extrait de code suivant montre comment le compactage se présente en pratique. Les séquences d’échappement sont non échapées, si nécessaire, puis compactées.

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}");

Lorsque ce code s’exécute, il retourne une sortie similaire au texte suivant.

AbsoluteUri: http://myurl/
PathAndQuery: /

Vous pouvez transformer le contenu de la Uri classe d’une référence d’URI encodée d’échappement en référence à une référence d’URI lisible à l’aide de la ToString méthode. Notez que certains caractères réservés peuvent toujours être échappés dans la sortie de la ToString méthode. Il s’agit de prendre en charge la reconstruction non ambiguë d’un URI à partir de la valeur retournée par ToString.

Certaines URI incluent un identificateur de fragment ou une requête ou les deux. Un identificateur de fragment est n’importe quel texte qui suit un signe numérique (#), sans inclure le signe numérique ; le texte du fragment est stocké dans la Fragment propriété. Les informations de requête sont un texte qui suit un point d’interrogation ( ?) dans l’URI ; le texte de la requête est stocké dans la Query propriété.

Remarque

La classe URI prend en charge l’utilisation d’adresses IP dans les deux notations pour le protocole IPv4 et le signe deux-points hexadécimal pour le protocole IPv6. N’oubliez pas de placer l’adresse IPv6 entre crochets, comme dans http://[ ::1].

Prise en charge de l’identificateur de ressource international

Les adresses web sont généralement exprimées à l’aide d’identificateurs de ressources uniformes qui se composent d’un ensemble très restreint de caractères :

• Lettres ASCII minuscules et majuscules de l’alphabet anglais.
• Chiffres de 0 à 9.
• Un petit nombre d’autres symboles ASCII.

Les spécifications des URI sont documentées dans RFC 2396, RFC 2732, RFC 3986 et RFC 3987 publié par internet Engineering Task Force (IETF).

Les identificateurs qui facilitent la nécessité d’identifier les ressources à l’aide de langues autres que l’anglais et d’autoriser des caractères non ASCII (caractères dans le jeu de caractères Unicode/ISO 10646) sont appelés identificateurs de ressources internationaux (IRIs). Les spécifications applicables aux IRI sont documentées dans la norme RFC 3987 publiée par l’IETF. L’utilisation d’IRI permet l’emploi de caractères Unicode dans les URL.

Dans .NET Framework 4.5 et versions ultérieures, IRI est toujours activé et ne peut pas être modifié à l’aide d’une option de configuration. Vous pouvez définir une option de configuration dans le fichier machine.config ou dans le fichier app.config pour spécifier si vous souhaitez que l’analyse IDN (Internationalized Domain Name) soit appliquée au nom de domaine. Par exemple :

<configuration>
  <uri>
    <idn enabled="All" />
  </uri>
</configuration>

L’activation d’IDN convertit toutes les étiquettes Unicode d’un nom de domaine en leurs équivalents Punycode. Les noms Punycode contiennent uniquement des caractères ASCII et commencent toujours par le préfixe xn--. Cela permet de garantir la prise en charge des serveurs DNS existants sur Internet, la plupart d’entre eux prenant uniquement en charge les caractères ASCII (consultez la norme RFC 3940).

L’activation d’IDN affecte la valeur de la Uri.DnsSafeHost propriété. L’activation d’IDN peut également modifier le comportement des méthodes et GetComponentsIsWellFormedOriginalString des EqualsméthodesOriginalString.

Il existe trois valeurs possibles pour IDN qui dépendent des serveurs DNS utilisés :

• idn enabled = All

  Cette valeur convertit tous les noms de domaine Unicode en leurs équivalents Punycode (noms IDN).

• idn enabled = AllExceptIntranet

  Cette valeur convertit tous les noms de domaine Unicode qui ne se trouvent pas sur l’intranet local pour utiliser leurs équivalents Punycode (noms IDN). Dans ce cas, pour gérer des noms internationaux sur l’intranet local, les serveurs DNS utilisés pour l'intranet doivent prendre en charge la résolution de noms Unicode.

• idn enabled = None

  Cette valeur ne convertit aucun nom de domaine Unicode pour utiliser Punycode. Il s’agit de la valeur par défaut.

La normalisation et les case activée de caractères sont effectuées conformément aux dernières règles IRI dans RFC 3986 et RFC 3987.

Le traitement IRI et IDN dans la Uri classe peut également être contrôlé à l’aide des System.Configuration.IriParsingElementclasses de paramètre , System.Configuration.IdnElementet System.Configuration.UriSection de configuration. Le paramètre System.Configuration.IriParsingElement active ou désactive le traitement des IRI dans la classe Uri. Le paramètre System.Configuration.IdnElement active ou désactive le traitement des IDN dans la classe Uri.

Le paramètre de configuration de l’objet System.Configuration.IriParsingElement et System.Configuration.IdnElement est lu une fois lorsque la première System.Uri classe est construite. Les changements apportés ultérieurement aux paramètres de configuration sont ignorés.

La classe System.GenericUriParser a également été étendue pour permettre la création d’un analyseur personnalisable qui prend en charge les IRI et les IDN. Le comportement d’un objet System.GenericUriParser est spécifié en passant une combinaison d’opérations au niveau du bit des valeurs disponibles dans l’énumération System.GenericUriParserOptions au constructeur System.GenericUriParser. Le type GenericUriParserOptions.IriParsing indique que l’analyseur prend en charge les règles d’analyse spécifiées dans la norme RFC 3987 pour les IRI (International Resource Identifier).

Le GenericUriParserOptions.Idn type indique que l’analyseur prend en charge l’analyse IDN (Internationalized Domain Name) des noms d’hôtes. Dans .NET 5 et versions ultérieures (y compris .NET Core) et .NET Framework 4.5+, IDN est toujours utilisé. Dans les versions précédentes, une option de configuration détermine si IDN est utilisé.

Prise en charge implicite du chemin d’accès aux fichiers

Uri peut également être utilisé pour représenter les chemins d’accès du système de fichiers local. Ces chemins d’accès peuvent être représentés explicitement dans les URI commençant par le schéma file:// et implicitement dans les URI qui n’ont pas le schéma de file://. En guise d’exemple concret, les deux URI suivants sont valides et représentent le même chemin d’accès au fichier :

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.

Ces chemins de fichier implicites ne sont pas conformes à la spécification d’URI et doivent donc être évités si possible. Lorsque vous utilisez .NET Core sur des systèmes Unix, les chemins de fichiers implicites peuvent être particulièrement problématiques, car un chemin d’accès de fichier implicite absolu est indistinguishable à partir d’un chemin relatif. Lorsque cette ambiguïté est présente, Uri la valeur par défaut consiste à interpréter le chemin en tant qu’URI absolu.

Considérations de sécurité

En raison de problèmes de sécurité, votre application doit utiliser la prudence lors de l’acceptation Uri d’instances provenant de sources non approuvées et avec dontEscape la valeur définie true dans le constructeur. Vous pouvez case activée une chaîne d’URI pour la validité en appelant la IsWellFormedOriginalString méthode.

Lorsque vous traitez d’une entrée utilisateur non approuvée, confirmez les hypothèses relatives à l’instance nouvellement créée Uri avant d’approuver ses propriétés. Pour ce faire, procédez comme suit :

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.
}

Cette validation peut être utilisée dans d’autres cas, comme lors du traitement des chemins UNC, en modifiant simplement les baseUripoints suivants :

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

Considérations relatives aux performances

Si vous utilisez un fichier Web.configqui contient des URI pour initialiser votre application, un délai supplémentaire est nécessaire pour traiter les URI si leurs identificateurs de schéma ne sont pas standard. Dans ce cas, initialisez les parties affectées de votre application lorsque les URI sont nécessaires, et non au moment du début.