Sdílet prostřednictvím

Referenční sestavení

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 vylučují všechny implementace členů a deklarace soukromých členů, které nemají žádný pozorovatelný dopad na kontrakt jejich 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 společ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 implementační sestavení nebo na odkazová 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íráte závislost na podrobnostech implementace.

Referenční sestavení pro knihovny rozhraní .NET Framework se distribuují s balíčky pro 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 jsou referenční sestavení automaticky podle potřeby stahována a odkazována prostřednictvím NuGet. 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 adresář. Pro .NET Core můžete vynutit, aby operace publikování zkopírovala referenční sestavení pro vaši cílovou platformu do podadresáře publish/refs ve výstupním adresáři nastavením vlastnosti projektu na PreserveCompilationContexttrue. 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 pouze pro reflexi v rozhraní .NET Framework (pomocí Assembly.ReflectionOnlyLoad metody) nebo do MetadataLoadContext v 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.

Integrovaná vývojová prostředí (IDE) a nástroje pro 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\ ve složce balíčku namísto do podadresáře lib\ určeného pro sestavení implementace.

Referenční struktura knihoven

Referenční sestavení jsou rozšířením souvisejícího konceptu, sestavení pouze s metadaty. Sestavení obsahující pouze metadata mají jejich těla metod nahrazena jediným throw null tělem, ale zahrnují všechny členy s výjimkou anonymních typů. Důvodem použití throw null těles (na rozdíl od žádných těles) je, aby PEVerify mohl běžet a uspět, čímž se ověří ú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, členy interní 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 prostředí runtime odmítne načíst referenční sestavení pro vykonání (lze je však načíst pouze v režimu 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 kódu. 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é