.Net Core Visual Studio NuGet.Config 配置参考

Visual Studio 2022 NUGET NU1301 无法加载源 基础连接已关闭：无法建立SSL / TLS安全通道的信任关系；根据验证过程，远程证书无效，参考文章：https://blog.csdn.net/hefeng_aspnet/article/details/145780081

NuGet 行为由不同 NuGet.Config 或 nuget.config 文件中的设置来控制，如常见 NuGet 配置中所述。

nuget.config 是包含顶级 <configuration> 节点的 XML 文件，而该节点包含本主题中所述的节元素。 每个部分均包含零个或多个项。 请参阅示例配置文件。 设置名称不区分大小写，并且值可以使用环境变量。

 提示

在项目存储库的根目录中添加 nuget.config 文件。 这被认为是一种最佳做法，因为它促进了可重复性，并可确保不同的用户具有相同的 NuGet 配置。 可能需配置 clear 元素以确保不应用任何特定于用户或计算机的配置。 详细了解如何应用设置。

配置节

包含杂项配置设置，可使用 nuget config 命令设置。

dependencyVersion 和 repositoryPath 仅适用于使用 packages.config 的项目。 globalPackagesFolder 仅适用于使用 PackageReference 格式的项目。

密钥	值
dependencyVersion（仅限于 packages.config）	包安装、还原和更新的默认 DependencyVersion 值（未直接指定 -DependencyVersion 开关时）。 NuGet 包管理器 UI 也使用此值。 值为 Lowest、HighestPatch、HighestMinor、Highest。
globalPackagesFolder	默认全局包文件夹的位置。 默认值为 %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	连接到包源时要使用的代理设置；http_proxy 应为 http://<username>:<password>@<domain> 格式。 密码已加密，且不能手动添加。 对于 no_proxy，该值是绕过代理服务器的域的列表（以逗号分隔）。 可将 http_proxy 和 no_proxy 环境变量交替用于这些值。 有关其他详细信息，请参阅 NuGet 代理设置 (skolima.blogspot.com)。
maxHttpRequestsPerSource	控制从 NuGet 发送到包依赖项解析和下载的每个包源的最大并行请求数。 dotnet.exe 的默认值为 Int32.MaxValue（从 HttpClientHandler.MaxConnectionsPerServer 属性派生）。 此设置不影响 Mac OS 的 dotnet.exe，因为已将限制设为 16 从而避免出现过多打开文件错误。 运行于 .NET Framework（例如 Visual Studio 和 nuget.exe）的 NuGet client tools 的默认值为 64（在 Windows 上）和 1（在 Mono 上）。 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:[e-mail]" />
    <add key="signatureValidationMode" value="require" />
    <add key="maxHttpRequestsPerSource" value="16" />
</config> 

bindingRedirects 节

在安装包时，配置 NuGet 是否执行自动绑定重定向。

密钥	值
skip	指示是否跳过自动绑定重定向的布尔。 默认值为 false。

示例： 

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

packageRestore 节

在生成期间控制包还原。

密钥	值
enabled	指示 NuGet 是否可执行自动还原的布尔。 还可以使用 True 的值设置 EnableNuGetPackageRestore 环境变量，而不是在配置文件中设置此密钥。
automatic	指示 NuGet 是否应在生成期间检查缺少的包。

示例： 

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

解决方案节

控制解决方案的 packages 文件夹是否包括在源代码管理中。 此节仅适用于解决方案文件夹中的 nuget.config 文件。

密钥	值
disableSourceControlIntegration	指示在使用源代码管理时是否忽略包文件夹的布尔。 默认值为 false。

示例： 

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

包源节

packageSources、packageSourceCredentials、apikeys、activePackageSource、disabledPackageSources、trustedSigners 和 packageSourceMapping 会共同配置在安装、还原和更新操作期间 NuGet 使用包存储库的方式。

nuget sources 命令通常用于管理这些设置，但用 nuget setapikey 命令来管理的 apikeys 以及用 nuget trusted-signers 命令来管理的 trustedSigners 除外。

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

packageSources

列出所有已知包源。 在还原操作期间以及针对采用 PackageReference 格式的所有项目，均会忽略该顺序。 对于使用 packages.config 的项目，NuGet 遵循针对安装和更新操作的源的顺序。

