Udostępnij za pomocą

Parametry zewnętrzne

Środowiska zapewniają kontekst, aby aplikacja mogła działać. Parametry umożliwiają żądanie wartości zewnętrznej podczas uruchamiania aplikacji. Parametry mogą służyć do podawania wartości aplikacji podczas uruchamiania lokalnego lub monitowania o wartości podczas wdrażania. Mogą być używane do modelowania szerokiej gamy scenariuszy, w tym tajnych danych, parametrów połączenia i innych wartości konfiguracji, które mogą się różnić w zależności od środowiska.

Wartości parametrów

Wartości parametrów są odczytywane z Parameters sekcji konfiguracji hosta AppHost i są używane do podawania wartości aplikacji podczas uruchamiania lokalnego. Po uruchomieniu lub opublikowaniu aplikacji, jeśli wartość nie jest skonfigurowana, zostanie wyświetlony monit o jej podanie.

Rozważmy następujący przykładowy plik 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);

Powyższy kod dodaje parametr o nazwie example-parameter-name do hosta AppHost. Parametr jest następnie przekazywany do projektu Projects.ApiService jako zmiennej środowiskowej o nazwie ENVIRONMENT_VARIABLE_NAME.

Konfigurowanie wartości parametrów

Dodawanie parametrów do konstruktora jest tylko jednym aspektem konfiguracji. Należy również podać wartość parametru . Wartość można podać w pliku konfiguracji AppHost, ustawić jako wpis tajny użytkownika lub skonfigurować w dowolnej innej konfiguracji standardowej. Gdy wartości parametrów nie zostaną znalezione, zostaną one wyświetlone po uruchomieniu lub opublikowaniu aplikacji.

Rozważmy następujący plik appsettings.jsonkonfiguracji AppHost:

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

Poprzedni JSON element konfiguruje parametr w Parameters sekcji konfiguracji AppHost. Innymi słowy, host AppHost jest w stanie znaleźć parametr tak, jak został skonfigurowany. Możesz na przykład przejść do IDistributedApplicationBuilder.Configuration i uzyskać dostęp do wartości przy użyciu klucza Parameters:example-parameter-name:

var builder = DistributedApplication.CreateBuilder(args);

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

Important

Jednak nie musisz uzyskiwać dostępu do tej wartości konfiguracji samodzielnie w hoście AppHost. Zamiast tego ParameterResource służy do przekazywania wartości parametru do zasobów zależnych. Najczęściej jako zmienna środowiskowa.

Przygotuj zapytanie o wartości parametrów na pulpicie nawigacyjnym

Jeśli kod dodaje parametry, ale ich nie ustawia, zostanie wyświetlony monit o skonfigurowanie ich wartości na pulpicie nawigacyjnym Aspire . Zostanie wyświetlony komunikat Nierozwiązane parametry i możesz wybrać pozycję Wprowadź wartości , aby rozwiązać problem:

Zrzut ekranu przedstawiający ostrzeżenie pulpitu nawigacyjnego Aspire , które jest wyświetlane, gdy istnieją nierozwiązane parametry.

Po wybraniu pozycji Wprowadź wartości zostanie wyświetlony formularz, Aspire którego można użyć do skonfigurowania wartości dla każdego z brakujących parametrów.

Możesz również kontrolować sposób wyświetlania tych parametrów na pulpicie nawigacyjnym przy użyciu następujących metod:

  • WithDescription: Użyj tej metody, aby podać opis tekstowy, który pomaga użytkownikom zrozumieć przeznaczenie parametru. Aby podać sformatowany opis w języku Markdown, użyj parametru enableMarkdown: true .
  • WithCustomInput: Użyj tej metody, aby udostępnić metodę wywołania zwrotnego, która dostosowuje okno dialogowe parametrów. Na przykład w tym wywołaniu zwrotnym można dostosować wartość domyślną, typ danych wejściowych, etykietę i tekst zastępczy.

Ten kod pokazuje, jak ustawić opis i użyć wywołania zwrotnego:

#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

Kod renderuje tę kontrolkę na pulpicie nawigacyjnym:

Zrzut ekranu przedstawiający okno dialogowe uzupełniania parametrów pulpitu nawigacyjnego Aspire z dostosowaniami.

Note

