MS_NuGetPrerelease

NuGetパッケージのプレリリース版

• 戻る（NuGet）
  • NuGet を使用したパッケージ管理
  • NuGetパッケージの開発と公開
    • NuGetプライベート・リポジトリ
    • NuGetパッケージのデバッグ
    • NuGetパッケージのプレリリース版

概要

NuGet 登録したビルドに問題があり、0n-0n（n.n.0）リリースが、
早速、n.n.0 -> n.n.1 -> n.n.2 となってしまうなどの問題に対する対応。

補足（この問題意識）: 「出してみたら壊れていたので、
すぐ次の版を出す羽目になる」——という、
公開してしまった版は取り消せないことに起因する問題である。

NuGet では、一度公開したバージョンは再利用できない
（同じ版番号で内容を差し替えることはできず、
unlist しても既存の参照からは解決され続ける）。

【プレリリースを使わない】
   1.2.0 公開 → 不具合 → 1.2.1 → また不具合 → 1.2.2 …
     → 安定版の履歴が「壊れた版」で埋まる

【プレリリースを使う】
   1.2.0-alpha.1 → -alpha.2 → -beta.1 → -rc.1 → 1.2.0
     → 安定版は 1.2.0 の 1 つだけ

つまり、版番号の空間を「試行用」と「正式」に分けるのが
プレリリースの本質的な役割である。

詳細

リリース作業は「-alpha、-beta、-preview、-rc」などの

「Semantic Versioning 2.0.0」
「セマンティック バージョン管理サフィックス」

でやって、後で、Grep & Replace で

• .NET Framework

  • package.config の PackageVersion 値
  • Project ファイルの
    • PackageVersion 値（Package Reference の場合）
    • NuGet 参照の HintPath に含まれる PackageVersion 値

• .NET Core
  Project ファイルの PackageVersion 値だけでスッキリ

を置き換える手順が良さそう。

補足（現在は Grep & Replace が不要になった／最新化）: 原文が
「後で Grep & Replace」と言っているのは、
版番号が複数箇所に散らばるためである。
現在はこれを解消する仕組みが 2 つ用意されている。

① 中央パッケージ管理（Central Package Management、NuGet 6.2+）

リポジトリのルートに Directory.Packages.props を置き、
版番号をそこ 1 箇所に集約する。

<!-- Directory.Packages.props（リポジトリ ルート） -->
<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <PackageVersion Include="MyCompany.Common" Version="1.2.0-beta.1" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.3" />
  </ItemGroup>
</Project>

<!-- 各 .csproj は版を書かない -->
<PackageReference Include="MyCompany.Common" />

プレリリースから正式版への切り替えが 1 行の修正で済むため、
原文の手順（Grep & Replace）はそのまま不要になる。

② Directory.Build.props による発行側の版の集約

発行するパッケージ側の版も、1 箇所で決められる。

<Project>
  <PropertyGroup>
    <VersionPrefix>1.2.0</VersionPrefix>
    <VersionSuffix Condition="'$(VersionSuffix)'==''">beta.1</VersionSuffix>
  </PropertyGroup>
</Project>

# CI では引数で上書きできる
dotnet pack -p:VersionSuffix=beta.$(Build.BuildId)
dotnet pack -p:VersionSuffix=            # 空にすれば正式版 1.2.0

packages.config（.NET Framework）は依然として
版が複数箇所に散るため、原文の指摘は当該方式では現在も有効である
（移行すれば解消する。
NuGet を使用したパッケージ管理 参照）。

プレリリースの種類

alpha:

• アルファ リリース。
• 一般的に、進行中の製品または実験に使用される。

beta:

• ベータ リリース。
• 次に計画されているリリースの機能をすべて利用できるが、
  既知のバグが含まれている可能性があります。

rc:

• リリース候補。
• 一般的に、重大なバグが現れない限り、
  最終版 (安定版) となる可能性があるリリース。

