Parâmetros externos

Artigo
12/13/2024

Os ambientes fornecem contexto para a aplicação em execução. Os parâmetros expressam a capacidade de pedir um valor externo ao executar o aplicativo. Os parâmetros podem ser usados para fornecer valores ao aplicativo durante a execução local ou para 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 dos parâmetros

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. Quando você publica o aplicativo, se o valor não estiver configurado, você será solicitado a fornecê-lo.

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

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. O parâmetro é então 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 aspeto 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 outrode configuração padrão. Quando os valores dos parâmetros não são encontrados, eles são solicitados ao publicar o aplicativo.

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

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

A 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 encontrar o parâmetro como configurado. Por exemplo, você pode caminhar até o IDistributedApplicationBuilder.Configuration e acessar o valor usando a tecla 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 sozinho no host do aplicativo. 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âmetros no manifesto

.NET .NET Aspire usa um manifesto de implantação para representar os recursos do aplicativo e seus relacionamentos. Os parâmetros são representados no manifesto como uma nova primitiva chamada 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 exemplo de host do aplicativo 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.

Observação

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. Na nomenclatura .NET.NET Aspire, o termo "cadeia de conexão" é usado para representar qualquer tipo de informação de conexão.

Considere o seguinte arquivo de exemplo do host do aplicativo 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 referentes a cadeias de conexão e sua representação no manifesto de implantação, consulte Connection string and binding references.

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 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 de projeto Projects.Parameters_ApiService.
Passa o parâmetro insertionRows para o projeto api.
Faz referência ao banco de dados db.

O valor para o 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();

Partilhar via