Verziószámozás

A szoftvertárak ritkán fejeződnek be az 1.0-s verzióban. A jó kódtárak idővel fejlődnek, funkciókkal bővülnek, kijavítják a hibákat, és javítják a teljesítményt. Fontos, hogy a .NET-kódtárak új verzióit a meglévő felhasználók feltörése nélkül is kiadhatja.

Kompatibilitástörő változások

A verziók közötti kompatibilitástörő változások kezeléséről további információt Kompatibilitástörő módosításokcímű témakörben talál.

Verziószámok

A .NET-kódtárak többféleképpen is megadhatnak verziót. Ezek a verziók a legfontosabbak:

• NuGet csomagverzió
• szerelvény verziója
• szerelvényfájl verziója
• szerelvény információs verziójának

NuGet-csomag verziója

A NuGet-csomag verziója megjelenik a NuGet.org és a Visual Studio NuGet csomagkezelőben, és a csomag használatakor hozzáadódik a forráskódhoz. A NuGet-csomag verziója az a verziószám, amelyet a felhasználók gyakran láthatnak, és hivatkozni fognak rá, amikor az általuk használt kódtár verziójáról beszélnek. A NuGet-csomag verzióját a NuGet használja, és nincs hatással a futtatókörnyezet viselkedésére.

<PackageVersion>1.0.0-alpha1</PackageVersion>

A NuGet-csomagazonosító és a NuGet-csomag verziója a NuGet-csomagok azonosítására szolgál. Például Newtonsoft.Json + 11.0.2. Az utótaggal rendelkező csomag egy előrendelési csomag, amely speciális viselkedéssel rendelkezik, így ideális teszteléshez. További információkért, lásd az előzetes csomagokat.

Mivel a NuGet-csomag verziója a fejlesztők számára a leglátogatottabb verzió, érdemes frissíteni Szemantikus verziókezelés (SemVer)használatával. A SemVer jelzi a kiadások közötti változások jelentőségét, és segít a fejlesztőknek megalapozott döntést hozni a használni kívánt verzió kiválasztásakor. Például, amikor 1.0-ról 2.0-re lépünk, az azt jelzi, hogy kompatibilitástörő változások lehetségesek.

Fontolja meg a NuGet csomag verziózásához a SemVer 2.0.0 használatát.

✔️ DO használja a NuGet-csomag verzióját a nyilvános dokumentációban, mivel ez a felhasználók által gyakran használt verziószám.

✔️ Foglalja bele az előzetes kiadásra utaló utótagot, amikor nem stabil csomagot ad ki. (További információ az API-k előzetes verzióként vagy kísérletiként való megjelöléséről: Előzetes verziójú API-k.)

A felhasználóknak be kell jelentkezniük az előzetes csomagok beszerzésébe, hogy tisztában legyenek azzal, hogy a csomag nem fejeződött be.

Szerelvény verziója

A szerelvény verziója az, amelyet a futtatási környezet (CLR) futtatási időben használ a betöltendő szerelvény verziójának kiválasztásához. Egy szerelvény verziószámozással történő kiválasztása csak erős névvel rendelkező szerelvényekre vonatkozik.

<AssemblyVersion>1.0.0.0</AssemblyVersion>

A .NET Framework CLR pontos egyezésre van szükség egy erős nevű assembly betöltéséhez. Például a Library1, Version=1.0.0.0Newtonsoft.Json, Version=11.0.0.0hivatkozással lett összeállítva. A .NET-keretrendszer csak ezt a verziót tölti be 11.0.0.0. Ha futásidőben más verziót szeretne betölteni, kötésátirányítást kell hozzáadni a .NET-alkalmazás konfigurációs fájljához.

Az erős elnevezés szerelvényverzióval kombinálva lehetővé teszi szigorú szerelvényverzió betöltését. Bár egy könyvtár erős névvel való ellátása számos előnnyel jár, gyakran vezet futásidejű kivételekhez, amikor egy assembly nem található, és kötési átirányításokatapp.config vagy web.config igényel a kijavításához. A .NET Core-ban az assemblyk betöltése lazább. A .NET (Core) futtatókörnyezet automatikusan betölti a magasabb verziójú szerelvényeket futásidőben.

✔️ VEGYE FIGYELEMBE, hogy csak egy főverziót tartalmaz a AssemblyVersion-ben.

Például a Library 1.0 és a Library 1.0.1 egyaránt rendelkezik 1.0.0.0AssemblyVersion-nel, míg a Library 2.0 a 2.0.0.0AssemblyVersion-nel rendelkezik. Amikor a szerelvény verziója ritkábban változik, csökkenti a kötés átirányítását.

✔️ FONTOLJA meg az AssemblyVersion és a NuGet-csomag főverziószámának szinkronban tartását.

Az AssemblyVersion szerepel néhány, a felhasználó számára megjelenített tájékoztató üzenetben, például a szerelvény neve és a szerelvényhez rendelt típusnevek a kivétel üzenetekben. A verziók közötti kapcsolat fenntartása további információt nyújt a fejlesztőknek arról, hogy melyik verziót használják.

❌ NE legyen rögzített AssemblyVersion.

Bár a változatlan AssemblyVersion elkerüli a kötésátirányítások szükségességét, ez azt jelenti, hogy a szerelvénynek csak egyetlen verziója telepíthető a globális szerelvénygyorsítótárban (GAC). Emellett a GAC-beli szerelvényre hivatkozó alkalmazások nem fognak működni, ha egy másik alkalmazás kompatibilitástöréseket okozó változtatásokkal frissíti a GAC-szerelvényt.

Szerelvényfájl verziója

A szerelvényfájl verziója a windowsos fájlverziók megjelenítésére szolgál, és nincs hatással a futásidejű működésre. A verzió megadása nem kötelező. Ez látható a Windows Intéző Fájltulajdonságok párbeszédpanelén:

<FileVersion>11.0.2.21924</FileVersion>

✔️ FONTOLJA meg, hogy az AssemblyFileVersion-változatként adjon meg egy folyamatos integrációs buildszámot.

Például a projekt 1.0.0-s verzióját készíti el, a folyamatos integrációs buildszám pedig 99, így a AssemblyFileVersion értéke 1.0.0.99.

✔️ A DO fájlverzióhoz használja a Major.Minor.Build.Revision formátumot.

Bár a .NET soha nem használja a fájlverziót, Windows elvárja, hogy a fájl verziójaMajor.Minor.Build.Revision formátumban legyen. Figyelmeztetés jelenik meg, ha a verzió nem követi ezt a formátumot.

Szerelvény információs verziója

A szerelvényinformációs verzió további verzióinformációk rögzítésére szolgál, és nincs hatással a futtatókörnyezet viselkedésére. A verzió megadása nem kötelező. Ha a Source Linket használja, ezt a verziót a NuGet-csomag verziójával, valamint egy forrásvezérlő verzióval állítja be a buildre. Például 1.0.0-beta1+204ff0a tartalmazza annak a forráskódnak a véglegesítési kivonatát, amelyből a szerelvény készült. További információ: Forráshivatkozás.

<InformationalVersion>The quick brown fox jumped over the lazy dog.</InformationalVersion>

❌ NE állítsa be a szerelvény információs verzióját.

Engedélyezze a SourceLink számára, hogy automatikusan létrehozza a NuGetet és a forrásvezérlő metaadatait tartalmazó verziót.