nuget.config 參考nuget.config reference

NuGet 行為是由不同或檔案中的設定所控制, NuGet.Config nuget.config一般 NuGet設定中所述。NuGet behavior is controlled by settings in different NuGet.Config or nuget.config files as described in Common NuGet configurations.

nuget.config 是包含最上層 <configuration> 節點的 XML 檔案,該節點則包含本主題中所述的區段項目。nuget.config is an XML file containing a top-level <configuration> node, which then contains the section elements described in this topic. 每個區段包含零或多個專案。Each section contains zero or more items. 請參閱設定檔範例See the examples config file. 設定名稱會區分大小寫,而且值可以使用環境變數Setting names are case-insensitive, and values can use environment variables.

config 區段config section

包含可使用 nuget config 命令設定的其他設定。Contains miscellaneous configuration settings, which can be set using the nuget config command.

dependencyVersionrepositoryPath 僅適用于使用的 packages.config 專案。dependencyVersion and repositoryPath apply only to projects using packages.config. globalPackagesFolder 只適用于使用 PackageReference 格式的專案。globalPackagesFolder applies only to projects using the PackageReference format.

KeyKey Value
dependencyVersion (僅 packages.config)dependencyVersion (packages.config only) 當未直接指定 -DependencyVersion 參數時,套件安裝、還原及更新的預設 DependencyVersion 值。The default DependencyVersion value for package install, restore, and update, when the -DependencyVersion switch is not specified directly. NuGet 套件管理員 UI 也使用此值。This value is also used by the NuGet Package Manager UI. 值為 LowestHighestPatchHighestMinorHighestValues are Lowest, HighestPatch, HighestMinor, Highest.
使用僅限 PackageReference 的 globalPackagesFolder (專案) globalPackagesFolder (projects using PackageReference only) 預設全域套件資料夾的位置。The location of the default global packages folder. 預設值為 %userprofile%\.nuget\packages (Windows) 或 ~/.nuget/packages (Mac/Linux)。The default is %userprofile%\.nuget\packages (Windows) or ~/.nuget/packages (Mac/Linux). 相對路徑可用於專案特有的 nuget.config 檔案。A relative path can be used in project-specific nuget.config files. 這項設定是由 NUGET_PACKAGES 環境變數所覆寫,這會優先使用。This setting is overridden by the NUGET_PACKAGES environment variable, which takes precedence.
repositoryPath (僅 packages.config)repositoryPath (packages.config only) 要在其中安裝 NuGet 套件的位置,而非預設 $(Solutiondir)/packages 資料夾。The location in which to install NuGet packages instead of the default $(Solutiondir)/packages folder. 相對路徑可用於專案特有的 nuget.config 檔案。A relative path can be used in project-specific nuget.config files. 這項設定是由 NUGET_PACKAGES 環境變數所覆寫,這會優先使用。This setting is overridden by the NUGET_PACKAGES environment variable, which takes precedence.
defaultPushSourcedefaultPushSource 識別在找不到任何其他套件來源可進行作業時,應該作為預設值使用的套件來源 URL 或路徑。Identifies the URL or path of the package source that should be used as the default if no other package sources are found for an operation.
http_proxy http_proxy.user http_proxy.password no_proxyhttp_proxy http_proxy.user http_proxy.password no_proxy 連線到套件來源時使用的 Proxy 設定;http_proxy 應該為 http://<username>:<password>@<domain> 格式。Proxy settings to use when connecting to package sources; http_proxy should be in the format http://<username>:<password>@<domain>. 密碼會加密,且無法手動新增。Passwords are encrypted and cannot be added manually. 對於 no_proxy,值是會略過 Proxy 伺服器的網域清單,並以逗號分隔。For no_proxy, the value is a comma-separated list of domains the bypass the proxy server. 您可以為那些值選擇使用 http_proxy 及 no_proxy 環境變數。You can alternately use the http_proxy and no_proxy environment variables for those values. 如需詳細資料,請參閱 NuGet proxy settings (NuGet proxy 設定) (skolima.blogspot.com)。For additional details, see NuGet proxy settings (skolima.blogspot.com).
因為 signaturevalidationmodesignatureValidationMode 指定驗證模式,用來驗證封裝安裝和還原的封裝簽章。Specifies the validation mode used to verify package signatures for package install, and restore. 值為 acceptrequireValues are accept, require. 預設值為 acceptDefaults to accept.

範例Example:

<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" />
</config>

bindingRedirects 區段bindingRedirects section

