Externa parametrar

Artikel
12/13/2024

Miljöer ger kontext för programmet att köras i. Parametrar uttrycker möjligheten att be om ett externt värde när appen körs. Parametrar kan användas för att ange värden för appen när den körs lokalt eller för att fråga efter värden vid distribution. De kan användas för att modellera en mängd olika scenarier, inklusive hemligheter, anslutningssträngar och andra konfigurationsvärden som kan variera mellan miljöer.

Parametervärden

Parametervärden läses från avsnittet Parameters i applikationsvärdens konfiguration och används till att ge värden till appen när den körs lokalt. Om värdet inte har konfigurerats när du publicerar appen uppmanas du att ange det.

Överväg följande exempel på appvärdsfilen 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);

Föregående kod lägger till en parameter med namnet value till appvärden. Parametern skickas sedan till Projects.ApiService-projektet som en miljövariabel med namnet EXAMPLE_VALUE.

Konfigurera parametervärden

Att lägga till parametrar i byggaren är bara en aspekt av konfigurationen. Du måste också ange värdet för parametern. Värdet kan anges i appvärdkonfigurationsfilen, anges som en användarhemlighet eller konfigureras i någon annan standardkonfiguration. När parametervärden inte hittas, ombeds du att ange dem vid publicering av appen.

Överväg följande appvärdkonfigurationsfil appsettings.json:

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

Den föregående JSON konfigurerar en parameter i avsnittet Parameters i appvärdkonfigurationen. Med andra ord kan appvärden hitta parametern så som den har blivit konfigurerad. Du kan till exempel gå fram till IDistributedApplicationBuilder.Configuration och komma åt värdet med hjälp av Parameters:value-nyckeln:

var builder = DistributedApplication.CreateBuilder(args);

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

Viktig

Du behöver dock inte komma åt det här konfigurationsvärdet själv i appvärden. I stället används ParameterResource för att skicka parametervärdet till beroende resurser. Oftast som en miljövariabel.

Parameterrepresentation i manifestet

.NET .NET Aspire använder ett distributionsmanifest för att representera appens resurser och deras relationer. Parametrar representeras i manifestet som en ny primitiv som heter parameter.v0:

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

Hemliga värden

Parametrar kan användas för att modellera hemligheter. När en parameter markeras som en hemlighet fungerar den som ett tips till manifestet att värdet ska behandlas som en hemlighet. När du publicerar appen uppmanas värdet att ange och lagras på en säker plats. När du kör appen lokalt läses värdet från avsnittet Parameters i appens värdkonfiguration.

Överväg följande exempel på fil för appvärd 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();

Överväg nu följande konfigurationsfil för appvärd appsettings.json:

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

Manifestrepresentationen är följande:

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

Värden för anslutningssträngar

Parametrar kan användas för att modellera anslutningssträngar. När du publicerar appen uppmanas värdet att ange och lagras på en säker plats. När du kör appen lokalt läses värdet från avsnittet ConnectionStrings i appvärdkonfigurationen.

Obs

Anslutningssträngar används för att representera ett brett spektrum av anslutningsinformation, inklusive databasanslutningar, meddelandeköer, slutpunkts-URI:er och andra tjänster. I .NET.NET Aspire nomenklatur används termen "anslutningssträng" för att representera alla typer av anslutningsinformation.

Överväg följande exempel på appvärd Program.cs fil:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Överväg nu följande konfigurationsfil för appvärd appsettings.json:

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

Mer information om anslutningssträngar och deras representation i distributionsmanifestet finns i Anslutningssträng och bindningsreferenser.

Parameterexempel

Tänk på följande exempelkod för att uttrycka en parameter:

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

Följande steg utförs:

Lägger till en SQL Server resurs med namnet sql och publicerar den som en anslutningssträng.
Lägger till en databas med namnet db.
Lägger till en parameter med namnet insertionRows.
Lägger till ett projekt med namnet api och associerar det med Projects.Parameters_ApiService project resource type-parameter.
Skickar parametern insertionRows till api-projektet.
Refererar till db-databasen.

Värdet för parametern insertionRows läses från avsnittet Parameters i konfigurationsfilen för appens värd appsettings.json:

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

Parameters_ApiService-projektet använder parametern insertionRows. Överväg exempelarket 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();

Dela via