Sdílet prostřednictvím

Externí parametry

Prostředí poskytují kontext pro spuštění aplikace. Parametry vyjadřují možnost požádat o externí hodnotu při spuštění aplikace. Parametry se dají použít k zadání hodnot aplikaci při místním spuštění nebo k zobrazení výzvy k zadání hodnot při nasazování. Dají se použít k modelování široké škály scénářů, včetně tajných kódů, připojovacích řetězců a dalších hodnot konfigurace, které se můžou mezi prostředími lišit.

Hodnoty parametrů

Hodnoty parametrů se čtou Parameters z části konfigurace AppHost a slouží k zadání hodnot aplikaci při místním spuštění. Pokud při spuštění nebo publikování aplikace není nakonfigurovaná hodnota, zobrazí se výzva k jejímu zadání.

Představte si následující příklad souboru AppHost 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);

Předchozí kód přidá parametr s názvem example-parameter-name AppHost. Parametr je pak jako proměnná prostředí s názvem Projects.ApiServicepředán projektu ENVIRONMENT_VARIABLE_NAME.

Konfigurace hodnot parametrů

Přidání parametrů do konstruktéru je pouze jedním aspektem konfigurace. Musíte také zadat hodnotu parametru. Hodnotu lze zadat v konfiguračním souboru AppHost, nastavit jako tajný klíč uživatele nebo nakonfigurovat v jakékoli jiné standardní konfiguraci. Pokud se hodnoty parametrů nenašly, zobrazí se výzva, když aplikaci spustíte nebo publikujete.

Zvažte následující konfigurační soubor appsettings.jsonAppHost:

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

JSON Předchozí konfigurace parametru v Parameters části konfigurace AppHost. Jinými slovy, že AppHost dokáže najít parametr, jak je nakonfigurovaný. Můžete například přejít k hodnotě IDistributedApplicationBuilder.Configuration a získat k této hodnotě Parameters:example-parameter-name přístup pomocí klíče:

var builder = DistributedApplication.CreateBuilder(args);

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

Important

K této konfigurační hodnotě ale nemusíte přistupovat sami v AppHostu. ParameterResource Místo toho se použije k předání hodnoty parametru závislým prostředkům. Nejčastěji se jedná o proměnnou prostředí.

Výzva k zadání hodnot parametrů na řídicím panelu

Pokud váš kód přidá parametry, ale nenastaví je, zobrazí se výzva ke konfiguraci jejich hodnot na řídicím panelu Aspire . Zobrazí se zpráva Nerozpoznané parametry a k vyřešení problému můžete vybrat Enter hodnoty :

Snímek obrazovky s upozorněním řídicího panelu Aspire , které se zobrazí, když jsou nevyřešené parametry

Když vyberete Zadat hodnoty, zobrazí formulář, Aspire který můžete použít ke konfiguraci hodnot pro každý z chybějících parametrů.

Pomocí těchto metod můžete také řídit, jak řídicí panel zobrazuje tyto parametry:

  • WithDescription: Tuto metodu použijte k zadání textového popisu, který uživatelům pomůže pochopit účel parametru. K zadání formátovaného popisu v MarkdownuenableMarkdown: true použijte parametr.
  • WithCustomInput: Tuto metodu použijte k poskytnutí metody zpětného volání, která přizpůsobí dialogové okno parametru. V tomto zpětném volání můžete například přizpůsobit výchozí hodnotu, typ vstupu, popisek a zástupný text.

Tento kód ukazuje, jak nastavit popis a použít zpětné volání:

#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

Kód vykreslí tento ovládací prvek na řídicím panelu:

Snímek obrazovky s dialogovým oknem dokončení parametru řídicího panelu Aspire s vlastními nastaveními

Note

Dialogové okno parametru řídicího panelu obsahuje zaškrtávací políčko Uložit do tajného kódu uživatele . Tuto možnost vyberte, pokud chcete ukládat citlivé hodnoty do tajných kódů uživatelů appHost pro dodatečnou ochranu. Další informace o hodnotách tajných parametrů naleznete v tématu Tajné hodnoty.

Reprezentace parametrů v manifestu

Aspire používá manifest nasazení k reprezentaci prostředků aplikace a jejich vztahů. Parametry jsou v manifestu reprezentovány jako nový primitivní název parameter.v0:

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

Tajné hodnoty

Parametry lze použít k modelování tajných kódů. Pokud je parametr označený jako tajný kód, slouží jako nápověda manifestu, že hodnota by měla být považována za tajný kód. Když aplikaci publikujete, budete vyzváni k zadání hodnoty, která bude uložena v zabezpečeném umístění. Při místním spuštění aplikace se hodnota načte z Parameters části konfigurace AppHost.

Představte si následující příklad souboru AppHost 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();

Nyní zvažte následující konfigurační soubor appsettings.jsonAppHost:

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

Reprezentace manifestu je následující:

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

Hodnoty připojovacího řetězce

Parametry lze použít k modelování připojovacích řetězců. Když aplikaci publikujete, budete vyzváni k zadání hodnoty, která bude uložena v zabezpečeném umístění. Při místním spuštění aplikace se hodnota načte z ConnectionStrings části konfigurace AppHost.

Note

Připojovací řetězce se používají k reprezentaci široké škály informací o připojení, včetně databázových připojení, zprostředkovatelů zpráv, identifikátorů URI koncových bodů a dalších služeb. V Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Představte si následující příklad souboru AppHost AppHost.cs :

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Note

Použití WaitFor s připojovacím řetězcem implicitně počká na prostředek, ke kterému se připojovací řetězec připojí.

Nyní zvažte následující konfigurační soubor appsettings.jsonAppHost:

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

Další informace týkající se připojovacích řetězců a jejich reprezentace v manifestu nasazení naleznete v části Připojovací řetězce a odkazy na vazby.

Vytváření připojovacích řetězců s referenčními výrazy

Pokud chcete vytvořit připojovací řetězec z parametrů a zajistit, aby se správně zpracovával ve vývoji i produkčním prostředí, použijte AddConnectionString s parametrem ReferenceExpression.

Pokud máte například tajný parametr, který ukládá malou část připojovacího řetězce, vložte ho pomocí tohoto kódu:

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

Pomocí referenčních výrazů můžete také připojit text k připojovacím řetězcům vytvořeným zdroji Aspire. Když například přidáte PostgreSQL prostředek do Aspire řešení, databázový server se spustí v kontejneru a je pro něj vytvořen připojovací řetězec. V následujícím kódu je další vlastnost Include Error Details připojena k tomuto připojovacímu řetězci, než se předá projektům, které ji využívají.

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

Příklad parametru

Pokud chcete vyjádřit parametr, zvažte následující ukázkový kód:

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

Provede se následující kroky:

  • Přidá prostředek SQL Server s názvem sql a publikuje ho jako připojovací řetězec.
  • Přidá databázi s názvem db.
  • Přidá parametr s názvem insertionRows.
  • Přidá projekt s názvem api a přidruží ho k parametru Projects.Parameters_ApiService typu zdroje projektu.
  • Předá parametr insertionRows projektu api.
  • Odkazuje na databázi db.

Hodnota parametru insertionRows se načte z Parameters části konfiguračního souboru appsettings.jsonAppHost:

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

Projekt Parameters_ApiService využívá insertionRows parametr. Podívejte se na Program.cs ukázkový soubor:

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

Viz také

  • Last updated on