dotnet 根據基線包版本實作庫版本兼容-有解無憂

本文來告訴大家如何根據基線包版本的功能來實作自動在構建程序中，告訴開發者，當前版本是否存在不兼容舊版本的變更，其不兼容變更包括二進制中斷變更和 API 不兼容變更和源代碼中斷變更，可以讓庫開發者花更少的精力在測驗兼容性上

今天看到了隊長推送的 .NET 6新特性試用 Nuget包驗證博客，才回憶起此功能，這個功能是給庫和框架開發者使用的，用于處理多版本兼容性問題

背景

只有對一個庫或框架準備對外發布且長期維護，以及期望給其他開發者使用時，才需要考慮庫或框架的兼容性問題，越是開發底層的庫，兼容性問題就越加重要，此重要性，只有自己參與開發，踩夠坑之后，才能有所體會

換句話說，判斷一位開發者是不是庫或框架的老司機開發者，可以通過他的兼容性處理上來看出，哈哈，需要說明的是，不是所有老司機開發者都是庫或框架開發方向的，這是判斷有經驗的開發者的充分不必要條件

開始之前，先聊聊什么是兼容性問題，兼容性可以分為以下不兼容變更：

源代碼中斷變更和 API 不兼容變更：簡單說 API 不兼容變更，就是更改了開放出去的 API 簽名，對于使用了此庫或框架的開發者來說，如果更新到新的版本，為了適配變更，就必須更改源代碼
二進制中斷變更：盡管是不用更改源代碼就能適配新版本，但是如果沒有重新構建，提示替換 DLL 檔案，那將會在運行程式時掛掉，例如給某個公開的函式加上了一個默認引數，盡管默認引數的添加，在源代碼上是可以不做任何變更就可以用上新的版本，然而如果沒有重新構建，只是將新版本的 DLL 或 EXE 替換過去，在運行的時候將提示找不到方法
行為中斷變更：某個行為被更改，執行邏輯和之前不兼容，例如原本一個方法能好好作業，現在呼叫了，行程就退出了等等

此外，還有更換了底層運行時框架的變更等，但這些就不在本文討論范圍了

更多請參閱官方檔案的詳細描述：重大更改和 .NET 庫 Microsoft Docs

對于使用庫或框架的開發者來說，一方面又期望用上新版本的強大功能，另一方面又怕有不兼容的變更，需要花費大量的精力在更新上面，如果庫或框架的開發者，可以保持好兼容性，那么升級版本是一個很輕松的事情

對于咱 dotnet 系的大部分庫或框架開發者來說，在開發程序中，考慮兼容性是一個必備的選項，那如果真的需要變更 API 了呢？問題也不大，別忘了咱還有版本號規則

版本號規則

基本所有 dotnet 系上，正經的庫和框架都會遵循約定的版本號規則，從而讓開發者在使用任何庫的時候，通過版本號都能明確其中的含義，決定自己是否應該升級到最新版本

無異議的版本規則是，版本號由四個部分組成，分為 主版本號.次版本號.構建號.修訂號 四個部分，其中的構建號和修訂號都可忽略不寫，各個部分的含義如下

主版本號： major version ，此版本如有變更，如從 1 升級到 2 的版本，代表著有重大更改，如存在不兼容的 API 或源代碼更改，或者機制性，或者行為上的變更，大部分情況下，有主版本的變更就意味著需要在升級完成進行適配的作業
次版本號: minor version，此版本如有變更，代表著有新增的 API 定義或者是較大的但是兼容的修訂，如修大 Bug 等，大部分情況下是不需要進行任何的適配作業
構建號: build number，此版本如有變更，代表著有小的更改，如修 Bug 等，不改變對外公開的約定的行為，升級新版本不需要進行任何的適配作業
修訂號: revision，此版本大部分情況是給構建工具鏈撰寫的，開發者人類是很少需要變更此，升級到此新版本，無須進行任何適配

此外，有一些庫畢竟激進，需要發布預覽版本等，可以考慮采用語意版本號的方法，請看語意版本號（Semantic Versioning） - walterlv - 博客園

