ASP.NET Core 配置分步指南
如果您不熟悉 ASP.NET Core 开发，您会注意到的前几件事之一是旧的 web.config 或 app.config 文件在 ASP.NET Core 项目中不再可用。 ASP.NET Core 中的配置是使用一个或多个配置提供程序执行的。有配置提供程序可以从几乎任何地方读取配置，例如文件，例如JSON、INI 或 XML、环境变量、Azure 密钥保管库、命令行参数等以及更多来源。本教程是分步指南，向您展示如何在各种文件（如 JSON、INI 或 XML）中配置应用程序设置，以及如何从应用程序代码中读取这些设置。我还将演示如何将应用程序设置读取为自定义 .NET 类型（类），以及如何使用内置的 ASP.NET Core 依赖项注入来读取解决方案中可用的多个类、服务甚至项目中的配置设置.
ASP.NET Core 配置
-
- 构建项目
- 默认配置
- 自定义应用程序配置
- 使用选项模式读取应用程序设置
- 在 ASP.NET Core 中使用 XML 配置提供程序
- 在 ASP.NET Core 中使用 INI 配置提供程序
- 总结概述
构建项目
使用 Visual Studio 2019 专业版或社区版创建 ASP.NET Core Web 应用程序。提供项目名称和位置，然后从可用模板之一中选择 MVC Web 应用程序
构建您的项目并按 F4 以确保该项目在浏览器中运行没有任何问题。
默认配置
当我们使用命令行或 Visual Studio 创建 ASP.NET Core Web 应用程序时，我们会看到一些自动生成的文件，其中一个文件是 Program.cs 文件。
此文件为我们创建主机构建器，您还将在此文件中看到一个方法 CreateDefaultBuilder，如下所示。
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
CreateDefaultBuilder 方法按以下顺序为我们的应用程序配置默认配置：
- 如果有任何主机配置和设置，它们将首先使用 ChainedConfigurationProvider 添加。
- 接下来，它将使用 JSON配置提供程序配置我们在项目 appsettings.json 文件中定义的项目设置。
- 如果我们在appsettings.Development.json 或appsettings.Production.json文件中有特定于环境的应用程序设置，那么它们将被配置。
- 如果我们配置了任何与开发相关的应用程序机密，接下来将加载它们。
- 接下来将使用环境变量配置提供程序加载环境变量。
- 最后，命令行参数将使用命令行配置提供程序加载。
请记住，上面列表中稍后添加的配置提供程序将覆盖任何以前的配置提供程序加载的以前的关键设置。例如，如果您配置了一个设置 在 appsettings.json 和环境中，将使用环境值。 使用默认配置提供程序，命令行配置提供程序覆盖所有其他提供程序，因为它们添加到上述列表的末尾。
自定义应用程序配置
现在我们需要决定我们要配置哪些应用程序设置，对于本教程，我将以下配置设置保存在我的项目 appsettings.json 文件中。
{
"MyApplication": {
"Name": "Demo Configuration Application",
"Version": "1.0",
"DefaultUrl": "http://www.exampledemoapp.com",
"Support": {
"Email": "[email protected]",
"Phone": "123456789"
}
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
},
"AllowedHosts": "*"
}
在 appsettings.Development.json 文件中添加了一些与开发环境相关的不同值的类似设置。
{
"MyApplication": {
"Name": "Demo Configuration Application (Development)",
"Version": "1.1",
"DefaultUrl": "http://localhost:3030",
"Support": {
"Email": "[email protected]",
"Phone": "123456789"
}
},
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft": "Warning",
"Microsoft.Hosting.Lifetime": "Information"
}
}
}
我们需要在我们的应用程序代码中读取这些设置，因此打开 HomeController.cs 文件并声明一个 IConfiguration 类型的私有字段。在 HomeController 的构造函数中注入 IConfiguration 参数，并确保在构造函数中初始化私有字段 Configuration。
using Microsoft.Extensions.Configuration;
private readonly IConfiguration Configuration;
public HomeController(IConfiguration configuration)
{
Configuration = configuration;
}
ASP.NET Core 将在运行时自动注入和初始化我们的字段，并使我们能够访问应用程序中所有可用的配置设置。要读取代码中的配置设置，我们需要使用上面的Configuration变量，并且需要将应用设置键名传递给索引器。如果我们有一个嵌套设置，那么我们可以使用冒号运算符分隔父设置和子设置，就像我们在下面的“MyApplication:Support:Email”的情况下所做的那样。
public IActionResult Index()
{
var appName = Configuration["MyApplication:Name"];
var appVersion = Configuration["MyApplication:Version"];
var appUrl = _ Configuration["MyApplication:DefaultUrl"];
var supportEmail = _ Configuration["MyApplication:Support:Email"];
var supportPhone = _ Configuration["MyApplication:Support:Phone"];
ViewBag.ApplicationName = appName;
ViewBag.ApplicationVersion = appVersion;
ViewBag.ApplicationUrl = appUrl;
ViewBag.SupportEmail = supportEmail;
ViewBag.SupportPhone = supportPhone;
return View();
}
我已经使用 ViewBag 将设置传递给视图，然后使用相同的 ViewBag 属性在视图中显示设置。
<div>
<h4>
@ViewBag.ApplicationName
</h4>
<h5>
Version: @ViewBag.ApplicationVersion
</h5>
<br />
<table class="table table-bordered table-striped" style="width:90%;">
<tr>
<td><b>Default URL</b></td>
<td>@ViewBag.ApplicationUrl</td>
</tr>
<tr>
<td><b>Support Email</b></td>
<td>@ViewBag.SupportEmail</td>
</tr>
<tr>
<td><b>Support Phone</b></td>
<td>@ViewBag.SupportPhone</td>
</tr>
</table>
</div>
如果您现在运行该项目，您将在浏览器中看到以下输出：
您可能在上面注意到的一件事是应用程序正在从 appsettings.Development.json 文件中读取设置，这是因为默认情况下，应用程序的当前环境设置为 Development。
默认的 JsonConfigurationProvider 首先加载 appsettings.json，然后加载 appsettings.Environment.json 并将覆盖 appsetttings.json 文件中定义的设置。例如，默认情况下：
- 在开发中，appsettings.Development.json 配置会覆盖 appsettings.json 中的值。
- 在生产中，appsettings.Production.json 配置会覆盖 appsettings.json中的值。例如，将应用程序部署到 Azure 时。
如果您将环境从上面的“开发”更改为“生产”并运行您的应用程序，您将看到该应用程序将停止从 appsettings.Development.json 文件中读取设置，因为我们没有 appsettings.Production.json文件中的文件，以便读取和显示 appsettings.json 文件中定义的所有内容。
使用选项模式读取应用程序设置
如果您正在构建一个具有大量配置的大型应用程序，或者您有许多层次设置要读取，那么不推荐逐个读取所有设置。也有可能在代码中拼错设置键，这可能会导致难以跟踪的错误。读取配置值的首选方法是使用选项模式。选项模式使用类来提供对相关设置组的强类型访问。要以强类型方式读取上述配置值，我们需要创建强类型 C# 类，如下所示：
public class ApplicationOptions
{
public const string MyApplication = "MyApplication";
public string Name { get; set; }
public decimal Version { get; set; }
public string DefaultUrl { get; set; }
public SupportOptions Support { get; set; }
}
public class SupportOptions
{
public const string Support = "Support";
public string Email { get; set; }
public string Phone { get; set; }
}
在创建强类型类以使用选项模式读取配置时，我们需要牢记以下几点。
- 类必须是具有公共无参数构造函数的非抽象类。
- 该类型的所有公共读写属性都被绑定。
- 字段未绑定，例如 MyApplication 和Support const 字段将不被绑定
要绑定我们的设置，我们需要调用 ConfigurationBinder.Bind 方法，并需要将 ApplicationOptions 类对象与 MyApplication 部分绑定，如下所示：
public IActionResult Index()
{
var applicationOptions = new ApplicationOptions();
Configuration.GetSection(ApplicationOptions.MyApplication).Bind(applicationOptions);
ViewBag.ApplicationName = applicationOptions.Name;
ViewBag.ApplicationVersion = applicationOptions.Version;
ViewBag.ApplicationUrl = applicationOptions.DefaultUrl;
ViewBag.SupportEmail = applicationOptions.Support.Email;
ViewBag.SupportPhone = applicationOptions.Support.Phone;
return View();
}
在前面的代码中，我们调用了 Bind 方法来绑定配置部分。还有另一种方便的方法 **Get**可用于将配置部分读取为指定的类型。以下是如何使用 Get方法读取和绑定具有强类型类的配置：
public IActionResult Index()
{
var applicationOptions = _ Configuration.GetSection(ApplicationOptions.MyApplication).Get<ApplicationOptions>();
ViewBag.ApplicationName = applicationOptions.Name;
ViewBag.ApplicationVersion = applicationOptions.Version;
ViewBag.ApplicationUrl = applicationOptions.DefaultUrl;
ViewBag.SupportEmail = applicationOptions.Support.Email;
ViewBag.SupportPhone = applicationOptions.Support.Phone;
return View();
}
在我上面的所有示例中，我正在读取标准 MVC 控制器中的应用程序设置。如果您有一个大型应用程序，您可能希望在整个应用程序中读取多个控制器和类中的配置。不建议在每个类中绑定配置部分并编写大量重复代码。更好的方法是使用选项模式将配置部分绑定到 Startup.cs 文件的 ConfigureServices 方法中，然后将其添加到依赖注入服务容器中。
public class Startup
{
public Startup(IConfiguration configuration)
{
Configuration = configuration;
}
public IConfiguration Configuration { get; }
public void ConfigureServices(IServiceCollection services)
{
services.Configure<ApplicationOptions>(Configuration.GetSection(ApplicationOptions.MyApplication));
services.AddControllersWithViews();
}
}
一旦我们的配置被添加到依赖注入容器中，我们就可以在我们想要读取配置设置的任何控制器或类中使用 IOptions 接口注入 ApplicationOptions 对象。以下代码显示了如何在 HomeController 中注入 ApplicationOptions 并从 appsettings.json 文件中读取我们的设置。
public class HomeController : Controller
{
private readonly ApplicationOptions _options;
public HomeController(IOptions<ApplicationOptions> options)
{
_options = options.Value;
}
public IActionResult Index()
{
ViewBag.ApplicationName = _options.Name;
ViewBag.ApplicationVersion = _options.Version;
ViewBag.ApplicationUrl = _options.DefaultUrl;
ViewBag.SupportEmail = _options.Support.Email;
ViewBag.SupportPhone = _options.Support.Phone;
return View();
}
}
在 ASP.NET Core 中使用 XML 配置提供程序
到目前为止，在本教程中，我们使用默认的 JsonConfigurationProvider，它从 appsettings.json 文件中读取设置。如果您不喜欢 JSON 并且想要从 XML 文件存储和读取设置，那么您必须使用 XmlConfigurationProvider 在运行时从 XML 文件键值对加载配置。让我们创建一个 appsettings.xml 文件并在新创建的 XML 文件中添加类似的设置。
<MyApplication>
<Name>Demo Configuration ApplicationName>
<Version>1.0Version>
<DefaultUrl>http://www.exampledemoapp.comDefaultUrl>
<Support>
<Email>[email protected]Email>
<Phone>123456789Phone>
Support>
MyApplication>
以下代码清除所有配置提供程序并添加多个配置提供程序。我正在使用 AddXmlFile 方法添加 appsettings.xml 和任何特定于环境的文件，例如 appsettings.Development.xml 和 appsettings.Production.xml。最后，我添加了环境变量和命令行配置提供程序。
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.Sources.Clear();
var env = hostingContext.HostingEnvironment;
config.AddXmlFile("appsettings.xml", optional: true, reloadOnChange: true)
.AddXmlFile($"appsettings.{env.EnvironmentName}.xml",
optional: true, reloadOnChange: true);
config.AddEnvironmentVariables();
if (args != null)
{
config.AddCommandLine(args);
}
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
以下代码展示了如何使用本教程开始时使用的相同 IConfiguration 对象读取 C# 代码中的 XML 设置。
public class HomeController : Controller
{
private readonly IConfiguration Configuration;
public HomeController(IConfiguration configuration)
{
Configuration = configuration;
}
public IActionResult Index()
{
var appName = Configuration["Name"];
var appVersion = Configuration["Version"];
var appUrl = Configuration["DefaultUrl"];
var supportEmail = Configuration["Support:Email"];
var supportPhone = Configuration["Support:Phone"];
ViewBag.ApplicationName = appName;
ViewBag.ApplicationVersion = appVersion;
ViewBag.ApplicationUrl = appUrl;
ViewBag.SupportEmail = supportEmail;
ViewBag.SupportPhone = supportPhone;
return View();
}
}
如果您现在运行该应用程序，您将看到与我们在使用 JSON 配置文件时看到的类似的输出。
在 ASP.NET Core 中使用 INI 配置提供程序
如果您正在与遗留系统集成，其中设置以 INI 文件的形式提供，那么您必须使用 IniConfigurationProvider 在运行时从 INI 文件键值对加载配置。让我们创建一个 appsettings.ini 文件并在新创建的 INI 文件中添加类似的设置。
[MyApplication]
Name="Demo Configuration Application"
Version=1.0
DefaultUrl="http://www.exampledemoapp.com"
[MyApplication:Support]
Email="[email protected]"
Phone="123456789"
下面的代码与上面的代码非常相似，我们从基于 XML 的配置文件中读取设置。我们需要清除所有配置提供程序并添加 INI 文件以及其他配置提供程序。我们需要使用 AddIniFile 方法来添加 appsettings.ini 和任何特定于环境的文件，例如 appsettings.Development.ini 和 appsettings.Production.ini。最后，我添加了环境变量和命令行配置提供程序。
public class Program
{
public static void Main(string[] args)
{
CreateHostBuilder(args).Build().Run();
}
public static IHostBuilder CreateHostBuilder(string[] args) =>
Host.CreateDefaultBuilder(args)
.ConfigureAppConfiguration((hostingContext, config) =>
{
config.Sources.Clear();
var env = hostingContext.HostingEnvironment;
config.AddIniFile("appsettings.ini", optional: true, reloadOnChange: true)
.AddIniFile($"appsettings.{env.EnvironmentName}.ini",
optional: true, reloadOnChange: true);
config.AddEnvironmentVariables();
if (args != null)
{
config.AddCommandLine(args);
}
})
.ConfigureWebHostDefaults(webBuilder =>
{
webBuilder.UseStartup<Startup>();
});
}
以下代码展示了如何使用本教程开始时使用的相同 IConfiguration 对象读取 C# 代码中的 INI 设置。
public class HomeController : Controller
{
private readonly IConfiguration Configuration;
public HomeController(IConfiguration configuration)
{
Configuration = configuration;
}
public IActionResult Index()
{
var appName = Configuration["MyApplication:Name"];
var appVersion = Configuration["MyApplication:Version"];
var appUrl = Configuration["MyApplication:DefaultUrl"];
var supportEmail = Configuration["MyApplication:Support:Email"];
var supportPhone = Configuration["MyApplication:Support:Phone"];
ViewBag.ApplicationName = appName;
ViewBag.ApplicationVersion = appVersion;
ViewBag.ApplicationUrl = appUrl;
ViewBag.SupportEmail = supportEmail;
ViewBag.SupportPhone = supportPhone;
return View();
}
}
总结概述
ASP.NET Core 提供了强大而灵活的选项，支持多种不同的配置方式，例如基于文件的配置、内存中的配置、环境变量，甚至命令行参数。这也支持选项模型，以便我们可以将设置强注入我们的应用程序。我们还可以创建一个自定义配置提供程序，使用实体框架 (EF) 从数据库中读取配置键值对。