.NET Aspire 外部参数 (External parameters)
.NET Aspire 外部参数 (External parameters)
https://learn.microsoft.com/en-us/dotnet/aspire/fundamentals/external-parameters
环境提供应用运行的上下文。Parameter 提供了在应用运行中请求外部值的功能。当应用本地运行的时候，Parameter 可以为应用提供值，或者在应用部署的时候，提示值。Parameter 可以用于建模各种场景，包括密钥，连接串，以及其它在各种环境下变得不同的配置值。
参数值
参数的值可以通过 app host 的配置读取，然后用于本地运行的应用。当部署应用的时候，实际的值会通过参数值来获得。
考虑下面的 app host 的 Program.cs 示例。
var builder = DistributedApplication.CreateBuilder(args);
// Add a parameter
IResourceBuilder<ParameterResource> value = builder.AddParameter("value");
builder.AddProject<Projects.ApiService>("api")
.WithEnvironment("EXAMPLE_VALUE", value);
相应的 appsettings.json 为：
{
"Parameters": {
"value": "local-value"
}
}
参数在清单中表示为名为 parameter.v0 的新基元：
{
"resources": {
"value": {
"type": "parameter.v0",
"value": "{value.inputs.value}",
"inputs": {
"value": {
"type": "string"
}
}
}
}
}
密钥
参数 Parameter 还可以用来建模密钥。当一个 Parameter 标记为密钥的时候，它提示清单该值应该被看做密钥。在部署中需要提示并保存在安全的位置。
当在本地运行的时候，该值将通过 app host 的配置中的 Parameters 配置节中读取出来。
考虑下面的 app host 中的 Program.cs 代码示例：
var builder = DistributedApplication.CreateBuilder(args);
// Add a secret parameter
var secret = builder.AddParameter("secret", secret: true);
builder.AddProject<Projects.ApiService>("api")
.WithEnvironment("SECRET", secret);
builder.Build().Run();
现在考虑相应的 app host 中如下的 appsettings.josn
{
"Parameters": {
"secret": "local-secret"
}
}
清单文件中的表示如下：
{
"resources": {
"value": {
"type": "parameter.v0",
"value": "{value.inputs.value}",
"inputs": {
"value": {
"type": "string",
"secret": true
}
}
}
}
}
连接串的值
Parameter 还可以用来建模连接串。在部署中，该值将被提示并保存到安全的位置。
当本地运行的时候，该值将通过 app host 的配置中的 ConnectionString 配置节中读取出来。
注意
连接串用来表示广义的连接信息，包括数据库连接串，消息中间件，以及其它服务。
在 .NET Aspire 的命名方式中，术语 connection string 用来表示任意类型的连接信息。
考虑如下的 app host 的 Program.cs 示例
var builder = DistributedApplication.CreateBuilder(args);
var redis = builder.AddConnectionString("redis");
builder.AddProject<Projects.WebApplication1>("api")
.WithReference(redis);
builder.Build().Run();
相应的 app host 的 appsettings.json 如下所示
{
"ConnectionStrings": {
"redis": "local-connection-string"
}
}
清单表示如下所示
{
"resources": {
"redis": {
"type": "parameter.v0",
"connectionString": "{redis.value}",
"value": "{redis.inputs.value}",
"inputs": {
"value": {
"type": "string",
"secret": true
}
}
}
}
}
Parameter 示例
为了表示 Parameter，考虑如下的示例代码：
var builder = DistributedApplication.CreateBuilder(args);
var db = builder.AddSqlServer("sql")
.PublishAsConnectionString()
.AddDatabase("db");
var insertionRows = builder.AddParameter("insertionRows");
builder.AddProject<Projects.Parameters_ApiService>("api")
.WithEnvironment("InsertionRows", insertionRows)
.WithReference(db);
builder.Build().Run();
实际执行如下步骤：
- 添加了名为 sql 的 SQL Server 资源，并发布为数据库连接串
- 添加了名为 db 的数据库
- 添加了名为 insertionRows 的 Parameter
- 添加了名为 api 的项目，将其关联到项目 Projects.Parameters_ApiService 项目资源类型参数上
- 将参数 insertionRows 传递给 api 项目
- 引用 db 数据库
其中的 insertionRows 参数从 app host 的 appsettings.json 中的 Parameters 配置节中读取。
{
"Logging": {
"LogLevel": {
"Default": "Information",
"Microsoft.AspNetCore": "Warning",
"Aspire.Hosting.Dcp": "Warning"
}
},
"Parameters": {
"insertionRows": "1"
}
}
而 Parameters_ApiService 项目消费该 insertionRows 参数，考虑 apiService 项目中的 Program.cs 代码
using Microsoft.EntityFrameworkCore;
var builder = WebApplication.CreateBuilder(args);
int insertionRows = builder.Configuration.GetValue<int>("InsertionRows", 1);
builder.AddServiceDefaults();
builder.AddSqlServerDbContext<MyDbContext>("db");
var app = builder.Build();
app.MapGet("/", async (MyDbContext context) =>
{
// You wouldn't normally do this on every call,
// but doing it here just to make this simple.
context.Database.EnsureCreated();
for (var i = 0; i < insertionRows; i++)
{
var entry = new Entry();
await context.Entries.AddAsync(entry);
}
await context.SaveChangesAsync();
var entries = await context.Entries.ToListAsync();
return new
{
totalEntries = entries.Count,
entries
};
});
app.Run();
