外部参数

环境为要在其中运行的应用程序提供上下文。 参数表示在运行应用时请求外部值的能力。 参数可用于在本地运行时向应用提供值，或者在部署时提示值。 它们可用于为各种方案建模，包括机密、连接字符串和其他可能因环境而异的配置值。

参数值

参数值是从应用主机配置 Parameters 部分读取的，用于在本地运行时向应用提供值。 发布应用时，如果未配置该值，系统会提示你提供它。

请考虑以下示例应用主机 Program.cs 文件：

var builder = DistributedApplication.CreateBuilder(args);

// Add a parameter named "example-parameter-name"
var parameter = builder.AddParameter("example-parameter-name");

builder.AddProject<Projects.ApiService>("api")
       .WithEnvironment("ENVIRONMENT_VARIABLE_NAME", parameter);

前面的代码将名为 example-parameter-name 的参数添加到应用主机。 然后将该参数作为名为 Projects.ApiService的环境变量传递给 ENVIRONMENT_VARIABLE_NAME 项目。

配置参数值

向生成器添加参数只是配置的一个方面。 还必须提供参数的值。 可以在应用主机配置文件中提供该值，将其设置为用户密码，或在 其他标准配置进行配置。 如果未找到参数值，则会在发布应用时请求输入这些值。

请考虑以下应用主机配置文件 appsettings.json：

{
    "Parameters": {
        "example-parameter-name": "local-value"
    }
}

前面的 JSON 在应用主机配置的 Parameters 部分中配置参数。 换句话说，该应用主机能够找到其配置的参数。 例如，你可以访问 IDistributedApplicationBuilder.Configuration，并使用 Parameters:example-parameter-name 键访问该值：

var builder = DistributedApplication.CreateBuilder(args);

var key = $"Parameters:example-parameter-name";
var value = builder.Configuration[key]; // value = "local-value"

清单中参数的表示形式

.NET .NET Aspire 使用 部署清单 来表示应用的资源及其关系。 参数在清单中表示为名为 parameter.v0的新基元：

{
  "resources": {
    "example-parameter-name": {
      "type": "parameter.v0",
      "value": "{value.inputs.value}",
      "inputs": {
        "value": {
          "type": "string"
        }
      }
    }
  }
}

机密值

参数可用于为机密建模。 将参数标记为机密时，它将作为清单的提示，指示值应被视为机密。 发布应用时，系统会提示该值并将其存储在安全位置。 在本地运行应用时，将从应用主机配置的 Parameters 部分读取该值。

请考虑以下示例应用主机 Program.cs 文件：

var builder = DistributedApplication.CreateBuilder(args);

// Add a secret parameter named "secret"
var secret = builder.AddParameter("secret", secret: true);

builder.AddProject<Projects.ApiService>("api")
       .WithEnvironment("SECRET", secret);

builder.Build().Run();

现在，请考虑以下应用主机配置文件 appsettings.json：

{
    "Parameters": {
        "secret": "local-secret"
    }
}

清单表示形式如下所示：

{
  "resources": {
    "value": {
      "type": "parameter.v0",
      "value": "{value.inputs.value}",
      "inputs": {
        "value": {
          "type": "string",
          "secret": true
        }
      }
    }
  }
}

连接字符串值

参数可用于为连接字符串建模。 发布应用时，系统会提示该值并将其存储在安全位置。 在本地运行应用时，将从应用主机配置的 ConnectionStrings 部分读取该值。

请考虑以下示例应用主机 Program.cs 文件：

var builder = DistributedApplication.CreateBuilder(args);

var redis = builder.AddConnectionString("redis");

builder.AddProject<Projects.WebApplication>("api")
       .WithReference(redis)
       .WaitFor(redis);

builder.Build().Run();

现在，请考虑以下应用主机配置文件 appsettings.json：

{
    "ConnectionStrings": {
        "redis": "local-connection-string"
    }
}

有关连接字符串及其在部署清单中的表示形式的详细信息，请参阅 连接字符串和绑定引用。

使用引用表达式生成连接字符串

如果要从参数构造连接字符串，并确保其在开发和生产中都能正确处理，请将AddConnectionString与ReferenceExpression一起使用。

例如，如果你有一个存储连接字符串的一小部分的机密参数，请使用以下代码插入它：

var secretKey = builder.AddParameter("secretkey", secret: true);

var connectionString = builder.AddConnectionString(
    "composedconnectionstring",
    ReferenceExpression.Create($"Endpoint=https://api.contoso.com/v1;Key={secretKey}"));

builder.AddProject<Projects.AspireReferenceExpressions_CatalogAPI>("catalogapi")
       .WithReference(connectionString)
       .WaitFor(connectionString);

还可以使用引用表达式将文本追加到资源 .NET.NET Aspire 创建的连接字符串。 例如，将资源添加到PostgreSQL.NET Aspire解决方案时，数据库服务器在容器中运行，并为其制定了连接字符串。 在以下代码中，附加属性 Include Error Details 将追加到该连接字符串，然后再将其传递给使用项目：

var postgres = builder.AddPostgres("postgres");
var database = postgres.AddDatabase("db");

var pgConnectionString = builder.AddConnectionString(
    "pgdatabase",
    ReferenceExpression.Create($"{database};Include Error Details=true"));

builder.AddProject<Projects.AspireReferenceExpressions_CustomerAPI>("customerapi")
       .WithReference(pgConnectionString)
       .WaitFor(pgConnectionString);

参数示例

若要表达参数，请考虑以下示例代码：

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 Server 的 sql 资源，并将其发布为连接字符串。
• 添加名为 db的数据库。
• 添加名为 insertionRows的参数。
• 添加一个名为 api 的项目，并将其与 Projects.Parameters_ApiService 项目资源类型参数相关联。
• 将 insertionRows 参数传递给 api 项目。
• 引用 db 数据库。

从应用主机配置文件的 insertionRows 部分读取 Parameters 参数的值：appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Aspire.Hosting.Dcp": "Warning"
    }
  },
  "Parameters": {
    "insertionRows": "1"
  }
}

Parameters_ApiService 项目使用 insertionRows 参数。 请考虑 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();

另请参阅

• 部署工具生成器 的 清单格式
• ASP.NET Core 将 SQL Server 应用连接到 .NET Aspire