Externa parametrar

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äse från Parameters avsnittet i AppHost-konfigurationen och används för att tillhandahålla värden till appen när den körs lokalt. Om värdet inte har konfigurerats när du kör eller publicerar appen uppmanas du att ange det.

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

Föregående kod lägger till en parameter med namnet example-parameter-name till AppHost. Parametern skickas sedan till Projects.ApiService-projektet som en miljövariabel med namnet ENVIRONMENT_VARIABLE_NAME.

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 AppHost-konfigurationsfilen, anges som en användarhemlighet eller konfigureras i någon annan standardkonfiguration. När parametervärden inte hittas uppmanas de att ange när du kör eller publicerar appen.

Överväg följande AppHost-konfigurationsfil appsettings.json:

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

Föregående JSON konfigurerar en parameter i Parameters avsnittet i AppHost-konfigurationen. Med andra ord kan AppHost hitta parametern när den är konfigurerad. Du kan till exempel gå fram till IDistributedApplicationBuilder.Configuration och komma åt värdet med hjälp av Parameters:example-parameter-name-nyckeln:

var builder = DistributedApplication.CreateBuilder(args);

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

Fråga efter parametervärden på instrumentpanelen

Om koden lägger till parametrar men inte anger dem visas en uppmaning om att konfigurera deras värden på Aspire instrumentpanelen. Meddelandet ouppklarade parametrar visas och du kan välja Ange värden för att lösa problemet:

När du väljer Ange värdenAspire visas ett formulär som du kan använda för att konfigurera värden för var och en av de parametrar som saknas.

Du kan också styra hur instrumentpanelen visar dessa parametrar med hjälp av följande metoder:

• WithDescription: Använd den här metoden för att ange en textbeskrivning som hjälper användarna att förstå syftet med parametern. Om du vill ange en formaterad beskrivning i Markdown använder du parametern enableMarkdown: true .
• WithCustomInput: Använd den här metoden för att tillhandahålla en återanropsmetod som anpassar parameterdialogrutan. I det här återanropet kan du till exempel anpassa standardvärdet, indatatypen, etiketten och platshållartexten.

Den här koden visar hur du anger en beskrivning och använder återanropet:

#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

Koden återger den här kontrollen på instrumentpanelen:

Parameterrepresentation i manifestet

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": {
    "example-parameter-name": {
      "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äss värdet från Parameters avsnittet i AppHost-konfigurationen.

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

Överväg nu följande AppHost-konfigurationsfil 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äss värdet från ConnectionStrings avsnittet i AppHost-konfigurationen.

Överväg följande exempel på AppHost-fil AppHost.cs :

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Överväg nu följande AppHost-konfigurationsfil appsettings.json:

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

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

Skapa anslutningssträngar med referensuttryck

Om du vill konstruera en anslutningssträng från parametrar och se till att den hanteras korrekt i både utveckling och produktion använder du AddConnectionString med en ReferenceExpression.

Om du till exempel har en hemlig parameter som lagrar en liten del av en anslutningssträng använder du den här koden för att infoga den:

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

Du kan också använda referensuttryck för att lägga till text i anslutningssträngar som skapats av Aspire resurser. När du till exempel lägger till en PostgreSQL resurs i din Aspire lösning körs databasservern i en container och en anslutningssträng formuleras för den. I följande kod läggs den extra egenskapen Include Error Details till i anslutningssträngen innan den skickas till förbrukande projekt:

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

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äse från Parameters avsnittet i AppHost-konfigurationsfilen 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();

Se även

• Aspire manifestformat för distributionsverktygsbyggare
• Självstudie: Ansluta en ASP.NET Core app till SQL Server med hjälp av Aspire och Entity Framework Core