版本控制

軟體程式庫在 1.0 版中通常還不完整。 良好的程式庫會隨著時間演進、新增功能、修正錯誤 (Bug) 並改善效能。 您必須發行新版的 .NET 程式庫，為每個版本提供額外的價值，而不會中斷現有的使用者。

重大變更

如需處理版本之間中斷性變更的相關資訊，請參閱中斷性變更。

版本號碼

.NET 程式庫有許多方式可以指定版本。 這些版本是最重要的：

NuGet 套件版本

NuGet 套件版本會顯示在 NuGet.org (Visual Studio NuGet 套件管理員) 上，並在使用套件時加入至原始程式碼。 NuGet 套件版本是使用者通常會看到的版本號碼，當他們討論他們所使用的程式庫版本時，他們會提及它。 NuGet 會使用 NuGet 套件版本，且對執行階段行為沒有影響。

<PackageVersion>1.0.0-alpha1</PackageVersion>

NuGet 套件識別碼與 NuGet 套件版本結合，可用來識別 NuGet 中的套件。 例如： Newtonsoft.Json + 11.0.2 。 帶有後置詞的套件是發行前版本套件，且具有特殊的行為，很適合用於測試。 如需詳細資訊，請參閱發行前版本套件。

因為 NuGet 套件版本是開發人員最明顯的版本，所以使用語意版本控制 (SemVer) 更新它是個不錯的主意。 SemVer 指出版本之間變更的重要性，並可協助開發人員在選擇要使用哪一個版本時，做出明智的決定。 例如，從 1.0 到 2.0 表示可能有潛在的中斷性變更。

✔️ 考慮使用 SemVer 2.0.0 來設定 NuGet 套件的版本。

✔️ 請務必在公用文件中使用 NuGet 套件版本，因為它是使用者通常會看到的版本號碼。

✔️ 請務必包含發行前版本尾碼 (當發行非穩定套件時)。

使用者必須選擇取得發行前版本套件，以便他們了解套件不完整。

組件版本

組件版本是 CLR 在執行階段使用的方式，可用於選取要載入的組件版本。 使用版本設定選取組件僅適用於具有強式名稱的組件。

<AssemblyVersion>1.0.0.0</AssemblyVersion>

.NET Framework CLR 會要求完全相符，以載入強式名稱組件。 例如，Library1, Version=1.0.0.0 編譯時參考了 Newtonsoft.Json, Version=11.0.0.0。 .NET Framework 將只會載入該確切版本 11.0.0.0。 若要在執行階段載入不同的版本，必須將繫結重新導向新增至 .NET 應用程式的設定檔中。

強式命名與組件版本相結合，可啟用嚴格的組件版本載入。 雖然為程式庫進行強式命名有很多好處，但它通常會導致無法找到組件的執行階段例外狀況，而且在 app.config 或 web.config 中要求修復繫結重新導向。 在 .NET Core 中，組件載入更為寬鬆。 .NET Core 執行階段會在執行階段自動載入具有較高版本的組件。

✔️ 考慮只在 AssemblyVersion 中包括主要版本。

例如，Library 1.0 與 Library 1.0.1 的 AssemblyVersion 都為 1.0.0.0，而 Library 2.0 的 AssemblyVersion 為 2.0.0.0。 當組件版本變更頻率較低時，它可減少繫結重新導向。

✔️ 考慮將 AssemblyVersion 與 NuGet 套件版本的主要版本號碼保持同步。

AssemblyVersion 包含在向使用者顯示的一些參考用訊息中，例如，例外狀況訊息中的組件名稱與組件限定類型名稱。 維護版本之間的關聯性，可為開發人員提供有關他們使用之版本的詳細資訊。

❌ 請勿使用固定的 AssemblyVersion。

雖然不會變更的 AssemblyVersion 避免了繫結重新導向的需要，但這表示只能在全域組件快取 (GAC) 中安裝單一版本的組件。 此外，如果另一個應用程式使用中斷性變更更新 GAC 組件，則參考 GAC 中組件的應用程式將中斷。

組件檔版本

組件檔版本用於顯示 Windows 中的檔案版本，對執行階段行為沒有影響。 是否設定此版本是選擇性的。 它會顯示在 Windows 檔案總管的 [檔案內容] 對話方塊中：

<FileVersion>11.0.2.21924</FileVersion>

✔️ 考慮包括持續整合組建編號作為 AssemblyFileVersion 修訂。

例如，您正在建置版本 1.0.0 的專案，且持續整合組建編號是 99，因此您的 AssemblyFileVersion 是 1.0.0.99。

✔️ 針對檔案版本，請使用格式 Major.Minor.Build.Revision。

雖然 .NET 永遠不會使用檔案版本，但 Windows 預期檔案版本的格式為 Major.Minor.Build.Revision。 如果版本未遵循此格式，則會引發警告。

組件資訊版本

組件資訊版本用於記錄其他版本資訊，對執行階段行為沒有影響。 是否設定此版本是選擇性的。 如果您正在使用來源連結，則此版本將在組建時使用 NuGet 套件版本加上原始檔控制版本進行設定。 例如，1.0.0-beta1+204ff0a 包括組件建置來源之原程式始碼的認可雜湊。 如需詳細資訊，請參閱來源連結。

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

注意

如果此版本未遵循 Major.Minor.Build.Revision 格式，則舊版的 Visual Studio 會引發建置警告。 您可以安心略過該警告。

❌ 避免設定您自己的組件資訊版本。

允許 SourceLink 自動產生包含 NuGet 與原始檔控制中繼資料的版本。

上一個下一個