Поделиться через

Внешние параметры

  • Статья

Среды предоставляют контекст для запуска приложения. Параметры выражают возможность запрашивать внешнее значение при запуске приложения. Параметры можно использовать для предоставления значений приложению при локальном запуске или запроса значений при развертывании. Их можно использовать для моделирования широкого спектра сценариев, включая секреты, строки подключения и другие значения конфигурации, которые могут отличаться между средами.

Значения параметров

Значения параметров считываются из раздела Parameters конфигурации узла приложения и используются для предоставления значений приложению во время локальной работы. При публикации приложения, если значение не настроено, вам будет предложено предоставить его.

Рассмотрим следующий пример 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);

Приведенный выше код добавляет параметр с именем value к хосту приложения. Затем параметр передается в проект Projects.ApiService в качестве переменной среды с именем EXAMPLE_VALUE.

Настройка значений параметров

Добавление параметров в построитель — это только один аспект конфигурации. Необходимо также указать значение параметра. Это значение можно указать в файле конфигурации узла приложения, задать в качестве секрета пользователя или настроить в любой другой стандартной конфигурации. Если значения параметров не найдены, они запрашиваются при публикации приложения.

Рассмотрим следующий файл конфигурации узла приложения appsettings.json:

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

Предшествующая JSON настраивает параметр в разделе Parameters конфигурации хоста приложения. Другими словами, этот хост приложения может найти параметр в его настроенном виде. Например, можно перейти к IDistributedApplicationBuilder.Configuration и получить доступ к значению с помощью ключа Parameters:value:

var builder = DistributedApplication.CreateBuilder(args);

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

Важный

Однако вам не нужно обращаться к этому значению конфигурации в хосте приложения. Вместо этого ParameterResource используется для передачи значения параметра зависимым ресурсам. Чаще всего в качестве переменной среды.

Представление параметров в манифесте

.NET .NET Aspire использует манифест развертывания для представления ресурсов приложения и их связей. Параметры представлены в манифесте как новый примитив, называемый parameter.v0:

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

Секретные значения

Параметры можно использовать для моделирования секретов. Если параметр помечается как секрет, он служит указанием манифесту, что значение должно рассматриваться как секрет. При публикации приложения значение запрашивается и хранится в безопасном расположении. При локальном запуске приложения значение считывается из раздела Parameters конфигурации узла приложения.

Рассмотрим следующий пример 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();

Теперь рассмотрим следующий файл конфигурации узла приложения appsettings.json:

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

Представление манифеста выглядит следующим образом:

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

Значения строки подключения

Параметры можно использовать для моделирования строк подключения. При публикации приложения значение запрашивается и хранится в безопасном расположении. При локальном запуске приложения значение считывается из раздела ConnectionStrings конфигурации узла приложения.

Заметка

Строки подключения используются для представления широкого диапазона сведений о подключении, включая подключения к базе данных, брокеры сообщений, URI конечной точки и другие службы. В .NET.NET Aspire номенклатуре термин "строка подключения" используется для представления любой информации о подключении.

Рассмотрим следующий пример Program.cs файла узла приложения:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Теперь рассмотрим следующий файл конфигурации узла приложения appsettings.json:

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

Дополнительные сведения о строках подключения и их представлении в манифесте развертывания см. в строках подключения и ссылках на привязки.

Пример параметра

Чтобы выразить параметр, рассмотрим следующий пример кода:

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

Выполняются следующие действия.

  • Добавляет ресурс SQL Server с именем sql и публикует его в качестве строки подключения.
  • Добавляет базу данных с именем db.
  • Добавляет параметр с именем insertionRows.
  • Добавляет проект с именем api и связывает его с параметром типа ресурса проекта Projects.Parameters_ApiService.
  • Передает параметр insertionRows проекту api.
  • Ссылается на базу данных db.

Значение параметра insertionRows считывается из раздела Parameters файла конфигурации узла приложения appsettings.json:

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

Проект Parameters_ApiService использует параметр insertionRows. Рассмотрим пример файла 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();

См. также