共用方式為

外部參數

  • 發行項

環境會提供應用程式運行的背景。 參數表示在執行應用程式時要求外部值的能力。 參數可用來在本機執行時提供值給應用程式，或在部署時提示值。 它們可用來建立各種案例的模型，包括秘密、連接字串和其他可能因環境而異的組態值。

參數值

參數值會從應用程式主機組態的 Parameters 區段讀取，並用來在本機執行時提供值給應用程式。 當您發佈應用程式時，如果未設定值，系統會提示您提供它。

請考慮下列應用程式主機 Program.cs 檔案範例：

var builder = DistributedApplication.CreateBuilder(args);

// Add a parameter named "value"
var value = builder.AddParameter("value");

builder.AddProject<Projects.ApiService>("api")
       .WithEnvironment("EXAMPLE_VALUE", value);

上述程式代碼會將名為 value 的參數新增至應用程式主機。 然後，參數會以名為 EXAMPLE_VALUE的環境變數的形式傳遞至 Projects.ApiService 專案。

設定參數值

將參數新增至產生器只是組態的一個層面。 您也必須提供 參數的值。 這個值可在應用程式主機組態檔中提供、設定為使用者密碼，或在任何 其他標準組態中設定。 當找不到參數值時，系統會在發佈應用程式時提示它們。

請考慮下列應用程式主機組態檔 appsettings.json：

{
    "Parameters": {
        "value": "local-value"
    }
}

上述 JSON 會在應用程式主機組態的 Parameters 區段中設定參數。 換句話說，該應用程式主機能夠找到其設定的參數。 例如，您可以走到 IDistributedApplicationBuilder.Configuration 並使用 Parameters:value 鍵來訪問值：

var builder = DistributedApplication.CreateBuilder(args);

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

重要

不過，您不需要在應用程式主機中自行存取此組態值。 相反地，ParameterResource 會用來將參數值傳遞至相依資源。 最常做為環境變數。

指令清單中的參數表示法

.NET .NET Aspire 使用 部署指令清單 來表示應用程式的資源及其關聯性。 參數會在清單檔中表示為名為 parameter.v0的新原始類型：

{
  "resources": {
    "value": {
      "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] 區段讀取值。

注意

連接字串可用來代表各種連線資訊，包括資料庫連接、訊息代理程式、端點 URI 和其他服務。 在 .NET.NET Aspire 名詞中，「連接字串」一詞用來代表任何類型的連接資訊。

請考慮下列應用程式主機 Program.cs 檔案範例：

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

現在，請考慮下列應用程式主機組態檔 appsettings.json：

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

如需有關連接字串及其在部署指令清單中表示的詳細資訊，請參閱 連接字串和系結參考。

參數範例

若要表示參數，請考慮下列範例程式代碼：

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的參數。
  • 新增名為 api 的專案，並將它與 Projects.Parameters_ApiService 專案資源類型參數產生關聯。
  • 將 insertionRows 參數傳遞至 api 專案。
  • 參考 db 資料庫。

從應用程式主機組態檔的 Parameters 區段讀取 insertionRows 參數的值 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();

另請參閱