nuget-manager

NuGet Manager

概觀

此技能確保在 .NET 專案中一致且安全地管理 NuGet 套件。它優先使用 dotnet CLI 以維護專案完整性，並對版本更新強制執行嚴格的驗證與還原工作流程。

先決條件

• 已安裝 .NET SDK（通常為 .NET 8.0 SDK 或更新版本，或與目標方案相容的版本）。
• dotnet CLI 可在 PATH 中使用。
• jq（JSON 處理器）或 PowerShell（用於使用 dotnet package search 進行版本驗證）。

核心規則

1. 絕對不要直接編輯 .csproj、.props 或 Directory.Packages.props 檔案來新增或移除套件。一律使用 dotnet add package 和 dotnet remove package 命令。
2. 直接編輯僅允許用於變更現有套件的版本。
3. 版本更新必須遵循強制工作流程：
   • 驗證目標版本存在於 NuGet 上。
   • 判斷版本是依專案管理（.csproj）還是集中管理（Directory.Packages.props）。
   • 在適當的檔案中更新版本字串。
   • 立即執行 dotnet restore 以驗證相容性。

工作流程

新增套件

使用 dotnet add [<PROJECT>] package <PACKAGE_NAME> [--version <VERSION>]。
範例：dotnet add src/MyProject/MyProject.csproj package Newtonsoft.Json

移除套件

使用 dotnet remove [<PROJECT>] package <PACKAGE_NAME>。
範例：dotnet remove src/MyProject/MyProject.csproj package Newtonsoft.Json

更新套件版本

更新版本時，請遵循以下步驟：

1. 驗證版本存在：
   使用 dotnet package search 命令搭配完全比對與 JSON 格式來檢查版本是否存在。
   使用 jq：
   dotnet package search <PACKAGE_NAME> --exact-match --format json | jq -e '.searchResult[].packages[] | select(.version == "<VERSION>")'
   使用 PowerShell：
   (dotnet package search <PACKAGE_NAME> --exact-match --format json | ConvertFrom-Json).searchResult.packages | Where-Object { $_.version -eq "<VERSION>" }

2. 判斷版本管理方式：

   • 在方案根目錄中搜尋 Directory.Packages.props。如果存在，則應透過 <PackageVersion Include="Package.Name" Version="1.2.3" /> 在此處管理版本。
   • 如果不存在，請檢查個別 .csproj 檔案中的 <PackageReference Include="Package.Name" Version="1.2.3" />。

3. 套用變更：
   修改識別出的檔案，更新版本字串。

4. 驗證穩定性：
   對專案或方案執行 dotnet restore。如果發生錯誤，請還原變更並調查原因。

範例

使用者：「將 Serilog 新增至 WebApi 專案」

動作：執行 dotnet add src/WebApi/WebApi.csproj package Serilog。

使用者：「將整個方案中的 Newtonsoft.Json 更新為 13.0.3」

動作：

1. 驗證 13.0.3 存在：dotnet package search Newtonsoft.Json --exact-match --format json（並解析輸出以確認「13.0.3」存在）。
2. 找到定義位置（例如 Directory.Packages.props）。
3. 編輯檔案以更新版本。
4. 執行 dotnet restore。