通過如上的說明，可以了解到，如果不想刷主版本號，那就要求庫或框架保持兼容舊版本，兼容舊版本需要在開發時，投入精力了解是否存在不兼容的更改，然而純依靠手動去閱讀代碼了解是否存在不兼容的變更，當然是不靠譜的，本文將告訴大家如何使用 EnablePackageValidation 和 PackageValidationBaselineVersion 功能，自動讓構建工具告訴開發者當前的更改是否存在不兼容的更改，從而更好保持庫或框架的兼容

使用方法

一如既往的簡單，只需要在專案檔案上，添加如下代碼即可

    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>基于的版本號</PackageValidationBaselineVersion>

例如當前是 2.0.0 的版本，期望進行對 1.0.0 包版本的兼容性測驗，可以將 PackageValidationBaselineVersion 的值更改為 1.0.0 版本，如下面代碼

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>2.0.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
  </PropertyGroup>

如此，在存在中斷性（也就是不兼容，需要代碼適配）變更時，在會在構建時給出提示，同時讓構建不通過

例子

如何更好的使用此功能，還請讓我用一個例子來告訴大家，此例子完全從官方檔案抄的

在第一個版本時，作為 1.0.2 的版本的 NuGet 包，已對外發布，在進行 1.1.0 版本開發時，期望能做到完全的兼容第一個版本，利用 PackageValidationBaselineVersion 的功能，在 csproj 專案檔案上，加上如下代碼

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>1.1.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.0.2</PackageValidationBaselineVersion>
  </PropertyGroup>

</Project>

通過在 PackageValidationBaselineVersion 執行定了基線包版本為 1.0.2 即可采用此指定的版本進行基線包版本對比，例如幾周后，你的任務是為庫添加對連接超時的支持，代碼的 Connect 方法目前如下所示：

public static HttpClient Connect(string url)
{
    // ...
}

由于連接超時是一個高級配置設定，因此你認為可以添加一個可選引數，更改如下：

public static HttpClient Connect(string url, TimeSpan timeout = default)
{
    // ...
}

更改之后，構建程序可以正常，但是在打包的時候，將會收到如下提示，打包失敗

D:\demo>dotnet pack
Microsoft (R) Build Engine version 17.0.0-preview-21460-01+8f208e609 for .NET
Copyright (C) Microsoft Corporation. All rights reserved.

  Determining projects to restore...
  All projects are up-to-date for restore.
  You are using a preview version of .NET. See: https://aka.ms/dotnet-core-preview
  PackageValidationThrough -> D:\demo\bin\Debug\net6.0\PackageValidationThrough.dll
  Successfully created package 'D:\demo\bin\Debug\PackageValidationThrough.2.0.0.nupkg'.
C:\Program Files\dotnet\sdk\6.0.100-rc.1.21463.6\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.Compatibility.Common.targets(32,5): error CP0002: Member 'A.B.Connect(string)' exists on [Baseline] lib/net6.0/PackageValidationThrough.dll but not on lib/net6.0/PackageValidationThrough.dll [D:\demo\PackageValidationThrough.csproj]

或者中文版本的提示如下

用于 .NET 的 Microsoft (R) 生成引擎版本 17.0.0-preview-21501-01+bbcce1dff
著作權所有(C) Microsoft Corporation，保留所有權利，

  正在確定要還原的專案…
  所有專案均是最新的，無法還原，
  你正在使用 .NET 的預覽版，請查看 https://aka.ms/dotnet-core-preview
  NallcearreyiHernareferkear -> C:\lindexi\NallcearreyiHernareferkear\NallcearreyiHernareferkear\bin\Debug\net6.0\NallcearreyiHernareferkear.dll
  已成功創建包“C:\lindexi\NallcearreyiHernareferkear\NallcearreyiHernareferkear\bin\Debug\NallcearreyiHernareferkear.2.0.0.nupkg”，