補足（サフィックスは自由文字列）: SemVer 2.0.0 では、
プレリリース識別子は 英数字とハイフンからなる任意の文字列であり、
alpha / beta / rc は慣習にすぎない。

.NET のエコシステムでよく見るものを補っておく。

サフィックス	使われ方
-alpha / -beta / -rc	一般的な段階表現
-preview.N	Microsoft の公式パッケージが採用（8.0.0-preview.7）
-rtm	出荷版直前（現在は -rc に統一される傾向）
-ci.YYYYMMDD.N	CI が自動採番する日次ビルド
-pr.123	プル リクエストごとのビルド

CI での自動採番が実務では重要で、
ビルドのたびに一意な版を発行することで
「どのビルドを試したか」を追跡できる。

dotnet pack -p:VersionSuffix=ci.$(date +%Y%m%d).$BUILD_ID

Example:

「セマンティック バージョン管理サフィックス」を持つ、
プレリリース版は通常版よりも優先順位が低くなり、
識別子は ASCII のソートの逆順で優先順序を与えます。

• 1.0.0-alpha ... 優先順が低い
• < 1.0.0-alpha.1
• < 1.0.0-alpha.beta
• < 1.0.0-beta
• < 1.0.0-beta.2
• < 1.0.0-beta.11
• < 1.0.0-rc.1
• < 1.0.0 ... 優先順が高い

移行メモ（「ASCII のソートの逆順」）: 原文のこの表現は
やや不正確なので補足する。
SemVer 2.0.0 の比較規則は次の通り。

1. プレリリース付きは、無しより常に小さい（1.0.0-rc.1 < 1.0.0）
2. プレリリース同士は、ドット区切りの識別子を左から順に比較する
3. 数値のみの識別子は数値として比較（beta.2 < beta.11）
4. 数値以外を含む識別子は ASCII 順（辞書順）で比較
5. 数値のみ < 数値以外（alpha.1 < alpha.beta）
6. 識別子の個数が少ない方が小さい（alpha < alpha.1）

1.0.0-alpha  <  1.0.0-alpha.1  <  1.0.0-alpha.beta
             ↑ ⑥               ↑ ⑤
  <  1.0.0-beta  <  1.0.0-beta.2  <  1.0.0-beta.11
                                  ↑ ③（辞書順なら 11 < 2 になってしまう）
  <  1.0.0-rc.1  <  1.0.0
                 ↑ ①

③ が実務上最も重要で、
beta.2 と beta.11 を正しく並べるには
beta.11 のようにドットで区切って数値にする必要がある
（beta11 と書くと文字列比較になり、beta11 < beta2 になってしまう）。

つまり、-alpha → -beta → -rc という順序が
「たまたま辞書順で正しく並ぶ」ため慣習として定着した、
というのが実情である。

補足（取得側の指定方法）: プレリリース版は
既定では取得されない（安定版のみが対象）。

# 明示的にプレリリースを許可する
dotnet add package MyLib --prerelease
dotnet add package MyLib --version 1.2.0-beta.1

<!-- 範囲指定でプレリリースを含める -->
<PackageReference Include="MyLib" Version="[1.2.0-alpha,2.0.0)" />

Visual Studio の NuGet パッケージ マネージャー UI では
「プレリリースを含める」チェック ボックスにあたる。

注意: Version="1.2.*" のような浮動バージョンに
プレリリースが混じると、意図せず不安定版が入ることがある。
本番向けの依存は版を固定するのが安全である。

参考

• NuGet パッケージのプレリリース バージョン
  https://learn.microsoft.com/ja-jp/nuget/create-packages/prerelease-packages
  • Semantic Versioning 2.0.0 | Semantic Versioning
    https://semver.org/spec/v2.0.0.html

Microsoft Learn

• パッケージのバージョン管理
  https://learn.microsoft.com/ja-jp/nuget/concepts/package-versioning
• 中央パッケージ管理（Central Package Management）
  https://learn.microsoft.com/ja-jp/nuget/consume-packages/central-package-management

---

Tags: 移行, .NET開発, デプロイ, NuGet