`nuget.config` 參考

發行項
02/02/2023

NuGet 行為是由不同 NuGet.Config 或 nuget.config 檔案中的設定所控制，如一般 NuGet 組態中所述。

nuget.config 是包含最上層 <configuration> 節點的 XML 檔案，該節點則包含本主題中所述的區段項目。每個區段都包含零個或多個專案。請參閱設定檔範例。設定名稱會區分大小寫，而且值可以使用環境變數。

提示

nuget.config在專案存放庫的根目錄中新增檔案。這被視為最佳做法，因為它會提升可重複性，並確保不同的使用者具有相同的 NuGet 設定。您可能需要設定 clear 元素，以確保不會套用任何使用者或電腦特定的設定。深入瞭解如何套用設定。

config 區段

包含其他組態設定，可使用命令進行nuget config設定。

dependencyVersion 和 repositoryPath 僅適用于使用 packages.config 的專案。 globalPackagesFolder 僅適用于使用 PackageReference 格式的專案。

Key	值
dependencyVersion (僅 `packages.config`)	當未直接指定 `-DependencyVersion` 參數時，套件安裝、還原及更新的預設 `DependencyVersion` 值。 NuGet 套件管理員 UI 也使用此值。值為 `Lowest`、`HighestPatch`、`HighestMinor`、`Highest`。
globalPackagesFolder (僅使用 PackageReference 的專案)	預設全域套件資料夾的位置。預設值為 `%userprofile%\.nuget\packages` (Windows) 或 `~/.nuget/packages` (Mac/Linux)。相對路徑可用於專案特有的 `nuget.config` 檔案。此設定會由優先順序的 `NUGET_PACKAGES` 環境變數覆寫。
repositoryPath (僅 `packages.config`)	要在其中安裝 NuGet 套件的位置，而非預設 `$(Solutiondir)/packages` 資料夾。相對路徑可用於專案特有的 `nuget.config` 檔案。
defaultPushSource	識別在找不到任何其他套件來源可進行作業時，應該作為預設值使用的套件來源 URL 或路徑。
http_proxy http_proxy.user http_proxy.password no_proxy	連線到套件來源時使用的 Proxy 設定；`http_proxy` 應該為 `http://<username>:<password>@<domain>` 格式。密碼會加密，且無法手動新增。對於 `no_proxy`，值是會略過 Proxy 伺服器的網域清單，並以逗號分隔。您可以為那些值選擇使用 http_proxy 及 no_proxy 環境變數。如需詳細資料，請參閱 NuGet proxy settings (NuGet proxy 設定) (skolima.blogspot.com)。
maxHttpRequestsPerSource	控制從 NuGet 傳送至每個套件來源的平行要求數目上限，以進行套件相依性解析和下載。上的 `dotnet.exeInt32.MaxValue` 預設值是從屬性衍生而來 `HttpClientHandler.MaxConnectionsPerServer` 。此設定不會影響 `dotnet.exeMac OS` ，因為節流限制設定為 `16` ，以避免發生太多開啟的檔案錯誤。在上執行的預設值 `NuGet client tools` ，例如 `Visual Studio` ，且 `nuget.exe` 位於 `64Windows` 和 `1` 上 `Mono` 。 `.NET Framework` 樣式專案的預設值 `Packages.config` 會設定為 `Environment.ProcessorCount` 。將屬性設定 `maxHttpRequestsPerSource` 為小於預設值的值可能會影響 NuGet 效能。
signatureValidationMode	指定用來驗證套件安裝及還原套件簽章的驗證模式。 `accept`值為、 `require` 。預設值為 `accept`。

範例：

<config>
    <add key="dependencyVersion" value="Highest" />
    <add key="globalPackagesFolder" value="c:\packages" />
    <add key="repositoryPath" value="c:\installed_packages" />
    <add key="http_proxy" value="http://company-squid:3128@contoso.com" />
    <add key="signatureValidationMode" value="require" />
    <add key="maxHttpRequestsPerSource" value="16" />
