Parâmetros externos

Artigo
12/15/2024

Os ambientes fornecem contexto para a execução do aplicativo. Os parâmetros expressam a capacidade de solicitar um valor externo ao executar o aplicativo. Os parâmetros podem ser usados para fornecer valores ao aplicativo ao executar localmente ou solicitar valores durante a implantação. Eles podem ser usados para modelar uma ampla gama de cenários, incluindo segredos, cadeias de conexão e outros valores de configuração que podem variar entre ambientes.

Valores de parâmetro

Os valores de parâmetro são lidos na seção Parameters da configuração do host do aplicativo e são usados para fornecer valores ao aplicativo durante a execução local. Ao publicar o aplicativo, se o valor não estiver configurado, você será solicitado a fornecê-lo.

Considere o seguinte exemplo de arquivo de host do aplicativo 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);

O código anterior adiciona um parâmetro chamado value ao host do aplicativo. Em seguida, o parâmetro é passado para o projeto Projects.ApiService como uma variável de ambiente chamada EXAMPLE_VALUE.

Configurar valores de parâmetro

Adicionar parâmetros ao construtor é apenas um aspecto da configuração. Você também deve fornecer o valor para o parâmetro. O valor pode ser fornecido no arquivo de configuração do host do aplicativo, definido como um segredo do usuário ou configurado em qualquer outra configuração padrão. Quando os valores de parâmetro não são encontrados, eles são solicitados durante a publicação do aplicativo.

Considere o seguinte arquivo de configuração do host do aplicativo appsettings.json:

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

O JSON anterior configura um parâmetro na seção Parameters da configuração do host do aplicativo. Em outras palavras, esse host de aplicativo é capaz de localizar o parâmetro como configurado. Por exemplo, você pode ir até o IDistributedApplicationBuilder.Configuration e acessar o valor usando a chave Parameters:value:

var builder = DistributedApplication.CreateBuilder(args);

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

Importante

No entanto, você não precisa acessar esse valor de configuração diretamente no host do app. Em vez disso, o ParameterResource é usado para passar o valor do parâmetro para recursos dependentes. Na maioria das vezes, como uma variável de ambiente.

Representação de parâmetro no manifesto

.NET .NET Aspire usa um manifesto de implantação para representar os recursos do aplicativo e suas relações. Os parâmetros são representados no manifesto como um novo primitivo chamado parameter.v0:

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

Valores secretos

Os parâmetros podem ser usados para modelar segredos. Quando um parâmetro é marcado como um segredo, ele serve como uma dica para o manifesto de que o valor deve ser tratado como um segredo. Quando você publica o aplicativo, o valor é solicitado e armazenado em um local seguro. Quando você executa o aplicativo localmente, o valor é lido na seção Parameters da configuração do host do aplicativo.

Considere o seguinte arquivo de host de aplicativo, exemplo 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();

Agora considere o seguinte arquivo de configuração do host do aplicativo appsettings.json:

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

A representação do manifesto é a seguinte:

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

Valores da cadeia de conexão

Os parâmetros podem ser usados para modelar cadeias de conexão. Quando você publica o aplicativo, o valor é solicitado e armazenado em um local seguro. Quando você executa o aplicativo localmente, o valor é lido na seção ConnectionStrings da configuração do host do aplicativo.

Nota

As cadeias de conexão são usadas para representar uma ampla gama de informações de conexão, incluindo conexões de banco de dados, agentes de mensagens, URIs de ponto de extremidade e outros serviços. Em .NET.NET Aspire nomenclatura, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

Considere o seguinte exemplo de arquivo de aplicativo host Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Agora considere o seguinte arquivo de configuração do host do aplicativo appsettings.json:

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

Para obter mais informações sobre cadeias de conexão e sua representação no manifesto de implantação, consulte Cadeia de conexão e referências de associação.

Exemplo de parâmetro

Para expressar um parâmetro, considere o seguinte código de exemplo:

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

As seguintes etapas são executadas:

Adiciona um recurso de SQL Server chamado sql e o publica como uma cadeia de conexão.
Adiciona um banco de dados chamado db.
Adiciona um parâmetro chamado insertionRows.
Adiciona um projeto chamado api e o associa ao parâmetro de tipo de recurso do projeto Projects.Parameters_ApiService.
Passa o parâmetro insertionRows para o projeto api.
Faz referência ao banco de dados db.

O valor do parâmetro insertionRows é lido na seção Parameters do arquivo de configuração do host do aplicativo appsettings.json:

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

O projeto Parameters_ApiService consome o parâmetro insertionRows. Considere o arquivo de exemplo 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();

Compartilhar via