設定 NuGet 在安裝套件時,是否自動繫結重新導向。Configures whether NuGet does automatic binding redirects when a package is installed.

KeyKey Value
skipskip 布林值,指出是否略過自動繫結重新導向。A Boolean indicating whether to skip automatic binding redirects. 預設為 false。The default is false.

範例Example:

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

packageRestore 區段packageRestore section

控制建置期間的套件還原。Controls package restore during builds.

KeyKey Value
已啟用enabled 布林值,指出 NuGet 是否可以執行自動還原。A Boolean indicating whether NuGet can perform automatic restore. 您也可以使用 True 值來設定 EnableNuGetPackageRestore 環境變數,而不是在設定檔中設定此金鑰。You can also set the EnableNuGetPackageRestore environment variable with a value of True instead of setting this key in the config file.
automaticautomatic 布林值,指出 NuGet 是否應該在建置期間檢查遺漏的套件。A Boolean indicating whether NuGet should check for missing packages during a build.

範例Example:

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

solution 區段solution section

控制解決方案的 packages 資料夾是否會包含在原始檔控制。Controls whether the packages folder of a solution is included in source control. 本區段只適用於解決方案資料夾中的 nuget.config 檔。This section works only in nuget.config files in a solution folder.

KeyKey Value
disableSourceControlIntegrationdisableSourceControlIntegration 布林值,指出當使用原始檔控制時是否要忽略 packages 資料夾。A Boolean indicating whether to ignore the packages folder when working with source control. 預設值為 false。The default value is false.

範例Example:

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

套件來源區段Package source sections

packageSources、、 packageSourceCredentials apikeysactivePackageSource disabledPackageSources 和全都會 trustedSigners 一起運作,以設定在安裝、還原和更新作業期間,NuGet 與套件存放庫的搭配運作方式。The packageSources, packageSourceCredentials, apikeys, activePackageSource, disabledPackageSources and trustedSigners all work together to configure how NuGet works with package repositories during install, restore, and update operations.

nuget sources 命令通常用來管理這些設定,但 apikeys 使用 nuget setapikey 命令來管理,以及 trustedSigners 使用 nuget trusted-signers 命令管理的例外。The nuget sources command is generally used to manage these settings, except for apikeys which is managed using the nuget setapikey command, and trustedSigners which is managed using the nuget trusted-signers command.

請注意,nuget.org 的來源 URL 是 https://api.nuget.org/v3/index.jsonNote that the source URL for nuget.org is https://api.nuget.org/v3/index.json.

packageSourcespackageSources

列出所有已知的套件來源。Lists all known package sources. 在還原作業期間,以及使用 PackageReference 格式的任何專案時,會忽略順序。The order is ignored during restore operations and with any project using the PackageReference format. NuGet 會遵循使用專案進行安裝和更新作業的來源順序 packages.configNuGet respects the order of sources for install and update operations with projects using packages.config.

KeyKey Value
(要指派給套件來源的名稱)(name to assign to the package source) 套件來源的路徑或 URL。The path or URL of the package source.

範例Example:

<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 會忽略先前針對該節點所定義的組態值。When <clear /> is present for a given node, NuGet ignores previously defined configuration values for that node. 深入瞭解設定的套用方式Read more about how settings are applied.

packageSourceCredentialspackageSourceCredentials

儲存來源的使用者名稱和密碼,通常使用 nuget sources-username-password 參數來指定。Stores usernames and passwords for sources, typically specified with the -username and -password switches with nuget sources. 依預設會加密密碼,除非同時使用了 -storepasswordincleartext 選項。Passwords are encrypted by default unless the -storepasswordincleartext option is also used. (選擇性)使用參數可以指定有效的驗證類型 -validauthenticationtypesOptionally, valid authentication types can be specified with the -validauthenticationtypes switch.

KeyKey Value
usernameusername 純文字的來源使用者名稱。The user name for the source in plain text.
密碼password 加密的來源密碼。The encrypted password for the source. 只有在 Windows 上才支援加密的密碼,而且只有在同一部電腦上使用時,以及透過與原始加密相同的使用者才能解密。Encrypted passwords are only supported on Windows, and only can be decrypted when used on the same machine and via the same user as the original encryption.
cleartextpasswordcleartextpassword 未加密的來源密碼。The unencrypted password for the source. 注意:環境變數可以用來改善安全性。Note: environment variables can be used for improved security.
validauthenticationtypesvalidauthenticationtypes 此來源的有效驗證類型清單(以逗號分隔)。Comma-separated list of valid authentication types for this source. 將此設定為, basic 如果伺服器通告 NTLM 或 Negotiate,而且您的認證必須使用基本機制傳送,例如,搭配內部部署 Azure DevOps Server 使用 PAT。Set this to basic if the server advertises NTLM or Negotiate and your credentials must be sent using the Basic mechanism, for instance when using a PAT with on-premises Azure DevOps Server. 其他有效的值包括 negotiatekerberosntlmdigest ,但這些值不太可能很有用。Other valid values include negotiate, kerberos, ntlm, and digest, but these values are unlikely to be useful.

