Freigeben über

System.Uri-Klasse

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

Ein URI (Uniform Resource Identifier) 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 führen kein Escape von URI-Zeichenfolgen durch, wenn die Zeichenfolge eine wohlgeformte URI mit einem Schema-Bezeichner ist.

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.
  • Escaped-Zeichen (auch bekannt als prozentcodierte Oktetts), die keinen reservierten Zweck haben, werden decodiert (auch bekannt als Nicht-Escaped-Zeichen). 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, indem Sequenzen wie /./ und /../ komprimiert werden (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 in der URI gemäß RFC 2396 escaped. Dieses Verhalten ändert sich, wenn International Resource Identifiers oder International Domain Name Parsing aktiviert ist. In diesem Fall werden reservierte Zeichen im URI in Übereinstimmung mit RFC 3986 und RFC 3987 escaped.

Im Rahmen der Kanonisierung im Konstruktor für einige Schemas werden Punktsegmente (/./ 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 werden, falls erforderlich, unescaped und dann verdichtet.

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 in der Ausgabe der ToString-Methode möglicherweise noch als Escapezeichen angezeigt werden. Dies dient der Unterstützung einer eindeutigen Wiederherstellung eines URI aus dem zurückgegebenen Wert 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 Quad-Notation für das IPv4-Protokoll als auch in Doppelpunkt-Hexadezimal für das IPv6-Protokoll. Denken Sie daran, die IPv6-Adresse wie in http://[::1] in eckige Klammern einzuschließen.

Unterstützung internationaler Ressourcenbezeichner

Webadressen werden in der Regel mithilfe von URIs ausgedrückt, die aus einem sehr eingeschränkten Satz von Zeichen bestehen:

  • Groß- und Kleinbuchstaben ASCII-Buchstaben aus dem englischen Alphabet.
  • Ziffern von 0 bis 9.
  • Eine kleine Anzahl anderer 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 Spezifikationen für IRIs sind in RFC 3987 dokumentiert, die von IETF veröffentlicht wurden. Durch die Verwendung von IRIs 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 machine.config oder in der dateiapp.config festlegen, um anzugeben, ob die IDN-Analyse (Internationalized Domain Name) auf den Domänennamen angewendet werden soll. Beispiel:

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

Durch aktivieren von IDN werden alle Unicode-Bezeichnungen in einem Domänennamen in ihre Punycode-Entsprechungen konvertiert. Punycode-Namen enthalten nur ASCII-Zeichen und beginnen immer mit dem Xn-Präfix. Der Grund hierfür ist die Unterstützung vorhandener DNS-Server im Internet, 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.

Je nach verwendeten DNS-Servern gibt es drei mögliche Werte für IDN:

  • idn aktiviert = Alle

    Konvertiert alle Unicode-Domänennamen in ihre Punycode-Entsprechungen (IDN-Namen).

  • idn aktiviert = AllExceptIntranet

    Konvertiert alle Unicode-Domänennamen, die nicht im lokalen Intranet enthalten sind, um die Punycode-Entsprechungen (IDN-Namen) zu verwenden. Um internationale Namen im lokalen Intranet zu behandeln, sollten die für das Intranet verwendeten DNS-Server die Unicode-Namensauflösung unterstützen.

  • idn aktiviert = Keine

    Unicode-Domänennamen werden nicht in Punycode konvertiert. Dies ist der Standardwert.

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

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

Die Konfigurationseinstellung für die System.Configuration.IriParsingElement und System.Configuration.IdnElement werden einmal gelesen, wenn die erste System.Uri Klasse erstellt wird. Änderungen an den Konfigurationseinstellungen nach diesem Zeitpunkt werden ignoriert.

Die System.GenericUriParser Klasse wurde auch erweitert, um das Erstellen eines anpassbaren Parsers zu ermöglichen, der IRI und IDN unterstützt. Das Verhalten eines System.GenericUriParser Objekts wird angegeben, indem eine bitweise Kombination der werte übergeben wird, die in der System.GenericUriParserOptions Enumeration an den System.GenericUriParser Konstruktor verfügbar sind. Der GenericUriParserOptions.IriParsing Typ gibt an, dass der Parser die in RFC 3987 für International Resource Identifiers (IRI) angegebenen Analyseregeln unterstützt.

Der GenericUriParserOptions.Idn Typ gibt an, dass der Parser die Analyse von Hostnamen (Internationalized Domain Name, IDN) 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.

Implizite Dateipfadunterstützung

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 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 Zweideutigkeit vorliegt, interpretiert Uri den Pfad standardmäßig als absolute URI.

Sicherheitsüberlegungen

Aufgrund von Sicherheitsbedenken sollte Ihre Anwendung Vorsicht walten lassen, wenn Sie Uri-Instanzen aus nicht vertrauenswürdigen Quellen und mit dontEscape auf true im Konstruktor akzeptieren. Sie können eine URI-Zeichenfolge auf Gültigkeit überprüfen, indem Sie die IsWellFormedOriginalString Methode aufrufen.

Wenn Sie mit nicht vertrauenswürdigen Benutzereingaben umgehen, bestätigen Sie Annahmen über die neu erstellte Uri-Instanz, bevor Sie deren 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\");

Leistungsüberlegungen

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