XML 特性	目的
键	（要分配给包源的名称）
值	包源的路径或 URL。
protocolVersion	要使用的 NuGet 服务器协议版本。 当前版本为“3”。 当未指向以 .json 结尾的包源 URL（例如 https://api.nuget.org/v3/index.json）时，默认为版本“2”。 在 NuGet 3.0 及以上版本中受到支持。 有关版本 3 协议的详细信息，请参阅 NuGet 服务器 API。
allowInsecureConnections	如果为 false 或未指定，则当源使用 http 而不是 https 时，NuGet 会发出警告。 如果你确信与此源的通信绝不会面临拦截攻击的风险，则可将该值设为 true 以不显示此警告。 在 NuGet 6.8 及以上版本中受到支持。
disableTLSCertificateValidation	此配置属性允许禁用 HTTPS 服务器的 SSL/TLS 证书验证。 如果设置为 true，服务器将忽略与 SSL/TLS 证书相关的任何错误（例如，过期证书或自签名证书），并在未进行验证的情况下建立连接。 在 NuGet 6.11 及以上版本中受到支持。

示例：

<packageSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
    <add key="Contoso" value="https://contoso.com/packages/" />
    <add key="http-source" value="http://httpsourcetrusted/" allowInsecureConnections="true" />
    <add key="Invalid-certificate-https-source" value="https://httpsSourceTrusted/" disableTLSCertificateValidation="true" />
    <add key="Test Source" value="c:\packages" />
</packageSources> 

 备注

使用信任的包源。

 备注

使用 CLI 时，可使用 RestoreSources MSBuild 属性或 --source(.NET CLI) | -Source(NuGet CLI) 以覆盖 NuGet.config 中定义的 <packageSources>。

 提示

当给定节点中存在 <clear /> 时，NuGet 将忽略之前为该节点定义的配置值。 详细了解如何应用设置。

auditSources

列出所有已知的审核源，NuGet 审核将在还原期间使用。 如果未提供审核源，则还原将使用包源并抑制 NU1905。 auditSources 已添加至 NuGet 6.12。

审核源支持与 packageSources（protocolVersion、allowInsecureConnections）相同的属性，使用 packageSourceCredentials 配置需要身份验证的源，与 packageSources 的方法相同。

示例：

<auditSources>
    <clear />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
</auditSources>

packageSourceCredentials

存储源的用户名和密码，通常通过 nuget sources 使用 -username 和 -password 开关指定。 默认情况下密码会进行加密，除非还使用了 -storepasswordincleartext 选项。 （可选）可使用 -validauthenticationtypes 开关指定有效的身份验证类型。

密钥	值
username	纯文本形式的源用户名。 注意：环境变量可用于提升安全性。
password	源的加密密码。 加密的密码仅在 Windows 上受到支持，且只能在同一计算机上使用时通过执行原始加密的同一用户来解密。
cleartextpassword	源的未加密密码。 注意：环境变量可用于提升安全性。
validauthenticationtypes	此源的有效身份验证类型的逗号分隔列表。 如果服务器公布 NTLM 或协商，并且你必须使用基本机制发送凭据（例如，在本地 Azure DevOps Server 中使用 PAT 时），则将此项设置为 basic。 其他有效值包括 negotiate、kerberos、ntlm 和 digest，但这些值不太可能有用。

 警告

强烈建议不要以明文形式存储密码。 请注意，仅 Windows 支持加密密码。 此外，加密密码只能在同一台计算机，由最初对其进行加密的同一用户解密。 有关安全地管理凭据的详细信息，请参阅使用私有源的包的安全最佳做法。

 提示

如果为 password 传递了非加密密码，则会出现错误消息“参数不正确”。

示例：

在配置文件中，<packageSourceCredentials> 元素包含每个适用源名称的子节点（名称中的空格被替换为 _x0020_）。 也就是说，对于名为“Contoso”和“测试源”的源，使用加密密码时，配置文件包含以下内容：

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="[e-mail]" />
        <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="[e-mail]" />
        <add key="Password" value="..." />
        <add key="ValidAuthenticationTypes" value="basic" />
    </Contoso>
    <Test_x0020_Source>
        <add key="Username" value="user" />
        <add key="Password" value="..." />
        <add key="ValidAuthenticationTypes" value="basic, negotiate" />
    </Test_x0020_Source>
