Externe parameters

Artikel
12/13/2024

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 sectie Parameters van de configuratie van de app-host en worden gebruikt om waarden voor de app op te geven terwijl ze lokaal worden uitgevoerd. Wanneer u de app publiceert en de waarde niet is geconfigureerd, wordt u gevraagd deze op te geven.

Bekijk het volgende voorbeeld van het app-hostbestand 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);

Met de voorgaande code wordt een parameter met de naam value toegevoegd aan de app-host. De parameter wordt vervolgens doorgegeven aan het Projects.ApiService project als een omgevingsvariabele met de naam EXAMPLE_VALUE.

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 configuratiebestand van de app-host, ingesteld als een gebruikersgeheim of geconfigureerd in een andere standaardconfiguratie. Wanneer parameterwaarden niet worden gevonden, wordt er om gevraagd tijdens het publiceren van de app.

Houd rekening met het volgende configuratiebestand voor de app-host appsettings.json:

{
    "Parameters": {
        "value": "local-value"
    }
}

De voorgaande JSON configureert een parameter in de sectie Parameters van de configuratie van de app-host. Met andere woorden, die app-host kan de parameter vinden zoals geconfigureerd. U kunt bijvoorbeeld naar de IDistributedApplicationBuilder.Configuration lopen en toegang krijgen tot de waarde met behulp van de Parameters:value-sleutel:

var builder = DistributedApplication.CreateBuilder(args);

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

Belangrijk

U hoeft echter geen toegang te krijgen tot deze configuratiewaarde zelf in de app-host. In plaats daarvan wordt de ParameterResource gebruikt om de parameterwaarde door te geven aan afhankelijke resources. Meestal als omgevingsvariabele.

Parameterweergave in het manifest

.NET .NET 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": {
    "value": {
      "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 sectie Parameters van de configuratie van de app-host.

Bekijk het volgende voorbeeld van app-hostbestand 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();

Overweeg nu het volgende configuratiebestand voor de app-host 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 om de waarde gevraagd en wordt deze opgeslagen op een veilige locatie. Wanneer u de app lokaal uitvoert, wordt de waarde gelezen uit de sectie ConnectionStrings van de configuratie van de app-host.

Notitie

Verbindingsreeksen worden gebruikt om een breed scala aan verbindingsgegevens weer te geven, waaronder databaseverbindingen, berichtbrokers, eindpunt-URI's en andere services. In .NET.NET Aspire nomenclatuur wordt de term "verbindingsreeks" gebruikt om alle soorten verbindingsgegevens weer te geven.

Beschouw het volgende voorbeeldapp-hostbestand Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Overweeg nu het volgende configuratiebestand voor de app-host appsettings.json:

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

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

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 parameter insertionRows wordt gelezen uit de sectie Parameters van het configuratiebestand van de app-host 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();

Delen via