範例︰Example:

設定檔中,<packageSourceCredentials> 項目包含每個適用來源名稱的子節點 (名稱中的空格會取代為 _x0020_)。In the config file, the <packageSourceCredentials> element contains child nodes for each applicable source name (spaces in the name are replaced with _x0020_). 也就是說,對於名為 "Contoso" 和 "Test Source" 的來源,在使用加密的密碼時設定檔時包含下列內容:That is, for sources named "Contoso" and "Test Source", the config file contains the following when using encrypted passwords:

<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>

使用儲存在環境變數中的未加密密碼時:When using unencrypted passwords stored in an environment variable:

<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>

使用未加密的密碼時:When using unencrypted passwords:

<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>

此外,也可以提供有效的驗證方法:Additionally, valid authentication methods can be supplied:

<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>

apikeysapikeys

儲存使用 API 金鑰驗證之來源的金鑰,如 nuget setapikey 命令所設定。Stores keys for sources that use API key authentication, as set with the nuget setapikey command.

KeyKey Value
(來源 URL)(source URL) 加密的 API 金鑰。The encrypted API key.

範例Example:

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

disabledPackageSourcesdisabledPackageSources

識別目前已停用的來源。Identified currently disabled sources. 可以是空的。May be empty.

KeyKey Value
(來源名稱)(name of source) 布林值,指出是否停用來源。A Boolean indicating whether the source is disabled.

範例︰Example:

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

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

activePackageSourceactivePackageSource

(僅 2.x,在 3.x+ 中已被取代)(2.x only; deprecated in 3.x+)

識別目前作用中的來源,或表示所有來源的彙總。Identifies to the currently active source or indicates the aggregate of all sources.

KeyKey Value
(來源名稱) 或 All(name of source) or All 如果金鑰是來源的名稱,則值是來源路徑或 URL。If key is the name of a source, the value is the source path or URL. 若為 All,值應該是 (Aggregate source) 以結合未以其他方式停用的所有套件來源。If All, value should be (Aggregate source) to combine all package sources that are not otherwise disabled.

範例Example:

<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 區段trustedSigners section

在安裝或還原時,儲存用來允許套件的受信任簽署者。Stores trusted signers used to allow package while installing or restoring. 當使用者將設定為時,此清單不可以是空的 signatureValidationMode requireThis list cannot be empty when the user sets signatureValidationMode to require.

您可以使用 nuget trusted-signers 命令來更新此區段。This section can be updated with the nuget trusted-signers command.

結構描述Schema:

受信任的簽署者有一個 certificate 專案集合,這些專案會登錄識別指定之簽署者的所有憑證。A trusted signer has a collection of certificate items that enlist all the certificates that identify a given signer. 受信任的簽署者可以是 AuthorRepositoryA trusted signer can be either an Author or a Repository.

受信任的存放 也會指定存放 serviceIndex 庫 (的,其必須是有效的 https uri) 而且可以選擇性地指定以分號分隔的清單, owners 以限制更多受該特定存放庫信任的物件。A trusted repository also specifies the serviceIndex for the repository (which has to be a valid https uri) and can optionally specify a semi-colon delimited list of owners to restrict even more who is trusted from that specific repository.

用於憑證指紋的支援雜湊演算法為 SHA256SHA384SHA512The supported hash algorithms used for a certificate fingerprint are SHA256, SHA384 and SHA512.

如果 certificate 指定為指定的 allowUntrustedRoot 憑證,則在 true 建立憑證鏈作為簽章驗證的一部分時,允許鏈至不受信任的根。If a certificate specifies allowUntrustedRoot as true the given certificate is allowed to chain to an untrusted root while building the certificate chain as part of the signature verification.

範例Example:

<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" />
        <owners>microsoft;aspnet;nuget</owners>
    </repository>
</trustedSigners>

fallbackPackageFolders 區段fallbackPackageFolders section