</packageSourceCredentials> 

使用存储在环境变量中的未加密密码时： 

<packageSourceCredentials>
    <Contoso>
        <add key="Username" value="[e-mail]" />
        <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="[e-mail]" />
        <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>

apikeys

存储使用 API 密钥身份验证的源的密钥，如使用 nuget setapikey 命令 设置。

密钥	值
（源 URL）	加密的 API 密钥。

示例：

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

disabledPackageSources

标识当前已禁用的源。 可以为空。 除非在此部分禁用特定源，否则它们将被启用。

密钥	值
（源名称）	指示源是否禁用的布尔。

示例： 

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

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

在以上示例中，包源 Contoso 处于禁用状态，因而不会用于下载或安装包。

activePackageSource

（仅限于 2.x；3.x+ 中已弃用）

标识到当前活动的源或指示所有源的聚合。

密钥	值
（源名称）或 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。

可信存储库还会为存储库（必须为有效 https URI）指定 serviceIndex，且可选择性地指定以分号分隔的 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" />
        <certificate fingerprint="566A31882BE208BE4422F7CFD66ED09F5D4524A5994F50CCC8B05EC0528C1353" 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" />
        <certificate fingerprint="1F4B311D9ACC115C8DC8018B5A49E00FCE6DA8E2855F9F014CA6F34570BC482D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />        
        <owners>microsoft;aspnet;nuget</owners>
    </repository>
</trustedSigners>

fallbackPackageFolders 部分

(3.5+) 提供一种预安装包方法，以便在回退文件夹中找到包时无需执行任何操作。 回退包文件夹的文件夹和文件结构与全局包文件夹完全相同：存在 .nupkg，且会提取所有文件。

此配置的查找逻辑为：

• 查看全局包文件夹以确定是否已下载包/版本。

• 查看回退文件夹以确定是否存在包/版本匹配项。

如果任一查找成功，则无需进行下载。

如果未找到匹配项，NuGet 则会先检查文件源再检查 http 源，然后下载包。

密钥	值
（回退文件夹的名称）	回退文件夹的路径。

示例：

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

包源映射部分

packageSourceMapping 部分包含有助于 NuGet 包操作确定从何处下载包 ID 的详细信息。

此部分目前只能手动管理。

packageSourceMapping 部分只能包含 packageSource 部分。

packageSource

packageSourceMapping 部分的子部分。 包含一个映射，从而帮助 NuGet 确定是否应考虑此源来下载感兴趣的包。

密钥
在 packageSources 部分声明的包源的名称。 此密钥必须与包源的密钥完全匹配。

packageSourceMapping 下的 packageSource 部分由 key 进行唯一标识。

package

package 是 packageSource 部分的一部分。

模式
由包源映射的语法定义的模式。

示例：

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

packageManagement 部分

设置默认包管理格式，即 packages.config 或 PackageReference。 SDK 式项目始终使用 PackageReference。

密钥	值
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 环境变量支持

语法	目录分隔符	Windows nuget.exe	Windows dotnet.exe	Mac nuget.exe（在 Mono 中）	Mac dotnet.exe
%MY_VAR%	/	是	是	是	是
%MY_VAR%	\	是	是	否	No
$MY_VAR	/	No	No	No	No
$MY_VAR	\	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>
        <clear />
        <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" />
            <certificate fingerprint="566A31882BE208BE4422F7CFD66ED09F5D4524A5994F50CCC8B05EC0528C1353" 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" />
            <certificate fingerprint="1F4B311D9ACC115C8DC8018B5A49E00FCE6DA8E2855F9F014CA6F34570BC482D" hashAlgorithm="SHA256" allowUntrustedRoot="false" />
            <owners>microsoft;aspnet;nuget</owners>
        </repository>
    </trustedSigners>
</configuration>

参考文章：nuget.config 文件参考 | Microsoft Learn 

如果您喜欢此文章，请收藏、点赞、评论，谢谢，祝您快乐每一天。