Okno dialogowe parametru pulpitu nawigacyjnego zawiera pole wyboru Zapisz w sekrecie użytkownika. Wybierz tę opcję, aby przechowywać poufne wartości w wpisach tajnych użytkownika usługi AppHost w celu uzyskania dodatkowej ochrony. Aby uzyskać więcej informacji na temat wartości parametrów wpisów tajnych, zobacz Wartości wpisów tajnych.

Reprezentacja parametrów w manifeście

Aspire używa manifestu wdrożenia do reprezentowania zasobów aplikacji i ich relacji. Parametry są reprezentowane w manifeście jako nowy element pierwotny o nazwie parameter.v0:

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

Wartości tajne

Parametry mogą służyć do modelowania tajemnic. Gdy parametr jest oznaczony jako tajny, służy jako wskazówka dla pliku manifestu, że wartość powinna być traktowana jako tajna. Po opublikowaniu aplikacji zostanie wyświetlony monit o podanie wartości i zapisanie jej w bezpiecznej lokalizacji. Po uruchomieniu aplikacji lokalnie wartość jest odczytywana z Parameters sekcji konfiguracji AppHost.

Rozważmy następujący przykładowy plik 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();

Teraz rozważ następujący plik appsettings.jsonkonfiguracji AppHost:

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

Reprezentacja manifestu jest następująca:

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

Wartości ciągu znaków połączenia

Parametry mogą służyć do modelowania ciągów połączenia. Po opublikowaniu aplikacji zostanie wyświetlony monit o podanie wartości i zapisanie jej w bezpiecznej lokalizacji. Po uruchomieniu aplikacji lokalnie wartość jest odczytywana z ConnectionStrings sekcji konfiguracji AppHost.

Note

Parametry połączenia służą do reprezentowania szerokiego zakresu informacji o połączeniu, w tym połączeń z bazą danych, brokerów komunikatów, identyfikatorów URI punktów końcowych i innych usług. W Aspire nomenklaturze termin "parametry połączenia" jest używany do reprezentowania dowolnego rodzaju informacji o połączeniu.

Rozważmy następujący przykładowy plik 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

Używanie WaitFor z ciągiem połączenia spowoduje niejawne oczekiwanie na zasób, do którego odnosi się ciąg połączenia.

Teraz rozważ następujący plik appsettings.jsonkonfiguracji AppHost:

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

Aby uzyskać więcej informacji dotyczących parametrów połączenia i ich reprezentacji w manifeście wdrożenia, zobacz Parametry połączenia i odwołania do powiązań.

Tworzenie parametrów połączenia za pomocą wyrażeń referencyjnych

Jeśli chcesz skonstruować ciąg połączenia z parametrów i upewnić się, że jest on poprawnie obsługiwany zarówno w środowisku deweloperskim, jak i produkcyjnym, należy użyć AddConnectionString z ReferenceExpression.

Jeśli na przykład masz parametr tajny, który przechowuje niewielką część parametrów połączenia, użyj tego kodu, aby go wstawić:

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

Możesz również użyć wyrażeń referencyjnych, aby dołączyć tekst do parametrów połączenia utworzonych przez Aspire zasoby. Na przykład po dodaniu PostgreSQL zasobu do Aspire rozwiązania serwer bazy danych jest uruchamiany w kontenerze, a parametry połączenia są dla niego sformułowane. W poniższym kodzie dodatkowa właściwość Include Error Details jest dołączana do tego ciągu połączenia, zanim zostanie przekazana do projektów, które z niego korzystają.

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

Przykład parametru

Aby wyrazić parametr, rozważmy następujący przykładowy kod:

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

Wykonano następujące kroki:

  • Dodaje zasób SQL Server o nazwie sql i publikuje go jako parametry połączenia.
  • Dodaje bazę danych o nazwie db.
  • Dodaje parametr o nazwie insertionRows.
  • Dodaje projekt o nazwie api i kojarzy go z parametrem typu zasobu projektu Projects.Parameters_ApiService.
  • Przekazuje parametr insertionRows do projektu api.
  • Odwołuje się do bazy danych db.

Wartość parametru insertionRows jest odczytywana z Parameters sekcji pliku appsettings.jsonkonfiguracji AppHost :

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

Projekt Parameters_ApiService używa parametru insertionRows. Rozważ przykładowy plik 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();

Zobacz także

  • Last updated on