</config>

bindingRedirects 區段

設定 NuGet 在安裝套件時，是否自動繫結重新導向。

Key	值
skip	布林值，指出是否略過自動繫結重新導向。預設值為 false。

範例：

<bindingRedirects>
    <add key="skip" value="True" />
</bindingRedirects>

packageRestore 區段

控制建置期間的套件還原。

Key	值
已啟用	布林值，指出 NuGet 是否可以執行自動還原。您也可以使用 `True` 值來設定 `EnableNuGetPackageRestore` 環境變數，而不是在設定檔中設定此金鑰。
automatic	布林值，指出 NuGet 是否應該在建置期間檢查遺漏的套件。

範例：

<packageRestore>
    <add key="enabled" value="true" />
    <add key="automatic" value="true" />
</packageRestore>

solution 區段

控制解決方案的 packages 資料夾是否會包含在原始檔控制。本區段只適用於解決方案資料夾中的 nuget.config 檔。

Key	值
disableSourceControlIntegration	布林值，指出當使用原始檔控制時是否要忽略 packages 資料夾。預設值為 false。

範例：

<solution>
    <add key="disableSourceControlIntegration" value="true" />
</solution>

套件來源區段

packageSources、 packageSourceCredentials 、 apikeys 、 activePackageSource 、 disabledPackageSourcestrustedSigners 和 packageSourceMapping 全都會一起運作，以設定 NuGet 在安裝、還原和更新作業期間如何與套件存放庫搭配運作。

命令 nuget sources通常用來管理這些設定，除了 apikeys 使用nuget setapikey 命令管理，以及 trustedSigners 使用命令來管理的nuget trusted-signers 設定。

請注意，nuget.org 的來源 URL 是 https://api.nuget.org/v3/index.json。

packageSources

列出所有已知的套件來源。還原作業期間以及任何使用 PackageReference 格式的專案都會忽略順序。 NuGet 會遵循使用來安裝及更新專案 packages.config 之作業的來源順序。

