System.Uri – třída

Tento článek obsahuje doplňující poznámky k referenční dokumentaci pro toto rozhraní API.

Identifikátor URI je kompaktní reprezentace prostředku dostupného vaší aplikaci na intranetu nebo internetu. Třída Uri definuje vlastnosti a metody pro zpracování identifikátorů URI, včetně analýzy, porovnání a kombinování. Vlastnosti Uri třídy jsou jen pro čtení. Chcete-li vytvořit upravitelný objekt, použijte UriBuilder třídu.

Relativní identifikátory URI (například /new/index.htm) musí být rozbalené s ohledem na základní identifikátor URI, aby byly absolutní. Metoda MakeRelativeUri je k dispozici k převodu absolutních identifikátorů URI na relativní identifikátory URI v případě potřeby.

Konstruktory Uri neuniknou řetězcům identifikátoru URI, pokud je řetězec dobře formátovaný identifikátor URI včetně identifikátoru schématu.

Vlastnosti Uri vrací kanonickou reprezentaci dat v řídicím kódování, přičemž všechny znaky s hodnotami Unicode větší než 127 nahrazeny jejich šestnáctkové ekvivalenty. Pokud chcete identifikátor URI vložit do kanonického tvaru, Uri konstruktor provede následující kroky:

• Převede schéma identifikátoru URI na malá písmena.

• Převede název hostitele na malá písmena.

• Pokud je název hostitele adresa IPv6, použije se kanonická adresa IPv6. ScopeId a další volitelná data IPv6 se odeberou.

• Odebere výchozí a prázdná čísla portů.

• Převede implicitní cesty k souborům bez schématu file:// (například C:\my\file) na explicitní cesty k souborům se schématem file://.

• Řídicí znaky (označované také jako oktety s kódováním procenta), které nemají vyhrazený účel, jsou dekódovány (označuje se také jako unescaped). Mezi nezarezervované znaky patří velká a malá písmena (%41–%5A a %61–%7A), desetinná čísla (%30–%39), spojovník (%2D), tečka (%2E), podtržítko (%5F) a vlnovka (%7E).

• Canonicalizes the path for hierarchical URIs by compacting sequences such as /./, /.. /, a // (zda je sekvence řídicím znakem). Všimněte si, že existují některá schémata, pro která tato sekvence nejsou komprimována.

• Pokud není hostitel ukončen lomítkem (/), přidá se u hierarchických identifikátorů URI.

• Ve výchozím nastavení jsou všechny rezervované znaky v identifikátoru URI řídicí znaky v souladu s dokumentem RFC 2396. Toto chování se změní, pokud je povolené parsování mezinárodních identifikátorů prostředků nebo mezinárodního názvu domény, v takovém případě jsou rezervované znaky v identifikátoru URI uchvácené v souladu s dokumentem RFC 3986 a RFC 3987.

