Megosztás a következőn keresztül:

Referenciaszerelvények

  • Cikk

A referenciaszerelvények egy speciális szerelvénytípus, amely csak a tár nyilvános API-felületének megjelenítéséhez szükséges minimális mennyiségű metaadatot tartalmazza. Az összes olyan tagra vonatkozó deklarációkat tartalmaznak, amelyek jelentősek a szerelvény buildelési eszközökben való hivatkozásakor, de kizárnak minden olyan tagi implementációt és magántagi deklarációt, amely nem befolyásolja az API-szerződésüket. Ezzel szemben a rendszeres szerelvényeket implementációs szerelvényeknek nevezzük.

A referenciaszerelvények nem tölthetők be a végrehajtáshoz, de fordítói bemenetként ugyanúgy továbbíthatók, mint a megvalósítási szerelvények. A referenciaszerelvények általában egy adott platform vagy tár szoftverfejlesztői készletével (SDK) vannak elosztva.

A referencia-szerelvény használatával a fejlesztők olyan programokat hozhatnak létre, amelyek egy adott kódtár-verziót céloznak meg anélkül, hogy az adott verzió teljes implementációs szerelvénye rendelkezik volna. Tegyük fel, hogy csak a legújabb verziójú könyvtárat használja a számítógépen, de olyan programot szeretne létrehozni, amely a tár egy korábbi verzióját célozza meg. Ha közvetlenül az implementációs szerelvényre fordít, előfordulhat, hogy véletlenül olyan API-tagokat használ, amelyek nem érhetők el a korábbi verzióban. Ezt a hibát csak akkor találja meg, ha a programot a célgépen teszteli. Ha a korábbi verzió referencia-szerelvénye alapján fordít, azonnal fordítási időt jelző hibaüzenet jelenik meg.

A referenciaszerelvények olyan szerződéseket is jelenthetnek, vagyis olyan API-k készletét, amelyek nem felelnek meg a konkrét megvalósítási szerelvénynek. Az ilyen referenciaszerelvények, az úgynevezett szerződésszerelvények több platform megcélzására használhatók, amelyek ugyanazt az API-kat támogatják. A .NET Standard például a különböző .NET-platformok között megosztott közös API-k halmazát jelöli, netstandard.dll. Ezeknek az API-knak az implementációit különböző platformokon található különböző szerelvények tartalmazzák, például mscorlib.dll .NET-keretrendszer vagy System.Private.CoreLib.dll a .NET Core-on. A .NET Standardot támogató kódtárak a .NET Standardot támogató összes platformon futtathatók.

Referenciaszerelvények használata

Ahhoz, hogy a projekt bizonyos API-kat használjon, hivatkozásokat kell hozzáadnia a szerelvényekhez. A megvalósítási szerelvényekre vagy a referenciaszerelvényekre mutató hivatkozásokat is hozzáadhat. Javasoljuk, hogy mindig használjon referenciaszerelvényeket, amikor elérhetők. Ezzel biztosítja, hogy csak a támogatott API-tagokat használja a célverzióban, amelyeket az API-tervezőknek szántak. A referencia-szerelvény használatával gondoskodhat arról, hogy ne függjön a megvalósítás részleteihez.

A .NET-keretrendszer kódtárak referenciaszerelvényei célcsomagokkal vannak elosztva. Beszerezheti őket egy különálló telepítő letöltésével vagy a Visual Studio telepítőjének egyik összetevőjének kiválasztásával. További információ: A .NET-keretrendszer telepítése fejlesztőknek. A .NET Core és a .NET Standard esetében a referenciaszerelvények szükség szerint automatikusan letöltődnek (NuGeten keresztül), és hivatkoznak rá. A .NET Core 3.0-s és újabb verziói esetében az alapvető keretrendszer referenciaszerelvényei a Microsoft.NETCore.App.Ref csomagban találhatók (a Microsoft.NETCore.App csomag a 3.0 előtti verziókhoz használatos).

