Bagikan melalui

Parameter eksternal

Lingkungan menyediakan konteks untuk menjalankan aplikasi. Parameter mengekspresikan kemampuan untuk meminta nilai eksternal saat menjalankan aplikasi. Parameter dapat digunakan untuk memberikan nilai ke aplikasi saat berjalan secara lokal, atau untuk meminta nilai saat menyebarkan. Mereka dapat digunakan untuk memodelkan berbagai skenario termasuk rahasia, string koneksi, dan nilai konfigurasi lainnya yang mungkin bervariasi di antara lingkungan.

Nilai parameter

Nilai parameter dibaca dari bagian Parameters konfigurasi host aplikasi dan digunakan untuk memberikan nilai ke aplikasi saat berjalan secara lokal. Saat Memublikasikan aplikasi, jika nilai tidak dikonfigurasi, Anda akan diminta untuk menyediakannya.

Pertimbangkan contoh file host aplikasi Program.cs berikut:

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

Kode sebelumnya menambahkan parameter bernama example-parameter-name ke host aplikasi. Parameter kemudian diteruskan ke proyek Projects.ApiService sebagai variabel lingkungan bernama ENVIRONMENT_VARIABLE_NAME.

Konfigurasikan nilai parameter

Menambahkan parameter ke pembangun hanyalah satu aspek konfigurasi. Anda juga harus memberikan nilai untuk parameter . Nilai dapat disediakan dalam file konfigurasi host aplikasi, diatur sebagai rahasia pengguna, atau dikonfigurasi dalam konfigurasi standar lainnya. Saat nilai parameter tidak ditemukan, pengguna akan diminta untuk memasukkannya saat menerbitkan aplikasi.

Pertimbangkan file konfigurasi host aplikasi berikut appsettings.json:

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

JSON sebelumnya mengatur suatu parameter di bagian Parameters dari konfigurasi host aplikasi. Dengan kata lain, host aplikasi tersebut dapat menemukan parameter sebagaimana dikonfigurasikan. Misalnya, Anda dapat berjalan ke IDistributedApplicationBuilder.Configuration dan mengakses nilai menggunakan kunci Parameters:example-parameter-name:

var builder = DistributedApplication.CreateBuilder(args);

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

Penting

Namun, Anda tidak perlu mengakses nilai konfigurasi ini sendiri di host aplikasi. Sebagai gantinya, ParameterResource digunakan untuk meneruskan nilai parameter ke sumber daya dependen. Paling sering sebagai variabel lingkungan.

Representasi parameter dalam manifes

.NET .NET Aspire menggunakan manifes penyebaran untuk mewakili sumber daya aplikasi dan hubungannya. Parameter diwakili dalam manifes sebagai primitif baru yang disebut parameter.v0:

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

Nilai rahasia

Parameter dapat digunakan untuk memodelkan rahasia. Ketika parameter ditandai sebagai rahasia, parameter berfungsi sebagai petunjuk untuk manifes bahwa nilai harus diperlakukan sebagai rahasia. Ketika Anda menerbitkan aplikasi, nilai akan diminta dan disimpan di lokasi yang aman. Saat Anda menjalankan aplikasi secara lokal, nilai dibaca dari bagian Parameters konfigurasi host aplikasi.

Pertimbangkan contoh file host aplikasi Program.cs berikut:

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

Sekarang pertimbangkan file konfigurasi host aplikasi berikut appsettings.json:

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

Representasi manifes adalah sebagai berikut:

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

Nilai string sambungan

Parameter dapat digunakan untuk memodelkan string koneksi. Ketika Anda menerbitkan aplikasi, nilai akan diminta dan disimpan di lokasi yang aman. Saat Anda menjalankan aplikasi secara lokal, nilai dibaca dari bagian ConnectionStrings konfigurasi host aplikasi.

Nota

String koneksi digunakan untuk mewakili berbagai informasi koneksi, termasuk koneksi database, broker pesan, URI titik akhir, dan layanan lainnya. Dalam nomenklatur .NET.NET Aspire, istilah "string koneksi" digunakan untuk mewakili segala jenis informasi koneksi.

Pertimbangkan contoh file host aplikasi Program.cs berikut:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Nota

Menggunakan WaitFor dengan string koneksi akan secara implisit menunggu sumber daya tempat string koneksi tersambung.

Sekarang pertimbangkan file konfigurasi host aplikasi berikut appsettings.json:

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

Untuk informasi selengkapnya yang berkaitan dengan string koneksi dan representasinya dalam manifes penyebaran, lihat String koneksi dan referensi pengikatan.

Membangun string koneksi dengan ekspresi referensi

Jika Anda ingin membuat string koneksi dari parameter dan memastikan bahwa string tersebut ditangani dengan benar dalam pengembangan dan produksi, gunakan AddConnectionString dengan ReferenceExpression.

Misalnya, jika Anda memiliki parameter rahasia yang menyimpan sebagian kecil string koneksi, gunakan kode ini untuk menyisipkannya:

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

Anda juga dapat menggunakan ekspresi referensi untuk menambahkan teks ke string koneksi yang dibuat oleh .NET.NET Aspire sumber daya. Misalnya, saat Anda menambahkan PostgreSQL sumber daya ke solusi Anda .NET Aspire , server database berjalan dalam kontainer dan string koneksi diformulasikan untuk itu. Dalam kode berikut, properti tambahan Include Error Details ditambahkan ke string koneksi tersebut sebelum diteruskan ke proyek yang memanfaatkannya.

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

Contoh parameter

Untuk mengekspresikan parameter, pertimbangkan contoh kode berikut:

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

Langkah-langkah berikut dilakukan:

  • Menambahkan sumber daya SQL Server bernama sql dan menerbitkannya sebagai string koneksi.
  • Menambahkan database bernama db.
  • Menambahkan parameter bernama insertionRows.
  • Menambahkan proyek bernama api dan mengaitkannya dengan parameter jenis sumber daya proyek Projects.Parameters_ApiService.
  • Meneruskan parameter insertionRows ke proyek api.
  • Merujuk ke database db.

Nilai untuk parameter insertionRows dibaca dari bagian Parameters file konfigurasi host aplikasi appsettings.json:

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

Proyek Parameters_ApiService menggunakan parameter insertionRows. Pertimbangkan file contoh 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();

Lihat juga