使用 MinVer 自動化 .NET 類別庫的版本號管理

TLDR

• MinVer 透過 Git Tag 自動推斷版本號，解決了傳統手動維護或複雜工具（如 GitVersion）帶來的設定失效與分支版本混亂問題。
• 若當前 Commit 有標籤，則直接採用該版本；若無標籤，則根據歷史最近標籤自動遞增 Patch 或預發佈識別碼。
• 預設版本為 0.0.0-alpha.0，並會自動加上距離標籤的 commit 數量（height）。
• 必須確保 Git 已安裝並存在於系統環境變數 PATH 中，否則會導致編譯錯誤。
• 建議避免使用過於複雜的標籤格式（如 0.0.1-alpha.0.0），以免遞增邏輯產生混亂。

---

MinVer 版本號規則

基本運作原理

MinVer 的核心邏輯完全依賴 Git 歷史記錄：

• 當前 Commit 有版本標籤：版本直接採用該標籤。
• 當前 Commit 無版本標籤：
  • 若找到歷史標籤為「預發佈版本」：直接採用該版本並加上 height（距離標籤的 commit 數量）。
  • 若找到歷史標籤為「正式版本」：自動遞增修補號（patch number），並加上預設預發佈識別碼（預設為 alpha.0）與 height。
  • 若完全找不到標籤：使用預設版本 0.0.0-alpha.0 並加上 height。

屬性值對應

MinVer 會自動將推斷出的版本號映射至以下 .NET 屬性：

屬性	值
AssemblyVersion	{MinVerMajor}.0.0.0
FileVersion	{MinVerMajor}.{MinVerMinor}.{MinVerPatch}.0
InformationalVersion	{MinVerVersion}
PackageVersion	{MinVerMajor}.{MinVerMinor}.{MinVerPatch} 或 {MinVerMajor}.{MinVerMinor}.{MinVerPatch}-{MinVerPreRelease}
Version	{MinVerMajor}.{MinVerMinor}.{MinVerPatch} 或 {MinVerMajor}.{MinVerMinor}.{MinVerPatch}-{MinVerPreRelease}

常用設定範例

在 .csproj 檔案中，可透過 PropertyGroup 進行客製化：

• 設定標籤前綴（例如習慣使用 v1.0.0）：

<PropertyGroup>
  <MinVerTagPrefix>v</MinVerTagPrefix>
</PropertyGroup>

• 自定義預發佈識別碼（例如改用 preview）：

<PropertyGroup>
  <MinVerDefaultPreReleaseIdentifiers>preview.0</MinVerDefaultPreReleaseIdentifiers>
</PropertyGroup>

---

實作範例與常見問題

什麼情況下會遇到版本號混亂？

當標籤命名格式過於複雜（例如 0.0.1-alpha.0.0）時，MinVer 在遞增時會產生如 0.0.1-alpha.0.0.1 的結果，導致版本號邏輯難以維護。

TIP

建議保持標籤格式簡潔，避免使用多層級的預發佈識別碼。

什麼情況下會遇到編譯錯誤？

若在建置專案時出現 git is not present in PATH. 錯誤，代表系統環境變數未包含 Git 路徑。

TIP

請確保 Git 已正確安裝，且在命令列輸入 git --version 可正常執行。

實作結果驗證

根據不同的 Git 狀態，MinVer 產出的版本號如下：

• 無標籤狀態：產生 0.0.0-alpha.0.1.nupkg。
• 前一個 Commit 為正式標籤 0.1.0：自動遞增為 0.1.1-alpha.0.1.nupkg。
• 前一個 Commit 為預發佈標籤 0.0.1-alpha.0：產生 0.0.1-alpha.0.1.nupkg。
• 最新 Commit 為正式標籤 0.1.2：直接採用標籤版本 0.1.2.nupkg。

---

異動歷程

1. 2025-03-29

   • 初版文件建立。