JetBrains Rider 2026.1 Help

.NET 用户密钥管理

在 .NET 中处理安全密钥需要在便利和安全之间进行谨慎平衡。 将生产数据库连接字符串添加到应用程序配置中以便快速测试非常容易，但可能会不小心将其提交到源码管理。 .NET 用户密钥为本地开发期间存储敏感信息提供了一种简便方法，可显著降低密钥被暴露的风险。

.NET 密钥管理器

从 .NET Core 3.1 起，SDK 包含密钥管理器——一个命令行工具，可为项目相关密钥创建唯一存储。 初始化后，.NET 会将项目密钥存储在当前项目之外的用户专属目录中。 根据主机操作系统不同，存储位置会有所不同：

  • Windows： %APPDATA%\Microsoft\UserSecrets\<user_secrets_id>\secrets.json

  • Linux/macOS： ~/.microsoft/usersecrets/<user_secrets_id>/secrets.json

将密钥存储在项目外部可以减少意外提交到源码管理的风险。 包含密钥的文件夹是每个项目唯一的，会在项目文件中使用 UserSecretsId MSBuild 元素。 该值可以是任意唯一标识符，.NET 模板通常会为你初始化这个值。

你还可以使用 MSBuild 属性作为 UserSecretsId 的值。 例如，你可以使用 ProjectName 属性。 只需确保你的项目名称在整个开发环境中都是唯一的。

初始化用户密钥

如果项目缺少 UserSecretsId 元素，可以通过两种方式进行初始化。

从终端初始化

  1. 在 JetBrains Rider 中打开终端并切换到项目目录。

  2. 请运行以下命令：

    dotnet user-secrets init

从 Solution Explorer 初始化

  1. 在 Solution Explorer 中，右键点击项目节点。

  2. 导航到 工具 | .NET 用户密钥。

  3. JetBrains Rider 会通过向项目文件添加 UserSecretsId 元素来初始化项目，并在用户目录中打开 secrets.json 文件。

大多数 .NET 项目模板已经初始化了用户密钥，你可以立即使用其密钥值。

管理密钥

项目初始化后，可以通过编辑 secrets.json 文件来管理密钥。 该文件类似于许多 .NET 项目中使用的 appsettings.json 配置文件。 可以拥有复杂结构的配置信息，但通常会在这些文件中看到密钥-值对。

要打开 secrets.json 文件，请在 Solution Explorer 中右键点击项目并选择 工具 | .NET 用户密钥。

编辑 secrets.json 文件时，请确保遵循 JSON 格式。 编辑非项目文件时，你可能会收到警告，这是为了防止你不小心编辑了项目和源码管理之外的文件。 点击 确定 以允许编辑文件。

在控制台应用程序中使用用户密钥

控制台应用程序项目通常没有配置依赖项，因此需要手动添加。

  1. 创建一个新的控制台应用程序项目。

  2. 使用 NuGet 工具窗口 添加 Microsoft.Extensions.Configuration.UserSecrets NuGet 软件包。 该依赖项可以帮助创建配置实例并加载你的用户密钥文件。

  3. 使用 工具 | .NET 用户密钥 上下文菜单项来初始化项目。

  4. 打开 secrets.json 文件并添加你的密钥值。 例如：

    { "Name": "World" }

  5. 在 Program.cs 中，使用 ConfigurationBuilder 类型来构建 IConfiguration 实例并访问你的用户密钥：

    using Microsoft.Extensions.Configuration; var configuration = new ConfigurationBuilder() .AddUserSecrets<Program>() .Build(); Console.WriteLine($"Hello, {configuration["Name"]}!");

AddUserSecrets 调用的重要部分是其泛型类型实参。 UserSecretsId MSBuild 属性值会被添加到你的程序集，并可通过 UserSecretsIdAttribute 自定义特性进行访问。 没有该特性值，.NET 无法找到你的用户密钥文件位置。

在 ASP.NET Core 和 Worker Services 中使用用户密钥

大多数 ASP.NET Core 和 Worker Service 项目模板默认已包含用户密钥。 它们的密钥值可以立即使用。

ASP.NET Core 应用程序通常以如下代码开始：

var builder = WebApplication.CreateBuilder(args);

WebApplication.CreateBuilder 的调用会构建你的 IConfiguration 实例。 默认配置提供程序包括 JSON、环境变量、命令行实参和用户密钥。

与控制台应用程序不同，主机构建器仅在应用程序以开发模式运行时才注册用户密钥。 在本地开发场景之外，开发者通常不会使用用户密钥。 还有其他机制可以为你的应用程序提供密钥，这些方式在生产环境下更易于管理。

安全注意事项

secrets.json 文件未加密，若计算机被攻破，任何恶意行为者都可以访问。 但用户密钥有助于降低密钥被意外添加到源码管理的风险。

仍然要坚持良好的安全习惯，比如定期更换密钥，并仅向需要的人员开放对敏感信息的访问权限。

2026年 5月 8日
配置文件大小限制.NET 监视器