System.Uri-Klasse

Dieser Artikel enthält ergänzende Hinweise zur Referenzdokumentation für diese API.

Ein URI ist eine kompakte Darstellung einer Ressource, die für Ihre Anwendung im Intranet oder Internet verfügbar ist. Die Uri Klasse definiert die Eigenschaften und Methoden für die Behandlung von URIs, einschließlich Analysieren, Vergleichen und Kombinieren. Die Uri Klasseneigenschaften sind schreibgeschützt. Verwenden Sie zum Erstellen eines modifizierbaren Objekts die UriBuilder Klasse.

Relative URIs (z. B. "/new/index.htm") müssen in Bezug auf einen Basis-URI erweitert werden, sodass sie absolut sind. Die MakeRelativeUri Methode wird bereitgestellt, um absolute URIs bei Bedarf in relative URIs zu konvertieren.

Die Uri Konstruktoren enthalten keine Escape-URI-Zeichenfolgen, wenn es sich bei der Zeichenfolge um einen wohlgeformten URI handelt, einschließlich eines Schemabezeichners.

Die Uri Eigenschaften geben eine kanonische Datendarstellung in escaped-Codierung zurück, wobei alle Zeichen mit Unicode-Werten größer als 127 durch ihre hexadezimalen Entsprechungen ersetzt werden. Um den URI in kanonischer Form zu platzieren, führt der Uri Konstruktor die folgenden Schritte aus:

• Konvertiert das URI-Schema in Kleinbuchstaben.

• Konvertiert den Hostnamen in Kleinbuchstaben.

• Wenn der Hostname eine IPv6-Adresse ist, wird die kanonische IPv6-Adresse verwendet. ScopeId und andere optionale IPv6-Daten werden entfernt.

• Entfernt Standard- und leere Portnummern.

• Konvertiert implizite Dateipfade ohne das file:// Schema (z. B. "C:\my\file") in explizite Dateipfade mit dem file://-Schema.

• Escapezeichen (auch als prozentcodierte Oktette bezeichnet), die keinen reservierten Zweck haben, werden decodiert (auch bekannt als unescaped). Diese nicht reservierten Zeichen umfassen Groß- und Kleinbuchstaben (%41-%5A und %61-%7A), Dezimalziffern (%30-%39), Bindestrich (%2D), Punkt (%2E), Unterstrich (%5F) und Tilde (%7E).

• Kanonisiert den Pfad für hierarchische URIs durch Komprimieren von Sequenzen wie /./, /.. /, und // (unabhängig davon, ob die Sequenz escaped ist). Beachten Sie, dass es einige Schemas gibt, für die diese Sequenzen nicht komprimiert werden.

• Bei hierarchischen URIs wird eine hinzugefügt, wenn der Host nicht mit einem Schrägstrich (/) beendet wird.

• Standardmäßig werden alle reservierten Zeichen im URI gemäß RFC 2396 escaped. Dieses Verhalten ändert sich, wenn internationale Ressourcenbezeichner oder internationale Do Standard Namenanalyse aktiviert ist, in diesem Fall reservierte Zeichen im URI gemäß RFC 3986 und RFC 3987 escaped werden.

