Externe parameters

Omgevingen bieden context waarin de toepassing kan worden uitgevoerd. Parameters geven de mogelijkheid om bij het uitvoeren van de app om een externe waarde te vragen. Parameters kunnen worden gebruikt om waarden aan de app op te geven wanneer ze lokaal worden uitgevoerd of om te vragen om waarden bij de implementatie. Ze kunnen worden gebruikt om een breed scala aan scenario's te modelleren, waaronder geheimen, verbindingsreeksen en andere configuratiewaarden die kunnen variëren tussen omgevingen.

Parameterwaarden

Parameterwaarden worden gelezen uit de Parameters sectie van de configuratie van AppHost en worden gebruikt om waarden aan de app op te geven terwijl ze lokaal worden uitgevoerd. Wanneer u de app uitvoert of publiceert, wordt u gevraagd deze op te geven als de waarde niet is geconfigureerd.

Bekijk het volgende apphost-voorbeeldbestand AppHost.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);

Met de voorgaande code wordt een parameter met de naam example-parameter-name toegevoegd aan de AppHost. De parameter wordt vervolgens doorgegeven aan het Projects.ApiService project als een omgevingsvariabele met de naam ENVIRONMENT_VARIABLE_NAME.

Parameterwaarden configureren

Het toevoegen van parameters aan de opbouwfunctie is slechts één aspect van de configuratie. U moet ook de waarde voor de parameter opgeven. De waarde kan worden opgegeven in het AppHost-configuratiebestand, ingesteld als een gebruikersgeheim of geconfigureerd in een andere standaardconfiguratie. Wanneer parameterwaarden niet worden gevonden, wordt er om gevraagd wanneer u de app uitvoert of publiceert.

Overweeg het volgende AppHost-configuratiebestand appsettings.json:

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

In het voorgaande JSON wordt een parameter geconfigureerd in de Parameters sectie van de AppHost-configuratie. Met andere woorden, dat AppHost de parameter kan vinden terwijl deze is geconfigureerd. U kunt bijvoorbeeld naar de IDistributedApplicationBuilder.Configuration lopen en toegang krijgen tot de waarde met behulp van de Parameters:example-parameter-name-sleutel:

var builder = DistributedApplication.CreateBuilder(args);

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

Vragen om parameterwaarden in het dashboard

Als uw code parameters toevoegt, maar deze niet instelt, ziet u een prompt om de waarden in het Aspire dashboard te configureren. Het bericht Niet-opgeloste parameters wordt weergegeven en u kunt Waarden invoeren selecteren om het probleem op te lossen:

Wanneer u Waarden invoeren selecteert, Aspire wordt een formulier weergegeven dat u kunt gebruiken om waarden te configureren voor elk van de ontbrekende parameters.

U kunt ook bepalen hoe deze parameters in het dashboard worden weergegeven met behulp van deze methoden:

• WithDescription: Gebruik deze methode om een tekstbeschrijving op te geven waarmee gebruikers het doel van de parameter kunnen begrijpen. Als u een opgemaakte beschrijving in Markdown wilt opgeven, gebruikt u de enableMarkdown: true parameter.
• WithCustomInput: Gebruik deze methode om een callback-methode op te geven waarmee het parameterdialoogvenster wordt aangepast. In deze callback kunt u bijvoorbeeld de standaardwaarde, het invoertype, het label en de tekst van de tijdelijke aanduiding aanpassen.

Deze code laat zien hoe u een beschrijving instelt en de callback gebruikt:

#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,
        Value = "https://example.com",
        Name = p.Name,
        Placeholder = $"Enter value for {p.Name}",
        Description = p.Description
    });
var externalService = builder.AddExternalService("external-service", externalServiceUrl);

#pragma warning restore ASPIREINTERACTION001

De code geeft dit besturingselement weer in het dashboard:

Parameterweergave in het manifest

Aspire gebruikt een implementatiemanifest om de resources en de bijbehorende relaties van de app weer te geven. Parameters worden in het manifest weergegeven als een nieuwe primitieve met de naam parameter.v0:

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

Geheime waarden

Parameters kunnen worden gebruikt om geheimen te modelleren. Wanneer een parameter wordt gemarkeerd als een geheim, fungeert deze als hint voor het manifest dat de waarde moet worden behandeld als een geheim. Wanneer u de app publiceert, wordt er om de waarde gevraagd en deze wordt opgeslagen op een veilige locatie. Wanneer u de app lokaal uitvoert, wordt de waarde gelezen uit de Parameters sectie van de AppHost-configuratie.

Bekijk het volgende apphost-voorbeeldbestand AppHost.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();

Overweeg nu het volgende AppHost-configuratiebestand appsettings.json:

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

De manifestweergave is als volgt:

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

Verbindingsreekswaarden

Parameters kunnen worden gebruikt om verbindingsreeksen te modelleren. Wanneer u de app publiceert, wordt er om de waarde gevraagd en deze wordt opgeslagen op een veilige locatie. Wanneer u de app lokaal uitvoert, wordt de waarde gelezen uit de ConnectionStrings sectie van de AppHost-configuratie.

Bekijk het volgende apphost-voorbeeldbestand AppHost.cs :

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Overweeg nu het volgende AppHost-configuratiebestand appsettings.json:

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

Zie Verbindingsreeks en bindingverwijzingenvoor meer informatie over verbindingsreeksen en hun weergave in het implementatiemanifest.

Verbindingsreeksen bouwen met verwijzingsexpressies

Als u een verbindingsreeks wilt maken op basis van parameters en ervoor wilt zorgen dat deze correct wordt verwerkt in zowel ontwikkeling als productie, gebruikt u AddConnectionString met een ReferenceExpression.

Als u bijvoorbeeld een geheime parameter hebt waarin een klein deel van een verbindingsreeks wordt opgeslagen, gebruikt u deze code om deze in te voegen:

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

U kunt ook verwijzingsexpressies gebruiken om tekst toe te voegen aan verbindingsreeksen die door Aspire resources zijn gemaakt. Wanneer u bijvoorbeeld een PostgreSQL resource aan uw Aspire oplossing toevoegt, wordt de databaseserver uitgevoerd in een container en wordt er een verbindingsreeks voor geformuleerd. In de volgende code wordt de extra eigenschap Include Error Details aan die verbindingsreeks toegevoegd voordat deze aan consumerende projecten wordt doorgegeven.

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

Parametervoorbeeld

Als u een parameter wilt uitdrukken, bekijkt u de volgende voorbeeldcode:

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

De volgende stappen worden uitgevoerd:

• Voegt een SQL Server resource met de naam sql toe en publiceert deze als een verbindingsreeks.
• Hiermee wordt een database met de naam dbtoegevoegd.
• Hiermee voegt u een parameter toe met de naam insertionRows.
• Hiermee voegt u een project toe met de naam api en koppelt u het aan de Projects.Parameters_ApiService projectresourcetypeparameter.
• Geeft de parameter insertionRows door aan het api-project.
• Verwijst naar de db-database.

De waarde voor de insertionRows parameter wordt gelezen uit de Parameters sectie van het AppHost-configuratiebestand appsettings.json:

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

Het Parameters_ApiService-project gebruikt de parameter insertionRows. Bekijk het Program.cs voorbeeldbestand:

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

Zie ook

• Aspire manifestindeling voor opbouwfuncties voor implementatieprogramma's
• Zelfstudie: Een ASP.NET Core-app verbinden met SQL Server met behulp van Aspire en Entity Framework Core