Parámetros externos

Artículo
12/16/2024

Los entornos proporcionan contexto para que la aplicación se ejecute. Los parámetros expresan la capacidad de solicitar un valor externo al ejecutar la aplicación. Los parámetros se pueden usar para proporcionar valores a la aplicación cuando se ejecuta localmente o para solicitar valores al implementar. Se pueden usar para modelar una amplia gama de escenarios, incluidos secretos, cadenas de conexión y otros valores de configuración que pueden variar entre entornos.

Valores de parámetro

Los valores de parámetro se leen desde la sección Parameters de la configuración del host de la aplicación y se usan para proporcionar valores a la aplicación mientras se ejecuta localmente. Al publicar la aplicación, si el valor no está configurado, se le pedirá que lo proporcione.

Tenga en cuenta el siguiente archivo del host del ejemplo de la aplicación 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);

El código anterior agrega un parámetro denominado value al host de la aplicación. A continuación, el parámetro se pasa al proyecto de Projects.ApiService como una variable de entorno denominada EXAMPLE_VALUE.

Configuración de valores de parámetro

Agregar parámetros al generador es solo un aspecto de la configuración. También debe proporcionar el valor del parámetro. El valor se puede proporcionar en el archivo de configuración del host de la aplicación, establecido como un secreto de usuario o configurado en cualquier otra configuración estándar . Cuando no se encuentran los valores de parámetro, se les pedirá al publicar la aplicación.

Tenga en cuenta el siguiente archivo de configuración del host de aplicación appsettings.json:

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

El JSON anterior configura un parámetro en la sección Parameters de la configuración del host de la aplicación. En otras palabras, ese host de aplicación puede encontrar el parámetro como está configurado. Por ejemplo, puede ir al IDistributedApplicationBuilder.Configuration y acceder al valor mediante la clave Parameters:value:

var builder = DistributedApplication.CreateBuilder(args);

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

Importante

Sin embargo, no es necesario acceder a este valor de configuración en el host de la aplicación. En su lugar, el ParameterResource se usa para pasar el valor del parámetro a los recursos dependientes. La mayoría de las veces como una variable de entorno.

Representación de parámetros en el manifiesto

.NET .NET Aspire usa un manifiesto de implementación para representar los recursos de la aplicación y sus relaciones. Los parámetros se representan en el manifiesto como un nuevo primitivo denominado parameter.v0:

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

Valores secretos

Los parámetros se pueden usar para modelar secretos. Cuando un parámetro se marca como un secreto, sirve como sugerencia para el manifiesto de que el valor se debe tratar como secreto. Al publicar la aplicación, se solicita el valor y se almacena en una ubicación segura. Al ejecutar la aplicación localmente, el valor se lee en la sección Parameters de la configuración del host de la aplicación.

Considere el siguiente archivo de host de aplicación de ejemplo 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();

Ahora, tenga en cuenta el siguiente archivo de configuración de host de aplicación appsettings.json:

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

La representación del manifiesto es la siguiente:

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

Valores de cadena de conexión

Los parámetros se pueden usar para modelar cadenas de conexión. Al publicar la aplicación, se solicita el valor y se almacena en una ubicación segura. Al ejecutar la aplicación localmente, el valor se lee en la sección ConnectionStrings de la configuración del host de la aplicación.

Nota

Las cadenas de conexión se usan para representar una amplia gama de información de conexión, incluidas las conexiones de base de datos, los agentes de mensajes, los URI de punto de conexión y otros servicios. En .NET.NET Aspire nomenclatura, el término "cadena de conexión" se usa para representar cualquier tipo de información de conexión.

Tenga en cuenta el siguiente ejemplo de archivo host de la aplicación Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Ahora, tenga en cuenta el siguiente archivo de configuración de host de aplicación appsettings.json:

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

Para obtener más información relacionada con las cadenas de conexión y sus referencias en el manifiesto de implementación, consulte Cadena de conexión y referencias de enlace.

Ejemplo de parámetro

Para expresar un parámetro, considere el código de ejemplo siguiente:

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

Se realizan los pasos siguientes:

Agrega un recurso SQL Server denominado sql y lo publica como una cadena de conexión.
Agrega una base de datos denominada db.
Agrega un parámetro denominado insertionRows.
Agrega un proyecto denominado api y lo asocia al parámetro de tipo de recurso de proyecto Projects.Parameters_ApiService.
Pasa el parámetro insertionRows al proyecto de api.
Hace referencia a la base de datos de db.

El valor del parámetro insertionRows se lee en la sección Parameters del archivo de configuración del host de la aplicación appsettings.json:

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

El proyecto Parameters_ApiService consume el parámetro insertionRows. Considere el archivo de ejemplo de 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();

Compartir a través de