Referenční sestavení

  • Článek

Referenční sestavení jsou speciálním typem sestavení, které obsahuje pouze minimální množství metadat potřebných k reprezentaci veřejného rozhraní API knihovny. Zahrnují deklarace pro všechny členy, které jsou významné při odkazování na sestavení v nástrojích sestavení, ale vyloučit všechny implementace členů a deklarace soukromých členů, které nemají žádný pozorovatelný dopad na jejich kontrakt rozhraní API. Naproti tomu běžná sestavení se nazývají implementační sestavení.

Referenční sestavení nelze načíst ke spuštění, ale lze je předat jako vstup kompilátoru stejným způsobem jako sestavení implementace. Referenční sestavení se obvykle distribuují pomocí sady SDK (Software Development Kit) konkrétní platformy nebo knihovny.

Použití referenčního sestavení umožňuje vývojářům vytvářet programy, které cílí na konkrétní verzi knihovny bez úplného sestavení implementace pro danou verzi. Předpokládejme, že máte na počítači jenom nejnovější verzi některé knihovny, ale chcete vytvořit program, který cílí na starší verzi této knihovny. Pokud kompilujete přímo proti sestavení implementace, můžete neúmyslně použít členy rozhraní API, které nejsou k dispozici v předchozí verzi. Tuto chybu najdete jenom při testování programu na cílovém počítači. Pokud zkompilujete referenční sestavení pro starší verzi, okamžitě se zobrazí chyba v době kompilace.

Referenční sestavení může také představovat kontrakt, tj. sadu rozhraní API, která neodpovídají konkrétnímu sestavení implementace. Taková referenční sestavení označovaná jako sestavení kontraktu lze použít k cílení na více platforem, které podporují stejnou sadu rozhraní API. Například .NET Standard poskytuje sestavení kontraktů netstandard.dll, které představuje sadu běžných rozhraní API sdílených mezi různými platformami .NET. Implementace těchto rozhraní API jsou obsažena v různých sestaveních na různých platformách, jako jsou mscorlib.dll v rozhraní .NET Framework nebo System.Private.CoreLib.dll v .NET Core. Knihovna, která cílí na .NET Standard, se může spouštět na všech platformách, které podporují .NET Standard.

Použití referenčních sestavení

Pokud chcete použít určitá rozhraní API z projektu, musíte přidat odkazy na jejich sestavení. Můžete přidat odkazy na sestavení implementace nebo odkaz na sestavení. Doporučujeme použít referenční sestavení vždy, když jsou k dispozici. Tím zajistíte, že v cílové verzi používáte jenom podporované členy rozhraní API, které mají používat návrháři rozhraní API. Použití referenčního sestavení zajišťuje, že nepřebírají závislost na podrobnostech implementace.

Referenční sestavení pro knihovny rozhraní .NET Framework se distribuují s balíčky cílení. Můžete je získat stažením samostatného instalačního programu nebo výběrem komponenty v instalačním programu sady Visual Studio. Další informace naleznete v tématu Instalace rozhraní .NET Framework pro vývojáře. Pro .NET Core a .NET Standard se referenční sestavení automaticky stáhnou podle potřeby (přes NuGet) a odkazují na. Pro .NET Core 3.0 a vyšší jsou referenční sestavení pro základní architekturu v balíčku Microsoft.NETCore.App.Ref ( balíček Microsoft.NETCore.App se používá místo toho pro verze starší než 3.0).

