External parameters

2025-07-29

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

Parameter values

参数值是从应用主机配置 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"

Important

但是，无需在应用主机中自行访问此配置值。相反，ParameterResource 用于将参数值传递给依赖资源。通常作为环境变量。

提示在仪表板中输入参数值

如果代码添加参数但未设置参数，则会在仪表板中看到 .NET.NET Aspire 配置其值的提示。此时会显示 “未解决的参数 ”消息，可以选择 Enter 值 来解决该问题：

选择 输入值时，.NET.NET Aspire 将显示一个用于配置每个缺失参数值的窗体。

还可以使用以下方法控制仪表板如何显示这些参数：

WithDescription：使用此方法提供有助于用户了解参数用途的文本说明。
WithMarkdownDescription：使用此方法在 Markdown 中提供格式化说明，用于说明参数的意图。
WithCustomInput：使用此方法提供自定义参数对话框的回调方法。例如，在此回调中，可以自定义默认值、输入类型、标签和占位符文本。

此代码演示如何设置说明并使用回调：

#pragma warning disable ASPIREINTERACTION001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
var externalServiceUrl = builder.AddParameter("external-service-url")
    .WithDescription("The URL of the external service.")
    .WithCustomInput(p => new()
    {
        InputType = InputType.Text,
#pragma warning restore ASPIREINTERACTION001
        Value = "https://example.com",
        Label = p.Name,
        Placeholder = $"Enter value for {p.Name}",
        Description = p.Description
    });
var externalService = builder.AddExternalService("external-service", externalServiceUrl);

代码在仪表板中呈现此控件：

Note

仪表板参数对话框包括 “保存到用户机密 ”复选框。选择此选项可将敏感值存储在 AppHost 的用户机密中，以便进行额外保护。有关机密参数值的详细信息，请参阅机密值。

清单中参数的表示形式

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

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

Secret values

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

Note

连接字符串用于表示各种连接信息，包括数据库连接、消息代理、终结点 URI 和其他服务。在 .NET.NET Aspire 名词中，术语“连接字符串”用于表示任何类型的连接信息。

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Note

与连接字符串一起使用WaitFor时，将会隐式等待该连接字符串要连接的资源。

现在，请考虑以下应用主机配置文件 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);

Parameter example

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

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();

通过

External parameters

Parameter values

配置参数值

提示在仪表板中输入参数值

清单中参数的表示形式

Secret values

连接字符串值

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

Parameter example

See also

反馈

其他资源