External parameters

環境は、アプリケーションを実行するためのコンテキストを提供します。 パラメーターは、アプリの実行時に外部値を要求する機能を表します。 パラメーターを使用すると、ローカルで実行するときにアプリに値を提供したり、デプロイ時に値の入力を求めたりすることができます。 これらは、シークレット、接続文字列、環境によって異なる可能性があるその他の構成値など、さまざまなシナリオをモデル化するために使用できます。

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 プロジェクトに渡されます。

パラメーター値の構成

ビルダーへのパラメーターの追加は、構成の 1 つの側面にすぎません。 パラメーターの値も指定する必要があります。 この値は、アプリ ホスト構成ファイルで指定したり、ユーザー シークレットとして設定したり、他の標準構成構成したりできます。 パラメーター値が見つからない場合は、アプリを実行または発行するときにパラメーター値の入力を求められます。

次のアプリ ホスト構成ファイル 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 ダッシュボードに値を構成するためのプロンプトが表示されます。 [未解決のパラメーター] メッセージが表示され、[値の入力] を選択して問題を解決できます。

[値の 入力] を選択すると、 .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);

このコードは、このコントロールをダッシュボードに表示します。

マニフェストでのパラメーター表現

.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 セクションから値が読み取られます。

次のアプリ ホスト 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);

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

See also

• .NET .NET Aspire 配置ツールビルダー向けのマニフェスト形式
• ASP.NET Core を使用して SQL Server アプリを .NET Aspire に接続する