Im Rahmen der Kanonisierung im Konstruktor für einige Schemas werden Punktsegmente und leere Segmente (/./, /../und //) komprimiert (mit anderen Worten, sie werden entfernt). Zu den Schemas, für die Uri Segmente komprimiert werden, gehören http, https, tcp, net.pipe und net.tcp. Bei einigen anderen Schemas werden diese Sequenzen nicht komprimiert. Der folgende Codeausschnitt zeigt, wie die Komprimierung in der Praxis aussieht. Die Escapesequenzen sind bei Bedarf nicht dargestellt und anschließend komprimiert.

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

Wenn dieser Code ausgeführt wird, wird die Ausgabe ähnlich dem folgenden Text zurückgegeben.

AbsoluteUri: http://myurl/
PathAndQuery: /

Sie können den Inhalt der Uri Klasse aus einem escapecodierten URI-Verweis in einen lesbaren URI-Verweis mithilfe der ToString Methode transformieren. Beachten Sie, dass einige reservierte Zeichen möglicherweise weiterhin in der Ausgabe der ToString Methode escapet werden. Dies ist die Unterstützung einer eindeutigen Wiederherstellung eines URI aus dem von ToString.

Einige URIs enthalten einen Fragmentbezeichner oder eine Abfrage oder beides. Ein Fragmentbezeichner ist jeder Text, der auf ein Nummernzeichen (#) folgt und nicht das Nummernzeichen enthält; Der Fragmenttext wird in der Fragment Eigenschaft gespeichert. Abfrageinformationen sind Text, der einem Fragezeichen (?) im URI folgt; der Abfragetext wird in der Query Eigenschaft gespeichert.

Hinweis

Die URI-Klasse unterstützt die Verwendung von IP-Adressen sowohl in der Quadnotation für das IPv4-Protokoll als auch für das IPv6-Protokoll durch Doppelpunkt hexadezimal. Denken Sie daran, die IPv6-Adresse wie in http://[::1] in eckige Klammern einzuschließen.

Unterstützung für internationale Ressourcenbezeichner

Webadressen werden in der Regel mit uniform-Ressourcenbezeichnern ausgedrückt, die aus einer sehr eingeschränkten Anzahl von Zeichen bestehen:

• ASCII-Großbuchstaben und -Kleinbuchstaben des englischen Alphabets
• Ziffern von 0 bis 9
• einer kleinen Anzahl weiterer ASCII-Symbole

Die Spezifikationen für URIs sind in RFC 2396, RFC 2732, RFC 3986 und RFC 3987 dokumentiert, die von der Internet Engineering Task Force (IETF) veröffentlicht wurden.

Bezeichner, die die Notwendigkeit erleichtern, Ressourcen mit anderen Sprachen als Englisch zu identifizieren und nicht-ASCII-Zeichen (Zeichen im Unicode/ISO 10646-Zeichensatz) zuzulassen, werden als internationale Ressourcenbezeichner (IRIs) bezeichnet. Die IRI-Spezifikationen werden in RFC 3987 dokumentiert, die von der IETF veröffentlicht wird. Wenn IRIs verwendet werden, kann eine URL Unicode-Zeichen enthalten.

In .NET Framework 4.5 und höheren Versionen ist IRI immer aktiviert und kann nicht mithilfe einer Konfigurationsoption geändert werden. Sie können eine Konfigurationsoption in der Datei "machine.config" oder in der Datei "app.config" festlegen, um anzugeben, ob die "Internationalized Do Standard Name (IDN)-Analyse auf den Do Standard namen angewendet werden soll. Beispiel:

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

Wenn IDN aktiviert wird, werden alle Unicode-Bezeichnungen in einem Do Standard Namen in ihre Punycode-Entsprechungen konvertiert. Punycode-Namen enthalten nur ASCII-Zeichen und beginnen immer mit dem Präfix „xn--“. So werden vorhandene DNS-Server im Internet unterstützt, da die meisten DNS-Server nur ASCII-Zeichen unterstützen (siehe RFC 3940).

Das Aktivieren von IDN wirkt sich auf den Wert der Uri.DnsSafeHost Eigenschaft aus. Das Aktivieren von IDN kann auch das Verhalten von Equals, OriginalString, und GetComponentsIsWellFormedOriginalString Methoden ändern.

Es gibt drei mögliche Werte für IDN, abhängig von den verwendeten DNS-Servern:

• idn enabled = All

  Durch diesen Wert werden alle Unicode-Domänennamen in ihre Punycode-Entsprechungen (IDN-Namen) konvertiert.

• idn enabled = AllExceptIntranet

  Durch diesen Wert werden alle Unicode-Domänennamen, die sich nicht im lokalen Intranet befinden, so konvertiert, dass die Punycode-Entsprechungen (IDN-Namen) verwendet werden. Wenn internationale Namen im lokalen Intranet verarbeitet werden sollen, müssen die DNS-Server im Intranet das Auflösen von Unicode-Namen unterstützen.

• idn enabled = None

  Durch diesen Wert werden keine Unicode-Domänennamen in ihre Punycode-Entsprechungen konvertiert. Dies ist der Standardwert.

Normalisierung und Zeichenüberprüfung erfolgen gemäß den neuesten IRI-Regeln in RFC 3986 und RFC 3987.

IRI- und IDN-Verarbeitung in der Uri Klasse kann auch mithilfe der System.Configuration.IriParsingElementKlassen , System.Configuration.IdnElementund System.Configuration.UriSection Konfigurationseinstellungsklassen gesteuert werden. Die Einstellung System.Configuration.IriParsingElement aktiviert oder deaktiviert die IRI-Verarbeitung in der Klasse Uri. Die Einstellung System.Configuration.IdnElement aktiviert oder deaktiviert die IDN-Verarbeitung in der Klasse Uri.

Die Konfigurationseinstellung für die System.Configuration.IriParsingElement und System.Configuration.IdnElement werden einmal gelesen, wenn die erste System.Uri Klasse erstellt wird. Später vorgenommene Änderungen an den Konfigurationseinstellungen werden anschließend ignoriert.

Die Klasse System.GenericUriParser wurde ebenfalls erweitert, um das Erstellen eines anpassbaren Parsers zu ermöglichen, der IRI und IDN unterstützt. Das Verhalten eines System.GenericUriParser-Objekts wird durch Übergabe einer bitweisen Kombination von Werten angegeben, die in der System.GenericUriParserOptions-Enumeration des System.GenericUriParser-Konstruktors verfügbar sind. Der GenericUriParserOptions.IriParsing-Typ gibt an, dass der Parser die in RFC 3987 angegebenen Analyseregeln für International Resource Identifiers (IRI) unterstützt.

Der GenericUriParserOptions.Idn Typ gibt an, dass der Parser die Internationalized Do Standard Name (IDN)-Analyse von Hostnamen unterstützt. In .NET 5 und höheren Versionen (einschließlich .NET Core) und .NET Framework 4.5+ wird IDN immer verwendet. In früheren Versionen bestimmt eine Konfigurationsoption, ob IDN verwendet wird.

Unterstützung für impliziten Dateipfad

Uri kann auch verwendet werden, um lokale Dateisystempfade darzustellen. Diese Pfade können explizit in URIs dargestellt werden, die mit dem file://-Schema beginnen, und implizit in URIs, die nicht über das file://-Schema verfügen. Als konkretes Beispiel sind die folgenden beiden URIs gültig und stellen denselben Dateipfad dar:

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.

Diese impliziten Dateipfade sind nicht mit der URI-Spezifikation kompatibel und sollten daher möglichst vermieden werden. Bei der Verwendung von .NET Core auf Unix-basierten Systemen können implizite Dateipfade besonders problematisch sein, da ein absoluter impliziter Dateipfad von einem relativen Pfad nicht unterschieden werden kann . Wenn eine solche Mehrdeutigkeit vorhanden ist, Uri wird der Pfad standardmäßig als absoluter URI interpretiert.

Sicherheitshinweise

Aufgrund von Sicherheitsbedenken sollte Ihre Anwendung vorsichtig sein, wenn Uri Instanzen aus nicht vertrauenswürdigen Quellen akzeptiert und dontEscape im Konstruktor festgelegt sindtrue. Sie können eine URI-Zeichenfolge auf Gültigkeit überprüfen, indem Sie die IsWellFormedOriginalString Methode aufrufen.

Bestätigen Sie beim Umgang mit nicht vertrauenswürdigen Benutzereingaben Annahmen über die neu erstellte Uri Instanz, bevor sie den Eigenschaften vertrauen. Dies kann auf folgende Weise erfolgen:

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

Diese Überprüfung kann in anderen Fällen verwendet werden, z. B. beim Umgang mit UNC-Pfaden, indem Sie einfach folgendes baseUriändern:

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

Überlegungen zur Leistung

Wenn Sie eine Web.config-Dateiverwenden, die URIs enthält, um Ihre Anwendung zu initialisieren, ist zusätzliche Zeit erforderlich, um die URIs zu verarbeiten, wenn ihre Schemabezeichner nicht standard sind. Initialisieren Sie in einem solchen Fall die betroffenen Teile Ihrer Anwendung, wenn die URIs erforderlich sind, nicht zum Startzeitpunkt.