外部パラメーター

[アーティクル]
12/15/2024

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

パラメーター値

パラメーター値は、アプリホストの構成の 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 プロジェクトに渡されます。

パラメーター値の構成

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

次のアプリホスト構成ファイル 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 プロジェクトリソースの型パラメーターに関連付けます。
api プロジェクトに insertionRows パラメーターを渡します。
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();

次の方法で共有

外部パラメーター

パラメーター値

パラメーター値の構成

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

シークレット値

接続文字列の値

パラメーターの例

関連項目

その他のリソース