Když v sadě Visual Studio přidáte odkazy na sestavení .NET Framework pomocí dialogového okna Přidat odkaz , vyberete sestavení ze seznamu a Sada Visual Studio automaticky najde referenční sestavení, která odpovídají verzi cílové architektury vybrané v projektu. Totéž platí pro přidání odkazů přímo do projektu MSBuild pomocí položky referenčního projektu: stačí zadat pouze název sestavení, nikoli úplnou cestu k souboru. Když do příkazového řádku přidáte odkazy na tato sestavení pomocí možnosti kompilátoru -reference (v jazyce C# a v jazyce Visual Basic) nebo pomocí Compilation.AddReferences metody v rozhraní Roslyn API, je nutné ručně zadat referenční soubory sestavení pro správnou verzi cílové platformy. Referenční soubory sestavení rozhraní .NET Framework jsou umístěny v %ProgramFiles(x86)%\Referenční sestavení\Microsoft\Framework\. NETFramework directory. Pro .NET Core můžete vynutit operaci publikování ke kopírování referenčních sestavení pro vaši cílovou platformu do podadresáře publish/refs výstupního adresáře nastavením PreserveCompilationContext vlastnosti projektu na true. Tyto referenční soubory sestavení pak můžete předat kompilátoru. Použití DependencyContext balíčku Microsoft.Extensions.DependencyModel může pomoct najít jejich cesty.

Vzhledem k tomu, že neobsahují žádnou implementaci, nelze načíst referenční sestavení pro spuštění. Při pokusu o to vznikne výsledek System.BadImageFormatException. Pokud chcete prozkoumat obsah referenčního sestavení, můžete ho načíst do kontextu jen pro reflexi v rozhraní .NET Framework (pomocí Assembly.ReflectionOnlyLoad metody) nebo do MetadataLoadContext rozhraní .NET a .NET Framework.

Generování referenčních sestavení

Generování referenčních sestavení pro knihovny může být užitečné, když uživatelé knihovny potřebují vytvářet své programy v mnoha různých verzích knihovny. Distribuce implementačních sestavení pro všechny tyto verze může být nepraktické kvůli jejich velké velikosti. Referenční sestavení jsou menší a distribuují se jako součást sady SDK vaší knihovny, což snižuje velikost stahování a šetří místo na disku.

Nástroje pro vývoj a sestavení mohou také využít referenční sestavení, aby se zkrátila doba sestavení v případě velkých řešení skládajících se z více knihoven tříd. V případě přírůstkového sestavení se projekt obvykle znovu sestaví při změně některého ze vstupních souborů, včetně sestavení, na kterých závisí. Sestavení implementace se změní vždy, když programátor změní implementaci libovolného člena. Referenční sestavení se změní pouze v případech, kdy je ovlivněno jeho veřejné rozhraní API. Použití referenčního sestavení jako vstupního souboru místo sestavení implementace umožňuje v některých případech přeskočit sestavení závislého projektu.

Můžete generovat referenční sestavení:

Pokud chcete distribuovat referenční sestavení s balíčky NuGet, musíte je zahrnout do podadresáře ref\ podadresář balíčku namísto v podadresáři lib\ použité pro sestavení implementace.

Referenční struktura sestavení

Referenční sestavení jsou rozšířením souvisejícího konceptu, sestavení pouze s metadaty. Sestavení pouze metadat mají jejich těla metody nahrazena jedním throw null tělem, ale zahrnují všechny členy s výjimkou anonymních typů. Důvodem použití throw null těl (na rozdíl od žádného těla) je, že funkce PEVerify může běžet a projít (tedy ověřit úplnost metadat).

Referenční sestavení dále odeberou metadata (privátní členy) ze sestavení pouze s metadaty:

  • Referenční sestavení obsahuje pouze odkazy na to, co potřebuje na povrchu rozhraní API. Skutečné sestavení může mít další odkazy související s konkrétními implementacemi. Například referenční sestavení pro class C { private void M() { dynamic d = 1; ... } } neodkazuje na žádné typy vyžadované pro dynamic.
  • Soukromé členy funkce (metody, vlastnosti a události) se odeberou v případech, kdy jejich odebrání nepozorovaně neovlivní kompilaci. Pokud neexistují žádné atributy InternalsVisibleTo , interní členy funkce jsou také odebrány.

Metadata v referenčních sestaveních nadále udržují následující informace:

  • Všechny typy, včetně privátních a vnořených typů.
  • Všechny atributy, i interní.
  • Všechny virtuální metody.
  • Explicitní implementace rozhraní
  • Explicitně implementované vlastnosti a události, protože jejich přístupové objekty jsou virtuální.
  • Všechna pole struktur.

Referenční sestavení zahrnují atribut ReferenceAssembly na úrovni sestavení. Tento atribut může být zadán ve zdroji; pak kompilátor nebude muset syntetizovat. Vzhledem k tomuto atributu moduly runtime nebudou muset načíst referenční sestavení pro spuštění (lze je však načíst v režimu pouze reflexe).

Přesné referenční podrobnosti o struktuře sestavení závisí na verzi kompilátoru. Novější verze se můžou rozhodnout vyloučit další metadata, pokud se zjistí, že neovlivňují plochu veřejného rozhraní API.

Poznámka:

Informace v této části platí pouze pro referenční sestavení generovaná kompilátory Roslyn počínaje jazykem C# verze 7.1 nebo Visual Basic verze 15.3. Struktura referenčních sestavení pro knihovny .NET Framework a .NET Core se může v některých podrobnostech lišit, protože používají vlastní mechanismus generování referenčních sestavení. Mohou mít například zcela prázdné tělo metody místo throw null těla. Ale obecný princip platí i nadále: nemají použitelné implementace metod a obsahují metadata pouze pro členy, kteří mají pozorovatelný dopad z hlediska veřejného rozhraní API.

Viz také