Freigeben über

Externe Parameter

Umgebungen bieten Kontext für die Ausführung der Anwendung. Parameter geben die Möglichkeit zum Anfordern eines externen Werts beim Ausführen der App an. Parameter können verwendet werden, um Werte für die App bereitzustellen, wenn sie lokal ausgeführt wird, oder um bei der Bereitstellung nach Werten zu fragen. Sie können verwendet werden, um eine vielzahl von Szenarien zu modellieren, einschließlich geheimer Schlüssel, Verbindungszeichenfolgen und anderer Konfigurationswerte, die zwischen Umgebungen variieren können.

Parameterwerte

Parameterwerte werden aus dem Abschnitt Parameters der Konfiguration des App-Hosts ausgelesen und genutzt, um der App beim lokalen Ausführen Werte zur Verfügung zu stellen. Wenn Sie die App veröffentlichen, und der Wert nicht konfiguriert ist, werden Sie aufgefordert, ihn anzugeben.

Betrachten Sie die folgende Beispiel-App-Host-Program.cs-Datei:

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

Der vorangehende Code fügt dem App-Host einen Parameter namens example-parameter-name hinzu. Der Parameter wird dann als Umgebungsvariable namens Projects.ApiServicean das ENVIRONMENT_VARIABLE_NAME Projekt übergeben.

Konfigurieren von Parameterwerten

Das Hinzufügen von Parametern zum Builder ist nur ein Aspekt der Konfiguration. Sie müssen auch den Wert für den Parameter angeben. Der Wert kann in der Konfigurationsdatei für den App-Host bereitgestellt, als geheimer Benutzer festgelegt oder in einer beliebigen anderen Standardkonfigurationkonfiguriert werden. Wenn Parameterwerte nicht gefunden werden, wird beim Veröffentlichen der App nach ihnen gefragt.

Betrachten Sie die folgende Konfigurationsdatei für den App-Host appsettings.json:

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

Der vorherige JSON konfiguriert einen Parameter im Abschnitt Parameters der App-Hostkonfiguration. Mit anderen Worten, dieser Anwendungshost kann den Parameter wie konfiguriert finden. Zum Beispiel können Sie zum IDistributedApplicationBuilder.Configuration gehen und mit dem Parameters:example-parameter-name-Schlüssel auf den Wert zugreifen.

var builder = DistributedApplication.CreateBuilder(args);

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

Von Bedeutung

Sie müssen jedoch nicht selbst auf diesen Konfigurationswert im App-Host zugreifen. Stattdessen wird der ParameterResource verwendet, um den Parameterwert an abhängige Ressourcen zu übergeben. Meistens als Umgebungsvariable.

Parameterdarstellung im Manifest

.NET .NET Aspire verwendet ein Bereitstellungsmanifest, um die Ressourcen der App und deren Beziehungen darzustellen. Parameter werden im Manifest als neuer Grundtyp namens parameter.v0dargestellt:

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

Geheime Werte

Parameter können verwendet werden, um Geheimnisse zu modellieren. Wenn ein Parameter als geheim markiert ist, dient er als Hinweis für das Manifest, dass der Wert als Geheimnis behandelt werden soll. Wenn Sie die App veröffentlichen, wird der Wert abgefragt und an einem sicheren Speicherort gespeichert. Wenn Sie die App lokal ausführen, wird der Wert aus dem Abschnitt Parameters der App-Hostkonfiguration gelesen.

Betrachten Sie die folgende Beispiel-App-Host-Program.cs-Datei:

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

Betrachten Sie nun die folgende App-Hostkonfigurationsdatei appsettings.json:

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

Die Darstellung des Manifests lautet wie folgt:

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

Verbindungszeichenfolgen-Werte

Parameter können zum Modellieren von Verbindungszeichenfolgen verwendet werden. Wenn Sie die App veröffentlichen, wird der Wert abgefragt und an einem sicheren Speicherort gespeichert. Wenn Sie die App lokal ausführen, wird der Wert aus dem Abschnitt ConnectionStrings der App-Hostkonfiguration gelesen.

Anmerkung

Verbindungszeichenfolgen werden verwendet, um eine vielzahl von Verbindungsinformationen darzustellen, einschließlich Datenbankverbindungen, Nachrichtenbroker, Endpunkt-URIs und anderen Diensten. In der .NET.NET Aspire Nomenklatur wird der Begriff "Verbindungsstring" verwendet, um jede Art von Verbindungsinformationen darzustellen.

Betrachten Sie die folgende Beispiel-App-Host-Program.cs-Datei:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Anmerkung

Die Verwendung WaitFor mit einer Verbindungszeichenfolge wartet implizit auf die Ressource, mit der die Verbindungszeichenfolge eine Verbindung herstellt.

Betrachten Sie nun die folgende App-Hostkonfigurationsdatei appsettings.json:

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

Weitere Informationen zu Verbindungszeichenfolgen und deren Darstellung im Bereitstellungsmanifest finden Sie unter "Verbindungszeichenfolge und Bindungsverweise".

Erstellen von Verbindungszeichenfolgen mit Referenzausdrücken

Wenn Sie eine Verbindungszeichenfolge aus Parametern erstellen und sicherstellen möchten, dass sie sowohl in der Entwicklung als auch in der Produktion korrekt behandelt wird, verwenden Sie dies AddConnectionString mit einer ReferenceExpression.

Wenn Sie beispielsweise über einen geheimen Parameter verfügen, der einen kleinen Teil einer Verbindungszeichenfolge speichert, verwenden Sie diesen Code, um ihn einzufügen:

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

Sie können auch Verweisausdrücke verwenden, um Text an Verbindungszeichenfolgen anzufügen, die von .NET.NET Aspire Ressourcen erstellt wurden. Wenn Sie beispielsweise eine PostgreSQL Ressource zu Ihrer .NET Aspire Lösung hinzufügen, wird der Datenbankserver in einem Container ausgeführt, und dann wird eine Verbindungszeichenfolge dafür erstellt. Im folgenden Code wird die zusätzliche Eigenschaft Include Error Details an diese Verbindungszeichenfolge angehängt, bevor sie an die verbrauchenden Projekte übergeben wird.

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

Parameterbeispiel

Um einen Parameter auszudrücken, berücksichtigen Sie den folgenden Beispielcode:

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

Die folgenden Schritte werden ausgeführt:

  • Fügt eine SQL Server Ressource namens sql hinzu und veröffentlicht sie als Verbindungszeichenfolge.
  • Fügt eine Datenbank mit dem Namen dbhinzu.
  • Fügt einen Parameter namens insertionRowshinzu.
  • Fügt ein Projekt mit dem Namen api hinzu und ordnet es dem Projects.Parameters_ApiService Projektressourcentypparameter zu.
  • Übergibt den Parameter insertionRows an das Projekt api.
  • Verweist auf die db-Datenbank.

Der Wert für den parameter insertionRows wird aus dem abschnitt Parameters der App-Hostkonfigurationsdatei appsettings.jsongelesen:

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

Parameters_ApiService Projekt konsumiert den insertionRows Parameter. Betrachten Sie die Beispieldatei 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();

Siehe auch