套件來源對應

套件來源對應是一種工具，可用來改善供應鏈安全性，特別是當您混合使用公用和私人套件來源時。

根據預設，NuGet 會在需要下載套件時搜尋所有已設定的套件來源。 當套件存在於多個來源上時，可能無法確定要從哪個來源下載套件。 使用套件來源對應，您可以篩選每個套件，其中source（s） NuGet 將會搜尋。

我們也提供其他 最佳做法 的建議，可協助您強化供應鏈抵禦攻擊。

NuGet 6.0 中已新增套件來源對應。 從 Visual Studio 17.5 開始，您可以使用 Visual Studio 選項對話方塊來新增和移除套件來源對應。

Visual Studio 支援

Visual Studio	套件來源對應	工具中的支援 -> 選項	封裝管理員 UI 中的支援
17.0 - 17.4	✅可用	❌ 無法使用	❌ 無法使用
17.5	✅可用	✅可用	❌ 無法使用
17.7 預覽版 3	✅可用	✅可用	✅ 顯示的狀態

此功能適用於所有 NuGet 整合式工具。

• Visual Studio 2022 和更新版本
• .NET SDK 6.0.100 和更新版本
• nuget.exe 6.0.0 和更新版本

較舊的工具將會忽略套件來源對應設定。 若要使用這項功能，請確定您的所有建置環境都使用相容的工具版本。

只要使用相容的工具，套件來源對應就會套用至所有項目類型，包括 .NET Framework。

影片逐步解說

如需套件來源對應功能的影片型概觀，請考慮在 YouTube上觀看使用套件來源對應 影片保護 NuGet 套件。

啟用套件來源對應

若要加入加入這項功能，您必須有檔案 nuget.config 。 在存放庫的根目錄中擁有單 nuget.config 一，會被視為最佳做法。 若要深入瞭解，請參閱 nuget.config 檔 。

使用 Visual Studio 選項對話框啟用

1. 在 Visual Studio 中開啟您的方案。
2. 瀏覽至 [ Package Source Mappings 選項] 對話框。

從 封裝管理員 UI

• 從清單中選取套件，以顯示在 [詳細資料] 窗格中。
• 按下按鈕以開啟 [ Configure 封裝來源對應] 選項頁面。

從 Visual Studio 選項對話方塊

• 移至 Tools 主要 Visual Studio 工具列中的功能表，然後選擇 NuGet Package Manager ->Package Manager Settings。
• 瀏覽至 Package Source Mappings 頁面。

3. 按下頁面中的AddPackage Source Mappings按鈕以開啟Add Package Source Mappings對話框。

4.輸入套件標識碼或套件模式，然後切換所需來源的複選框來選取一或多個套件來源。

5. 選項 Package Source Mapping 頁面會顯示新建立的來源對應。

6. 按 OK [選項] 對話框，將變更儲存至適用的 nuget.config。
7. [NuGet 封裝管理員] 視窗會重新整理並反映所選套件來源對應的新狀態。

手動編輯來啟用 nuget.config

• 在檔案中 nuget.config 宣告所需的套件來源。
• 在來源宣告之後，新增 <packageSourceMapping> 元素，指定每個來源所需的對應。
• 針對使用中的每個來源，宣告一個 packageSource 元素。
  • 視需要新增多個模式。

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <!-- Define the package sources, nuget.org and contoso.com. -->
  <!-- `clear` ensures no additional sources are inherited from another config file. -->
  <packageSources>
    <clear />
    <!-- `key` can be any identifier for your source. -->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso.com" value="https://contoso.com/packages/" />
  </packageSources>
  
  <!-- Define mappings by adding package patterns beneath the target source. -->
  <!-- Contoso.* packages and NuGet.Common will be restored from contoso.com,
       everything else from nuget.org. -->
  <packageSourceMapping>
    <!-- key value for <packageSource> should match key values from <packageSources> element -->
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso.com">
      <package pattern="Contoso.*" />
      <package pattern="NuGet.Common" />
    </packageSource>
  </packageSourceMapping>
</configuration>

當不同層級的多個nuget.config檔案（計算機層級、用戶層級、存放庫層級）存在時，會套用套件來源對應設定，以遵循 nuget.config 優先順序規則。

套件來源對應規則

為了獲得最大的彈性和控制，NuGet 要求所有套件都透過妥善定義的優先順序來比對套件模式。

套件模式需求

所有要求的套件都必須比對已定義的套件模式來對應至一或多個來源。 換句話說，一旦您定義元素packageSourceMapping之後，您必須明確定義每個套件的來源，包括可轉移的套件，將會從中還原。