(3.5 +) 提供預先安裝封裝的方法,因此,如果在回溯資料夾中找到封裝,就不需要執行任何工作。(3.5+) Provides a way to preinstall packages so that no work needs to be done if the package is found in the fallback folders. Fallback 封裝資料夾與全域封裝資料夾的資料夾和檔案結構完全相同: nupkg 存在,而且所有檔案都已解壓縮。Fallback package folders have the exact same folder and file structure as the global package folder: .nupkg is present, and all files are extracted.

這項設定的查閱邏輯是:The lookup logic for this configuration is:

  • 查看全域封裝資料夾,查看是否已下載套件/版本。Look in global package folder to see if the package/version is already downloaded.

  • 查看 [回復] 資料夾中是否有套件/版本相符。Look in the fallback folders for a package/version match.

如果其中一項查閱成功,則不需要下載。If either lookup is successful, then no download is necessary.

如果找不到相符項,則 NuGet 會檢查檔案來源,然後再檢查 HTTP 來源,然後下載套件。If a match is not found, then NuGet checks file sources, and then http sources, and then it downloads the packages.

KeyKey Value
(的 [fallback] 資料夾名稱) (name of fallback folder) Fallback 資料夾的路徑。Path to fallback folder.

範例Example:

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

packageManagement 區段packageManagement section

設定預設封裝管理格式( packages.config 或 PackageReference)。Sets the default package management format, either packages.config or PackageReference. SDK 樣式的專案一律使用 PackageReference。SDK-style projects always use PackageReference.

KeyKey Value
formatformat 指出預設封裝管理格式的布林值。A Boolean indicating the default package management format. 如果 1 為,則格式為 PackageReference。If 1, format is PackageReference. 如果 0 為,則 packages.config 格式。If 0, format is packages.config.
disableddisabled 布林值,指出是否要在第一次安裝套件時顯示提示以選取預設封裝格式。A Boolean indicating whether to show the prompt to select a default package format on first package install. False 隱藏提示。False hides the prompt.

範例Example:

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

使用環境變數Using environment variables

您可以在 nuget.config 值中使用環境變數 (NuGet 3.4+),在執行階段套用設定。You can use environment variables in nuget.config values (NuGet 3.4+) to apply settings at run time.

例如,如果 Windows 上的 HOME 環境變數設為 c:\users\username,則設定檔中的 %HOME%\NuGetRepository 值會解析為 c:\users\username\NuGetRepositoryFor example, if the HOME environment variable on Windows is set to c:\users\username, then the value of %HOME%\NuGetRepository in the configuration file resolves to c:\users\username\NuGetRepository.

請注意,您必須使用 Windows 樣式的環境變數 (以% ) 作為開頭和結尾,即使是在 Mac/Linux 上也是如此。Note that you have to use Windows-style environment variables (starts and ends with %) even on Mac/Linux. $HOME/NuGetRepository無法解析設定檔中的 Having。Having $HOME/NuGetRepository in a configuration file will not resolve. 在 Mac/Linux 上,的值 %HOME%/NuGetRepository 會解析為 /home/myStuff/NuGetRepositoryOn Mac/Linux the value of %HOME%/NuGetRepository will resolve to /home/myStuff/NuGetRepository.

如果找不到環境變數,NuGet 會使用來自設定檔的常值。If an environment variable is not found, NuGet uses the literal value from the configuration file. 例如, %MY_UNDEFINED_VAR%/NuGetRepository 將解析為 path/to/current_working_dir/$MY_UNDEFINED_VAR/NuGetRepositoryFor example %MY_UNDEFINED_VAR%/NuGetRepository will be resolved as path/to/current_working_dir/$MY_UNDEFINED_VAR/NuGetRepository

下表顯示 NuGet.Config 檔案的環境變數語法和路徑分隔符號的支援。The table below show environnment variable syntax and path separator support for NuGet.Config files.

NuGet.Config 環境變數支援NuGet.Config environment variable support

語法Syntax Dir 分隔符號Dir separator Windows nuget.exeWindows nuget.exe Windows dotnet.exeWindows dotnet.exe Mono 中的 Mac nuget.exe () Mac nuget.exe (in Mono) Mac dotnet.exeMac dotnet.exe
%MY_VAR% / Yes Yes Yes Yes
%MY_VAR% \ Yes Yes No No
$MY_VAR / No No No No
$MY_VAR \ No No No No

範例設定檔Example config file

以下是範例檔案 nuget.config ,其中說明許多設定,包括選擇性的設定:Below is an example nuget.config file that illustrates a number of settings including optional ones:

<?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" />
            <owners>microsoft;aspnet;nuget</owners>
        </repository>
    </trustedSigners>
</configuration>