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 "value"
var value = builder.AddParameter("value");

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

Der vorangehende Code fügt dem App-Host einen Parameter namens value hinzu. Der Parameter wird dann als Umgebungsvariable namens EXAMPLE_VALUEan das Projects.ApiService 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": {
        "value": "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:value-Schlüssel auf den Wert zugreifen.

var builder = DistributedApplication.CreateBuilder(args);

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

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": {
    "value": {
      "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-Datei 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();

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 aufgefordert und an einem sicheren Speicherort gespeichert. Wenn Sie die App lokal ausführen, wird der Wert aus dem Abschnitt ConnectionStrings der App-Hostkonfiguration gelesen.

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

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

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".

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

• .NET .NET Aspire Manifestformat für Ersteller von Bereitstellungstools
• Lernprogramm: Verbinden einer ASP.NET Core-App mit SQL Server mithilfe von .NET Aspire und Entity Framework Core