V rámci kanonizace v konstruktoru pro některá schémata jsou tečkované segmenty a prázdné segmenty (/./, /../a //) komprimovány (jinými slovy, jsou odebrány). Schémata, pro která Uri komprimují segmenty, zahrnují http, https, tcp, net.pipe a net.tcp. U některých dalších schémat nejsou tyto sekvence komprimovány. Následující fragment kódu ukazuje, jak komprimace vypadá v praxi. Řídicí sekvence jsou v případě potřeby neuskutečené a pak komprimované.

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

Když se tento kód spustí, vrátí výstup podobný následujícímu textu.

AbsoluteUri: http://myurl/
PathAndQuery: /

Obsah třídy můžete transformovat Uri z řídicího zakódovaného odkazu URI na čitelný odkaz URI pomocí ToString metody. Všimněte si, že některé rezervované znaky mohou být stále u řídicích znaků ve výstupu ToString metody. Toto je podpora jednoznačného obnovení identifikátoru URI z hodnoty vrácené ToStringhodnotou .

Některé identifikátory URI obsahují identifikátor fragmentu, dotaz nebo obojí. Identifikátor fragmentu je jakýkoli text, který následuje za znaménkem čísla (#), který neobsahuje znaménko čísla; text fragmentu Fragment je uložen ve vlastnosti. Informace o dotazu jsou jakýkoli text, který se řídí otazníkem (?) v identifikátoru URI; text dotazu je uložen ve Query vlastnosti.

Poznámka:

Třída URI podporuje použití IP adres v quad-notation pro protokol IPv4 i dvojtečka-hexadecimal pro protokol IPv6. Nezapomeňte uzavřít adresu IPv6 do hranatých závorek, jako v http://[::1].

Podpora mezinárodních identifikátorů prostředků

Webové adresy se obvykle vyjadřují pomocí jednotných identifikátorů prostředků, které se skládají z velmi omezené sady znaků:

• Velká a malá písmena ASCII z anglické abecedy.
• Číslice od 0 do 9
• Malý počet dalších symbolů ASCII.

Specifikace identifikátorů URI jsou zdokumentované v dokumentu RFC 2396, RFC 2732, RFC 3986 a RFC 3987 publikovaném skupinou IETF (Internet Engineering Task Force).

Identifikátory, které usnadňují identifikaci prostředků pomocí jiných jazyků než angličtiny a umožňují znaky jiné než ASCII (znaky v znakové sadě Unicode/ISO 10646), se označují jako mezinárodní identifikátory prostředků (IRI). Specifikace IRI jsou zdokumentované v DOKUMENTU RFC 3987 publikovaném IETF. Použití rozhraní IRI umožňuje adrese URL obsahovat znaky Unicode.

V rozhraní .NET Framework 4.5 a novějších verzích je rozhraní IRI vždy povolené a nejde ho změnit pomocí možnosti konfigurace. V souboru machine.config nebo v souboru app.config můžete nastavit možnost konfigurace, abyste určili, jestli se má na název domény použít analýza IDN (Internationalized Domain Name). Příklad:

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

Povolení IDN převede všechny popisky Unicode v názvu domény na jejich ekvivalenty Punycode. Punycode names contain only ASCII characters and always start with the xn-- prefix. Důvodem je podpora stávajících serverů DNS na internetu, protože většina serverů DNS podporuje pouze znaky ASCII (viz RFC 3940).

Povolení IDN ovlivňuje hodnotu Uri.DnsSafeHost vlastnosti. Povolení IDN může také změnit chování Equals, OriginalString, GetComponentsa IsWellFormedOriginalString metody.

Existují tři možné hodnoty pro IDN v závislosti na používaných serverech DNS:

• idn enabled = All

  Tato hodnota převede všechny názvy domén Unicode na jejich ekvivalenty punycode (názvy IDN).

• idn enabled = AllExceptIntranet

  Tato hodnota převede všechny názvy domén Unicode, které nejsou v místním intranetu, aby používaly ekvivalenty punycode (názvy IDN). V tomto případě pro zpracování mezinárodních názvů v místním intranetu by servery DNS používané pro intranet měly podporovat překlad názvů Unicode.

• idn enabled = None

  Tato hodnota nepřevedne žádné názvy domén Unicode tak, aby používaly Punycode. Tato hodnota je výchozí.

Normalizace a kontrola znaků se provádí podle nejnovějších pravidel IRI v RFC 3986 a RFC 3987.

Zpracování IRI a IDN ve Uri třídě lze také řídit pomocí System.Configuration.IriParsingElementtříd nastavení , System.Configuration.IdnElementa System.Configuration.UriSection konfigurace. Nastavení System.Configuration.IriParsingElement povolí nebo zakáže zpracování IRI ve Uri třídě. Nastavení System.Configuration.IdnElement povolí nebo zakáže zpracování IDN ve Uri třídě.

Nastavení konfigurace pro objekt a System.Configuration.IriParsingElementSystem.Configuration.IdnElement jsou čteno jednou při vytvoření první System.Uri třídy. Změny nastavení konfigurace po uplynutí této doby se ignorují.

Třída System.GenericUriParser byla také rozšířena tak, aby umožňovala vytvoření přizpůsobitelného analyzátoru, který podporuje IRI a IDN. Chování objektu System.GenericUriParser je určeno předáním bitové kombinace hodnot dostupných ve System.GenericUriParserOptions výčtu konstruktoru System.GenericUriParser . Typ GenericUriParserOptions.IriParsing indikuje, že analyzátor podporuje pravidla analýzy zadaná v dokumentu RFC 3987 pro mezinárodní identifikátory zdrojů (IRI).

Typ GenericUriParserOptions.Idn označuje, že analyzátor podporuje parsování názvů hostitelů internationalizovaný název domény (IDN). V .NET 5 a novějších verzích (včetně .NET Core) a .NET Framework 4.5+ se idN vždy používá. V předchozích verzích určuje možnost konfigurace, jestli se používá IDN.

Podpora implicitní cesty k souborům

Uri lze také použít k reprezentaci místních cest systému souborů. Tyto cesty lze vyjádřit explicitně v identifikátorech URI, které začínají schématem file://, a implicitně v identifikátorech URI, které nemají schéma file://. V konkrétním příkladu jsou platné následující dvě identifikátory URI a představují stejnou cestu k souboru:

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.

Tyto implicitní cesty k souborům nevyhovují specifikaci identifikátoru URI, a proto by se měly vyhnout, pokud je to možné. Při použití .NET Core v systémech unixových systémů může být implicitní cesty k souborům obzvláště problematické, protože absolutní implicitní cesta k souboru je nerozlišitelná od relativní cesty. Pokud je tato nejednoznačnost přítomna, Uri ve výchozím nastavení se cesta interpretuje jako absolutní identifikátor URI.

Bezpečnostní aspekty

Vzhledem k obavám o zabezpečení by vaše aplikace měla při přijímání Uri instancí z nedůvěryhodných zdrojů a při dontEscape nastavení true v konstruktoru používat upozornění. Řetězec identifikátoru URI můžete zkontrolovat tak, že zavoláte metodu IsWellFormedOriginalString .

Při práci s nedůvěryhodným uživatelským vstupem potvrďte předpoklady o nově vytvořené Uri instanci předtím, než důvěřujete jeho vlastnostem. To lze provést následujícím způsobem:

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

Toto ověřování lze použít v jiných případech, například při práci s cestami UNC, jednoduše změnou baseUri:

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

Důležité informace o výkonu

Pokud k inicializaci aplikace použijete soubor Web.config, který obsahuje identifikátory URI, je potřeba další čas ke zpracování identifikátorů URI, pokud jejich identifikátory schématu nejsou nestandardní. V takovém případě inicializovat ovlivněné části aplikace, pokud jsou potřeba identifikátory URI, ne v počátečním čase.