třída System.Uri

Poznámka:

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

Identifikátor URI (Uniform Resource Identifier) je kompaktní reprezentace prostředku dostupného vaší aplikaci v 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 rozšířeny s ohledem na základní identifikátor URI tak, 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 neunikají řetězcům URI, pokud je řetězec dobře formátovaným URI včetně určení schématu.

Vlastnosti Uri vrací kanonickou reprezentaci dat v upraveném kódování, přičemž všechny znaky s hodnotami Unicode většími než 127 jsou nahrazeny jejich šestnáctkovými 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://.
  • Upravené znaky (také označované jako oktety kódované procenty), které nemají vyhrazený účel, jsou dekódovány (označováno také jako dezakódované). Mezi nezarezervované znaky patří velká a malá písmena (%41-%5A a %61-%7A), desetinné číslice (%30-%39), pomlčka (%2D), tečka (%2E), podtržítko (%5F) a vlnovka (%7E).
  • Kanonizuje cestu hierarchických URI zmenšením sekvencí, jako jsou /./ a /../ (bez ohledu na to, zda je sekvence eskapovaná). Všimněte si, že existují některá schémata, pro která tato sekvence nejsou komprimována.
  • U hierarchických identifikátorů URI, pokud host není ukončen lomítkem (/), jedno se přidá.
  • Ve výchozím nastavení jsou všechny rezervované znaky v identifikátoru URI převedeny na unikátní kódové sekvence 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čkové 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. Escape sekvence jsou v případě potřeby odstraněny a poté zhuštěny.

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 Uri můžete transformovat z escape kódovaného odkazu URI na čitelný odkaz URI pomocí metody ToString. Všimněte si, že některé rezervované znaky mohou být ve výstupu metody ToString stále uniknuté. Toto má podporovat jednoznačnou rekonstrukci identifikátoru URI z hodnoty vrácené ToString.

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 dotazu je jakýkoli text, který následuje za otazníkem (?) v URI; text dotazu je uložen v Query vlastnosti.

Poznámka:

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

Podpora identifikátorů mezinárodních zdrojů

Webové adresy se obvykle vyjadřují pomocí identifikátorů URI, 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 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). Například:

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

Povolením IDN se všechny Unicode popisky v názvu domény převedou na jejich Punycode ekvivalenty. Názvy v Punycode obsahují pouze znaky ASCII a vždy začínají prefixem xn--. 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 povoleno = vše

    Převede všechny názvy domén Unicode na jejich ekvivalenty Punycode (názvy IDN).

  • idn povolené = VšechnoMimoIntranet

    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ě by pro zpracování mezinárodních názvů v místním intranetu měly servery DNS používané pro intranet podporovat překlad názvů Unicode.

  • povoleno idn = Žádný

    Nejsou převedeny žádné názvy domén Unicode tak, aby používaly Punycode. Toto je výchozí hodnota.

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í tříd nastavení System.Configuration.IriParsingElement, System.Configuration.IdnElement a System.Configuration.UriSection konfiguračního nastavení. 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 System.Configuration.IriParsingElement a System.Configuration.IdnElement jsou čtena pouze jednou, když je poprvé vytvořena třída System.Uri. 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í mezinárodních názvů domén (IDN) pro názvy hostitelů. 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 měly by se 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, ve výchozím nastavení se Uri cesta interpretuje jako absolutní identifikátor URI.

Bezpečnostní aspekty

Vzhledem k obavám o zabezpečení by vaše aplikace měla postupovat opatrně při přijímání Uri instancí z nedůvěryhodných zdrojů a při nastavení dontEscape na true v konstruktoru. Řetězec URI můžete zkontrolovat zavoláním metody 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.
}

Tuto validaci lze použít v jiných případech, například při práci s cestami UNC, jednoduše změňte baseUri:

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

Další podrobnosti o aspektech návrhu a bezpečnosti Uri a UriBuilder najdete v následujících dokumentech modelu hrozeb:

Důležité informace o výkonu

Pokud k inicializaci aplikace použijete souborWeb.config obsahující 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ě inicializujte ovlivněné části vaší aplikace, když jsou identifikátory URI potřeba, a ne při spuštění.

  • Last updated on