• 最上層 和可轉移的 套件都必須符合定義的模式。 不需要最上層套件及其相依性來自相同的來源。
• 您可以在多個來源上定義相同的標識碼模式，以便從任何定義模式的摘要還原相符的套件識別碼。 不過，不建議這麼做，因為對還原可預測性的影響（指定的套件可能來自多個來源）。 如果您信任所有個別來源，這可能是有效的組態。

套件模式語法

模式	範例語法	描述
套件前置詞模式	*, NuGet.*	結尾 *必須是 ，其中 * 符合 0 或多個字元。 * 是最短允許的前置詞模式，且符合所有套件標識符。
套件標識碼模式	NuGet.Common, Contoso.Contracts	確切的套件標識碼。

套件模式優先順序

當多個唯一模式符合套件標識符時，會優先使用最特定的模式。 套件標識碼模式一律具有最高的優先順序，而泛型 * 一律具有最低優先順序。 對於套件前置詞模式，最長的優先順序為 。

設定預設來源

模式 * 可用來宣告非事實的預設來源 -- 這表示任何不符合其他指定模式的套件都會從該來源還原，而不會擲回錯誤。 如果您主要使用 來自的套件， nuget.org而且只有少數內部套件，或針對像是 Contoso.*的所有內部套件使用標準前置詞，則此組態相當有利。

如果您的小組在安裝之前未針對內部套件標識碼或審查 nuget.org 套件使用標準前置詞，則讓私人來源成為預設值會更符合您的需求。

注意

當要求的套件已存在於全域套件資料夾中時，將不會發生任何來源查閱，而且將會忽略對應。 請考慮宣告存放庫的全域套件資料夾，以取得此功能的完整安全性優點。 請針對下一個反覆專案，改善中預設全域套件資料夾的體驗。 若要深入瞭解套件安裝的運作方式，請參閱 概念檔。

開始使用

有 2 種方式可讓您完全將存放庫上線、 手動 或使用 NuGet.PackageSourceMapper 工具。

手動上線

針對手動上線，您可以採取下列步驟：

1. 宣告存放庫的新全域套件資料夾。
2. 執行 dotnet restore 以還原 相依性。
3. 執行 dotnet list package --include-transitive 以檢視解決方案中的所有最上層和可轉移套件。
   • 對於使用 packages.config的 .NET Framework 專案，檔案 packages.config 會有所有直接和可轉移套件的一般清單。
4. 定義對應，讓解決方案中的每個套件識別碼都符合目標來源的模式， 包括可轉移的套件 。
5. 執行 dotnet nuget locals global-packages -c 以清除 global-packages 目錄。
6. 執行還原來驗證您已正確設定對應。 如果您的對應未完全涵蓋解決方案中的每個套件識別碼，錯誤訊息將協助您識別問題。
7. 還原成功時，您已完成！ 選擇性地考慮：
   • 使用更廣泛的套件標識碼前置詞或 盡可能設定預設來源 ，將組態簡化為較少的宣告。
   • 檢查全域套件資料夾中的 元數據檔案，或檢閱還原記錄，確認每個套件的來源已從還原。

使用工具自動上線

許多存放庫都有大量的套件，而且手動執行工作可能很耗時。 NuGet.PackageSourceMapper 工具可以根據專案的已知套件和來源自動為您產生 NuGet.config。

套件來源對應程式工具會要求您完成成功的套件還原，其中會讀取組建中產生的每個個別 .nupkg.metadata 檔案，以充分了解對應個別套件和來源的方式。 工具不僅涵蓋最上層相依性，也會在產生對應時考慮所有可轉移的相依性。

工具有數個選項如何根據您的需求產生對應模式，請參閱 部落格文章 和工具的 自述檔指示 ，以取得詳細數據。

如需來源對應外觀的概念，請參閱我們的 範例存放庫。

注意

• 沒有用於管理套件來源對應設定的nuget.exe或dotnet.exe命令，請參閱 NuGet/Home#10735。
• 套件安裝期間沒有任何對應套件的方法，請參閱 NuGet/Home#10730。
• 使用 DotNetCoreCLI@2 Azure Pipelines 工作時有一個限制，您可以使用 feed- 來源對應組態中的前置詞來處理。 不過，建議您針對驗證需求使用 NuGetAuthenticate ，並直接從腳本工作呼叫 dotnet cli。 請參閱 microsoft/azure-pipelines-tasks#15542。