C:\Program Files\dotnet\sdk\6.0.100-rc.2.21505.57\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.Compatibility.Common.targets(32,5): error CP0002: Member 'NallcearreyiHernareferkear.Foo.Connect(string)' exists on [Baseline] lib/net6.0/NallcearreyiHernareferkear.dll but not on lib/net6.0/NallcearreyiHernareferkear.dll [C:\lindexi\NallcearreyiHernareferkear\NallcearreyiHernareferkear\NallcearreyiHernareferkear.csproj]

如此通過打包失敗，提示的 CP0002 失敗，可以了解到，自己沒有做到讓當前版本對寫入到 PackageValidationBaselineVersion 的兼容，此時要做的事情，要么是廢棄掉對 PackageValidationBaselineVersion 的兼容，也就是洗掉此屬性，同時升級主版本號，告訴其他開發者，當前版本存在不兼容，要么是更改 API 定義，更改到兼容

例如以上的代碼，雖然加上了一個默認引數，可以實作到源代碼兼容，但是大家都知道，這是二進制不兼容的，如果直接替換 DLL 檔案，而不經過編譯，將會在運行的程序中，因為找不到對應的方法而失敗

什么情況下會遇到沒有重新構建，只是替換 DLL 檔案而已？在于是其他底層庫的依賴參考，例如再有另一個庫 C 也參考了此，而庫 C 打出的 NuGet 包被最終專案所參考，當最終專案升級版本時，由于 Connect 方法被更改，從而讓庫 C 里面的對應邏輯找不到方法，而在運行時失敗

因此為了做到這部分的兼容，可以考慮作為多載的方法更改，更改如下

public static HttpClient Connect(string url)
{
    return Connect(url, Timeout.InfiniteTimeSpan);
}

public static HttpClient Connect(string url, TimeSpan timeout)
{
    // ...
}

這樣進行重新打包，即可看到打包成功，兼容 PackageValidationBaselineVersion 的 1.0.2 版本

原理

此功能是依托于 NuGet 包發布而拿到指定版本號規則的，和使用基于 Roslyn 的 Microsoft.CodeAnalysis.PublicApiAnalyzers 來追蹤專案的 API 改動，幫助保持庫的 API 兼容性 - walterlv 的方法是完全不相同的

本文介紹的方法，是在 PackageValidationBaselineVersion 里面，宣告的包版本，在構建程序中，通過 NuGet 去拉取對應的版本，接著通過 DLL 匯出型別的對比，從而了解是否存在不兼容的變更

也就是說在 PackageValidationBaselineVersion 里面寫入的版本號，要求是可以在 NuGet 源里面（無論是 nuget.org 源，還是你的私有的源，還是你的本機檔案夾都可以）拉到對應的版本，由此版本里面的 DLL 執行具體的對比邏輯，這也就要求了此功能只能用在簡單的 NuGet 上，對于很多上了黑科技的 NuGet 包是無法執行的，例如使用 SourceYard 打包的源代碼包

本文介紹的方法，對比使用基于 Roslyn 的 Microsoft.CodeAnalysis.PublicApiAnalyzers 來追蹤專案的 API 改動，幫助保持庫的 API 兼容性的方法來說，優勢在于不需要帶上 PublicAPI.Unshipped.txt 和 PublicAPI.Shipped.txt 檔案，此兩個檔案夾特別好在團隊開發時進行沖突，而且需要進行手動管理，但是缺點在于本文介紹的方法功能單一，也依賴 NuGet 包版本

代碼

本文以上的代碼放在github 和 gitee 歡迎訪問

可以通過如下方式獲取本文的源代碼，先創建一個空檔案夾，接著使用命令列 cd 命令進入此空檔案夾，在命令列里面輸入以下代碼，即可獲取到本文的代碼

git init
git remote add origin https://gitee.com/lindexi/lindexi_gd.git
git pull origin 95692dcaabfb0d143dffa8e31c0a1ad00e7c2e74

以上使用的是 gitee 的源，如果 gitee 不能訪問，請替換為 github 的源

git remote remove origin
git remote add origin https://github.com/lindexi/lindexi_gd.git

獲取代碼之后，進入 NallcearreyiHernareferkear 檔案夾

dotnet 根據基線包版本實作庫版本兼容

背景

版本號規則

使用方法

例子

原理

代碼

更多閱讀