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 z části Parameters konfigurace hostitele aplikace a slouží k poskytnutí hodnot aplikaci při místním spuštění. Pokud při publikování aplikace není nakonfigurovaná hodnota, zobrazí se výzva k jejímu zadání.

Podívejte se na následující ukázkový soubor hostitele Program.cs aplikace:

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á do hostitele aplikace parametr s názvem example-parameter-name. 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 hostitele aplikace, nastavit jako tajný klíč uživatele nebo nakonfigurovat v jakékoli jiné standardní konfiguraci. Pokud se hodnoty parametrů nenašly, zobrazí se výzva k zadání při publikování aplikace.

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

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

Člen, který předchází JSON, konfiguruje parametr v Parameters části konfigurace hostitele aplikace. Jinými slovy, hostitel aplikace dokáže najít parametr jako 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"

Důležitý

K této konfigurační hodnotě ale nemusíte přistupovat sami v hostiteli aplikace. 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í.

Reprezentace parametrů v manifestu

.NET .NET 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 hostitele aplikace.

Podívejte se na následující příklad souboru hostitele aplikace 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();

Teď zvažte následující konfigurační soubor appsettings.jsonhostitele aplikace:

{
    "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 hostitele aplikace.

Poznámka

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 .NET.NET Aspire terminologii se výraz "připojovací řetězec" používá k reprezentaci jakéhokoli druhu informací o připojení.

Zvažte následující příklad souboru Program.cs hostitele aplikace:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Poznámka

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í.

Teď zvažte následující konfigurační soubor appsettings.jsonhostitele aplikace:

{
    "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 text také připojit k připojovacím řetězcům vytvořeným zdroji .NET.NET Aspire. Když například přidáte PostgreSQL prostředek do .NET 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.jsonhostitele aplikace:

{
  "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é