Amikor a Visual Studióban a Hivatkozás hozzáadása párbeszédpanelen .NET-keretrendszer szerelvényekre mutató hivatkozásokat ad hozzá, kiválaszt egy szerelvényt a listából, és a Visual Studio automatikusan megkeresi a projektben kiválasztott cél-keretrendszerverziónak megfelelő referenciaszerelvényeket. Ugyanez vonatkozik arra is, hogy közvetlenül az MSBuild projektbe a Referencia projektelem használatával adhat hozzá hivatkozásokat: csak a szerelvény nevét kell megadnia, nem pedig a teljes fájl elérési útját. Ha a parancssorban a fordítási lehetőséggel -reference (C# és Visual Basic) vagy a Compilation.AddReferences Roslyn API metódusával ad hozzá hivatkozásokat ezekre a szerelvényekre, manuálisan kell megadnia a referencia-szerelvényfájlokat a megfelelő célplatform-verzióhoz. .NET-keretrendszer referencia-szerelvényfájlok a %ProgramFiles(x86)%\Reference Assemblies\Microsoft\Framework\ mappában találhatók. NETFramework könyvtár. A .NET Core esetében kényszerítheti a közzétételi műveletet a célplatform referenciaszerelvényeinek másolására a kimeneti könyvtár közzétételi/refs alkönyvtárába a PreserveCompilationContext projekttulajdonság truebeállításával. Ezután átadhatja ezeket a referencia-szerelvényfájlokat a fordítónak. A Microsoft.Extensions.DependencyModel csomag használatával DependencyContext megkeresheti az elérési útjukat.

Mivel nem tartalmaznak implementációt, a referenciaszerelvények nem tölthetők be végrehajtásra. Ha ezt megkísérli, az eredmény egy System.BadImageFormatException. Ha meg szeretné vizsgálni egy referenciaszerelvény tartalmát, betöltheti azt a csak tükröződési környezetbe a .NET-keretrendszer (a Assembly.ReflectionOnlyLoad metódus használatával), vagy a .NET-ben és a MetadataLoadContext .NET-keretrendszer.

Referenciaszerelvények létrehozása

A kódtárak referenciaszerelvényeinek létrehozása akkor lehet hasznos, ha a tár felhasználóinak a kódtár számos különböző verziójához kell összeállítaniuk a programjaikat. A megvalósítási szerelvények elosztása ezekhez a verziókhoz nagy méretük miatt nem praktikus. A referencia-szerelvények kisebb méretűek, és a tár SDK részeként történő elosztása csökkenti a letöltés méretét, és lemezterületet takarít meg.

Az IDE-k és a buildelési eszközök a referenciaszerelvények előnyeit is kihasználva csökkenthetik az összeállítási időt több osztálykódtárból álló nagy megoldások esetén. Növekményes buildelési forgatókönyvekben a projekt általában újraépül, amikor a bemeneti fájlok bármelyike megváltozik, beleértve azokat a szerelvényeket is, amelyektől függ. A megvalósítási szerelvény akkor változik, amikor a programozó módosítja bármely tag implementációját. A referencia-szerelvény csak akkor változik, ha a nyilvános API-t érinti. Így a referencia-szerelvény bemeneti fájlként való használata a megvalósítási szerelvény helyett lehetővé teszi a függő projekt buildjének kihagyását bizonyos esetekben.

Referenciaszerelvényeket hozhat létre:

Ha NuGet-csomagokkal szeretné terjeszteni a referencia-szerelvényeket, azokat a ref\ alkönyvtárban kell elhelyeznie a csomagkönyvtár alatt, nem pedig a implementálási szerelvényekhez használt lib\ alkönyvtárban.

Referenciaszerelvények felépítése

A referenciaszerelvények a kapcsolódó fogalom, a csak metaadatokkal rendelkező szerelvények kibővítése. A csak metaadat-összeállítások metódustesteit egyetlen throw null törzsre cserélik, de a névtelen típusok kivételével minden tagot magukban foglalnak. A testek használatának throw null oka (szemben a testekkel) az, hogy a PEVerify futhat és továbbítható (így érvényesítheti a metaadatok teljességét).

A referenciaszerelvények tovább távolítják el a metaadatokat (magántagokat) a csak metaadat-szerelvényekből:

  • A referenciaszerelvények csak az API-felületen igényelnek referenciákat. A valós szerelvény további hivatkozásokkal rendelkezhet az egyes implementációkhoz. A referenciaszerelvény class C { private void M() { dynamic d = 1; ... } } például nem hivatkozik a szükséges típusokra dynamic.
  • A privát függvénytagok (metódusok, tulajdonságok és események) törlődnek olyan esetekben, amikor eltávolításuk nem befolyásolja a fordítást. Ha nincsenek InternalsVisibleTo attribútumok, a belső függvénytagok is törlődnek.

A referencia-szerelvények metaadatai továbbra is a következő információkat őrzik meg:

  • Minden típus, beleértve a privát és a beágyazott típusokat is.
  • Minden attribútum, még a belső is.
  • Minden virtuális módszer.
  • Explicit felületi implementációk.
  • Kifejezetten implementált tulajdonságok és események, mivel a tartozékaik virtuálisak.
  • Minden struktúramező.

A referenciaszerelvények tartalmazzák a szerelvényszintű ReferenceAssembly attribútumot. Ez az attribútum megadható a forrásban; akkor a fordítónak nem kell szintetizálnia. Emiatt az attribútum miatt a futtatókörnyezetek nem fogják betölteni a referenciális szerelvényeket a végrehajtáshoz (de csak tükröződés módban tölthetők be).

A referencia-szerelvény szerkezetének pontos részletei a fordító verziójától függenek. Az újabb verziók dönthetnek úgy, hogy kizárnak további metaadatokat, ha úgy vannak meghatározva, hogy az nem érinti a nyilvános API-felületet.

Feljegyzés

Az ebben a szakaszban található információk csak a Roslyn fordítói által a C# 7.1-es vagy a Visual Basic 15.3-os verziójából létrehozott referenciaszerelvényekre vonatkoznak. A .NET-keretrendszer és a .NET Core-kódtárak referenciaszerelvényeinek szerkezete bizonyos részletekben eltérhet, mivel a referenciaszerelvények létrehozásának saját mechanizmusát használják. Előfordulhat például, hogy teljesen üres metódustestek vannak a throw null törzs helyett. Az általános alapelv azonban továbbra is érvényes: nem rendelkeznek használható metódus-implementációkkal, és csak olyan tagok metaadatait tartalmazzák, akiknek a nyilvános API szempontjából megfigyelhető hatása van.

Lásd még