Key	值	protocolVersion
(要指派給套件來源的名稱)	套件來源的路徑或 URL。	要使用的 NuGet 伺服器通訊協定版本。目前的版本為「3」。當未指向以 (結尾 `.json` 的套件來源 URL 時，預設為版本「2」，例如 https://api.nuget.org/v3/index.json) 。 NuGet 3.0+支援。如需第 3 版通訊協定的詳細資訊，請參閱 NuGet 伺服器 API 。

範例：

<packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="Contoso" value="https://contoso.com/packages/" />
    <add key="Test Source" value="c:\packages" />
</packageSources>

提示

指定節點具有 <clear /> 時，NuGet 會忽略先前針對該節點所定義的組態值。深入瞭解如何套用設定。

packageSourceCredentials

儲存來源的使用者名稱和密碼，通常使用 nuget sources 的 -username 和 -password 參數來指定。依預設會加密密碼，除非同時使用了 -storepasswordincleartext 選項。您可以選擇性地使用 -validauthenticationtypes 參數來指定有效的驗證類型。

Key	值
username	純文字的來源使用者名稱。
密碼	加密的來源密碼。只有在 Windows 上才支援加密密碼，而且只能在相同電腦上使用時，以及透過與原始加密相同的使用者解密。
cleartextpassword	未加密的來源密碼。注意：環境變數可用來改善安全性。
validauthenticationtypes	此來源的有效驗證類型逗號分隔清單。如果伺服器公告 NTLM 或 Negotiate，而且必須使用基本機制傳送認證，例如，搭配內部部署Azure DevOps Server使用 PAT 時，請將此 `basic` 設定為。其他有效值包括 `negotiate` 、 `kerberos` 、 `ntlm` 、和 `digest` ，但這些值不太可能很有用。

提示

如果傳遞 password 了非加密的密碼，錯誤訊息「參數不正確」就會發生。

範例︰

設定檔中，<packageSourceCredentials> 項目包含每個適用來源名稱的子節點 (名稱中的空格會取代為 _x0020_)。也就是說，對於名為 "Contoso" 和 "Test Source" 的來源，在使用加密的密碼時設定檔時包含下列內容：

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="Password" value="..." />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="Password" value="..." />
    </Test_x0020_Source>
</packageSourceCredentials>

使用儲存在環境變數中的未加密密碼時：

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="ClearTextPassword" value="%ContosoPassword%" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="ClearTextPassword" value="%TestSourcePassword%" />
    </Test_x0020_Source>
</packageSourceCredentials>

使用未加密的密碼時：

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="ClearTextPassword" value="33f!!lloppa" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="ClearTextPassword" value="hal+9ooo_da!sY" />
    </Test_x0020_Source>
</packageSourceCredentials>

此外，也可以提供有效的驗證方法：

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="user@contoso.com" />
        <add key="Password" value="..." />
        <add key="ValidAuthenticationTypes" value="basic" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="ClearTextPassword" value="hal+9ooo_da!sY" />
        <add key="ValidAuthenticationTypes" value="basic, negotiate" />
    </Test_x0020_Source>
</packageSourceCredentials>

apikeys

儲存使用 API 金鑰驗證的來源金鑰，如命令所nuget setapikey設定。

Key	值
(來源 URL)	加密的 API 金鑰。

範例：

<apikeys>
    <add key="https://MyRepo/ES/api/v2/package" value="encrypted_api_key" />
</apikeys>

disabledPackageSources

識別目前已停用的來源。可以是空的。除非本節中停用特定來源，否則會啟用它們。

Key	值
(來源名稱)	布林值，指出是否停用來源。

範例︰

<disabledPackageSources>
    <add key="Contoso" value="true" />
</disabledPackageSources>

<!-- Empty list -->
<disabledPackageSources />

在上述範例中，套件來源 Contoso 已停用，且不會用來下載或安裝套件。

activePackageSource

(僅 2.x，在 3.x+ 中已被取代)

識別目前作用中的來源，或表示所有來源的彙總。

Key	值
(來源名稱) 或 `All`	如果金鑰是來源的名稱，則值是來源路徑或 URL。若為 `All`，值應該是 `(Aggregate source)` 以結合未以其他方式停用的所有套件來源。

範例：

<activePackageSource>
    <!-- Only one active source-->
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />

    <!-- All non-disabled sources are active -->
    <add key="All" value="(Aggregate source)" />
</activePackageSource>

trustedSigners 區段

儲存用來在安裝或還原時允許封裝的信任簽署者。當使用者設定 signatureValidationMode 為 require 時，此清單不能是空的。

您可以使用命令來更新nuget trusted-signers此區段。

結構描述：

信任的簽署者具有一組專案集合 certificate ，可列出所有識別指定簽署者的憑證。受信任的簽署者可以是 Author 或 Repository 。

信任的存放庫也會指定 serviceIndex 存放庫 (必須是有效的 https uri) ，而且可以選擇性地指定的分號分隔清單 owners ，以限制更信任該特定存放庫的人員。

用於憑證指紋的支援雜湊演算法為 SHA256 、 SHA384 和 SHA512 。

certificate如果指定 allowUntrustedRoot 為 true 指定的憑證，則允許鏈結至不受信任的根目錄，同時建置憑證鏈結做為簽章驗證的一部分。

範例：

<trustedSigners>
    <author name="microsoft">
        <certificate fingerprint="3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <certificate fingerprint="AA12DA22A49BCE7D5C1AE64CC1F3D892F150DA76140F210ABD2CBFFCA2C18A27" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
    </author>
    <repository name="nuget.org" serviceIndex="https://api.nuget.org/v3/index.json">
        <certificate fingerprint="0E5F38F57DC1BCC806D8494F4F90FBCEDD988B46760709CBEEC6F4219AA6157D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <certificate fingerprint="5A2901D6ADA3D18260B9C6DFE2133C95D74B9EEF6AE0E5DC334C8454D1477DF4" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        <owners>microsoft;aspnet;nuget</owners>
    </repository>
</trustedSigners>

fallbackPackageFolders 區段

(3.5+) 提供預先安裝套件的方式，以便在後援資料夾中找到套件時不需要執行任何工作。後援套件資料夾與全域套件資料夾具有相同的資料夾和檔案結構： .nupkg 存在，而且會擷取所有檔案。

此組態的查閱邏輯如下：

查看全域套件資料夾，以查看是否已下載套件/版本。
查看套件/版本相符的後援資料夾。

如果任一查閱都成功，則不需要下載。

如果找不到相符專案，則 NuGet 會檢查檔案來源，然後再檢查 HTTP 來源，然後下載套件。

Key	值
(後援資料夾的名稱)	後援資料夾的路徑。

範例：

<fallbackPackageFolders>
   <add key="XYZ Offline Packages" value="C:\somePath\someFolder\"/>
</fallbackPackageFolders>

套件來源對應區段

區 packageSourceMapping 段包含詳細資料，可協助 NuGet 套件作業判斷應該從何處下載套件識別碼。

本節目前只能手動管理。

區 packageSourceMapping 段只能包含 packageSource 區段。

packageSource

區段的 packageSourceMapping 子區段。包含可協助 NuGet 判斷來源是否應該考慮下載感興趣的套件的對應。

答案
區段中宣告 `packageSources` 的封裝來源名稱。金鑰必須完全符合封裝來源的金鑰。

下的 packageSourcepackageSourceMapping 區段是由唯一識別。 key

套件

package是區 packageSource 段的一部分。

模式
套件來源對應語法所定義的模式。

範例：

<packageSourceMapping>
  <packageSource key="contoso.com">
    <package pattern="Contoso.*" />
  </packageSource>
</packageSourceMapping>

packageManagement 區段

設定預設套件管理格式， packages.config 或 PackageReference。 SDK 樣式專案一律使用 PackageReference。

Key	值
format	指出預設套件管理格式的布林值。如果 `1` 為，則格式為 PackageReference。如果 `0` 為，則格式為packages.config。
disabled	布林值，指出是否要在第一次安裝套件時顯示選取預設套件格式的提示。 `False` 隱藏提示。

範例：

<packageManagement>
   <add key="format" value="1" />
   <add key="disabled" value="False" />
</packageManagement>

提示

指定節點具有 <clear /> 時，NuGet 會忽略先前針對該節點所定義的組態值。深入瞭解如何套用設定。

使用環境變數

您可以在 nuget.config 值中使用環境變數 (NuGet 3.4+)，在執行階段套用設定。

例如，如果 Windows 上的 HOME 環境變數設為 c:\users\username，則設定檔中的 %HOME%\NuGetRepository 值會解析為 c:\users\username\NuGetRepository。

請注意，您必須在 Mac/Linux 上使用 Windows 樣式環境變數， (開頭和結尾為 %) 。在組態檔中具有 $HOME/NuGetRepository 將無法解析。在 Mac/Linux 上，的值 %HOME%/NuGetRepository 會解析為 /home/myStuff/NuGetRepository 。

如果找不到環境變數，NuGet 會使用來自設定檔的常值。例如 %MY_UNDEFINED_VAR%/NuGetRepository ，會解析為 path/to/current_working_dir/$MY_UNDEFINED_VAR/NuGetRepository

下表顯示NuGet.Config檔案的環境變數語法和路徑分隔符號支援。

`NuGet.Config` 環境變數支援

Syntax	Dir 分隔符號	Windows nuget.exe	Windows dotnet.exe	Mono) 中的 Mac nuget.exe (	Mac dotnet.exe
`%MY_VAR%`	`/`	Yes	Yes	Yes	Yes
`%MY_VAR%`	`\`	Yes	是	否	No
`$MY_VAR`	`/`	No	No	No	No
`$MY_VAR`	`\`	No	No	No	No

範例設定檔

以下是說明一些設定的範例 nuget.config 檔案，包括選擇性設定：

<?xml version="1.0" encoding="utf-8"?>
<configuration>
    <config>
        <!--
            Used to specify the default location to expand packages.
            See: nuget.exe help install
            See: nuget.exe help update

            In this example, %PACKAGEHOME% is an environment variable.
            This syntax works on Windows/Mac/Linux
        -->
        <add key="repositoryPath" value="%PACKAGEHOME%/External" />

        <!--
            Used to specify default source for the push command.
            See: nuget.exe help push
        -->

        <add key="defaultPushSource" value="https://MyRepo/ES/api/v2/package" />

        <!-- Proxy settings -->
        <add key="http_proxy" value="host" />
        <add key="http_proxy.user" value="username" />
        <add key="http_proxy.password" value="encrypted_password" />
    </config>

    <packageRestore>
        <!-- Allow NuGet to download missing packages -->
        <add key="enabled" value="True" />

        <!-- Automatically check for missing packages during build in Visual Studio -->
        <add key="automatic" value="True" />
    </packageRestore>

    <!--
        Used to specify the default Sources for list, install and update.
        See: nuget.exe help list
        See: nuget.exe help install
        See: nuget.exe help update
    -->
    <packageSources>
        <add key="NuGet official package source" value="https://api.nuget.org/v3/index.json" />
        <add key="MyRepo - ES" value="https://MyRepo/ES/nuget" />
    </packageSources>

    <!-- Used to store credentials -->
    <packageSourceCredentials />

    <!-- Used to disable package sources  -->
    <disabledPackageSources />

    <!--
        Used to specify default API key associated with sources.
        See: nuget.exe help setApiKey
        See: nuget.exe help push
        See: nuget.exe help mirror
    -->
    <apikeys>
        <add key="https://MyRepo/ES/api/v2/package" value="encrypted_api_key" />
    </apikeys>

    <!--
        Used to specify trusted signers to allow during signature verification.
        See: nuget.exe help trusted-signers
    -->
    <trustedSigners>
        <author name="microsoft">
            <certificate fingerprint="3F9001EA83C560D712C24CF213C3D312CB3BFF51EE89435D3430BD06B5D0EECE" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <certificate fingerprint="AA12DA22A49BCE7D5C1AE64CC1F3D892F150DA76140F210ABD2CBFFCA2C18A27" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
        </author>
        <repository name="nuget.org" serviceIndex="https://api.nuget.org/v3/index.json">
            <certificate fingerprint="0E5F38F57DC1BCC806D8494F4F90FBCEDD988B46760709CBEEC6F4219AA6157D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <certificate fingerprint="5A2901D6ADA3D18260B9C6DFE2133C95D74B9EEF6AE0E5DC334C8454D1477DF4" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <owners>microsoft;aspnet;nuget</owners>
        </repository>
    </trustedSigners>
</configuration>

`nuget.config` 參考

config 區段

bindingRedirects 區段

packageRestore 區段

solution 區段

套件來源區段

packageSources

packageSourceCredentials

apikeys

disabledPackageSources

activePackageSource

trustedSigners 區段

fallbackPackageFolders 區段

套件來源對應區段

packageSource

套件

packageManagement 區段

使用環境變數

`NuGet.Config` 環境變數支援

範例設定檔

其他資源

其他資源

nuget.config 參考

config 區段

bindingRedirects 區段

packageRestore 區段

solution 區段

套件來源區段

packageSources

packageSourceCredentials

apikeys

disabledPackageSources

activePackageSource

trustedSigners 區段

fallbackPackageFolders 區段

套件來源對應區段

packageSource

套件

packageManagement 區段

使用環境變數

NuGet.Config 環境變數支援

範例設定檔

其他資源

其他資源

`nuget.config` 參考

`NuGet.Config` 環境變數支援