Classe System.Uri

Cet article fournit des remarques supplémentaires à la documentation de référence de cette API.

Un URI (Uniform Resource Identifier) 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 constructeurs Uri n'échappent pas les chaînes URI si la chaîne est une URI bien formée comprenant un identifiant 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 échappés (également appelés octets codés en pourcentage) qui n'ont pas de fonction réservée sont décodés (également appelés « non échappés »). Ces caractères non réservés incluent des lettres majuscules et minuscules (%41-%5A et %61-%7A), des chiffres décimaux (%30-%39), des traits d’union (%2D), des points (%2E), un trait de soulignement (%5F) et tilde (%7E).
• Canonise le chemin pour les URI hiérarchiques en compactant les séquences telles que /./ et /../ (que la séquence soit é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 ne se termine pas par une barre oblique (/), celle-ci est ajoutée.
• Par défaut, tous les caractères réservés dans l’URI sont échappés conformément à la norme RFC 2396. Ce comportement change si l'analyse des identifiants de ressources internationaux ou des noms de domaine internationaux est activée, auquel cas les caractères réservés dans l'URI sont échappés conformément aux normes RFC 3986 et RFC 3987.

Dans le cadre de la canonisation dans le constructeur pour certains schémas, les segments de points (/./ et /../) sont compactés (en d’autres termes, ils sont supprimés). Les schémas pour lesquels Uri compacte des segments 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 échappées sont déséchappé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 classe Uri d'une référence URI encodée en échappement en une référence URI lisible à l'aide de la méthode ToString Veuillez noter que certains caractères réservés peuvent toujours être échappés dans la sortie de la méthode ToString. 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é.

Prise en charge de l'identifiant international des ressources

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

• Lettres ASCII majuscules et minuscules 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 des URI sont documentées dans RFC 3987 publiée par IETF. L’utilisation d’IRIs permet à une URL de contenir des caractères Unicode.

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 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- . La raison en est de prendre en charge les serveurs DNS existants sur Internet, car la plupart des serveurs DNS prennent uniquement en charge les caractères ASCII (voir 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 Equals, OriginalString, GetComponents, et IsWellFormedOriginalString.

Il existe trois valeurs possibles pour IDN en fonction des serveurs DNS utilisés :

• idn enabled = All

  Convertit les noms de domaine Unicode en leurs équivalents Punycode (noms IDN).

• idn enabled = AllExceptIntranet

  Convertit tous les noms de domaine Unicode qui ne sont pas sur l'Intranet local pour utiliser leurs équivalents Punycode (noms IDN). Dans ce cas, pour gérer les 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 activé = Aucun

  Aucun nom de domaine Unicode n’est converti pour utiliser Punycode. Il s’agit de la valeur par défaut.

La normalisation et la vérification des caractères sont effectuées en fonction des dernières règles IRI dans RFC 3986 et RFC 3987.

Le traitement IRI et IDN dans la classe Uri peut également être contrôlé avec les classes de paramétrage de configuration System.Configuration.IriParsingElement, System.Configuration.IdnElement et System.Configuration.UriSection. Le System.Configuration.IriParsingElement paramètre active ou désactive le traitement IRI dans la Uri classe. Le System.Configuration.IdnElement paramètre active ou désactive le traitement IDN dans la Uri classe.

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. Modifications apportées aux paramètres de configuration après cette période sont ignorées.

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

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 des chemins 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 de l’URI et doivent ê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é existe, Uri interprète par défaut le chemin comme une URI absolue.

Considérations relatives à la sécurité

En raison de problèmes de sécurité, votre application doit faire preuve de prudence en acceptant Uri d'instances provenant de sources non approuvées et avec dontEscape défini à true dans le constructeur. Vous pouvez vérifier la validité d’une chaîne d’URI 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 le baseUri.

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

Considérations relatives aux performances

Si vous utilisez un fichier Web.config qui 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.