Paramètres externes

Article
12/15/2024

Les environnements fournissent un contexte pour que l’application s’exécute. Les paramètres expriment la possibilité de demander une valeur externe lors de l’exécution de l’application. Les paramètres peuvent être utilisés pour fournir des valeurs à l’application lors de l’exécution locale ou pour demander des valeurs lors du déploiement. Ils peuvent être utilisés pour modéliser un large éventail de scénarios, notamment les secrets, les chaînes de connexion et d’autres valeurs de configuration qui peuvent varier entre les environnements.

Valeurs des paramètres

Les valeurs de paramètre sont lues à partir de la section Parameters de la configuration de l’hôte d’application et sont utilisées pour fournir des valeurs à l’application lors de l’exécution locale. Lorsque vous publiez l’application, si la valeur n’est pas configurée, vous êtes invité à le fournir.

Considérez le fichier hôte d’exemple d’application suivant 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);

Le code précédent ajoute un paramètre nommé value à l’hôte de l’application. Le paramètre est ensuite passé au projet Projects.ApiService en tant que variable d’environnement nommée EXAMPLE_VALUE.

Configurer les valeurs des paramètres

L’ajout de paramètres au générateur n’est qu’un aspect de la configuration. Vous devez également fournir la valeur du paramètre. La valeur peut être fournie dans le fichier de configuration de l’hôte d’application, définie en tant que secret utilisateur ou configurée dans n’importe quel autrede configuration standard. Lorsque les valeurs de paramètre ne sont pas présentes, elles sont demandées lors de la publication de l'application.

Considérez le fichier de configuration de l’hôte d’application suivant appsettings.json:

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

La JSON précédente configure un paramètre dans la section Parameters de la configuration de l’hôte d’application. En d’autres termes, cet hôte d’application peut trouver le paramètre tel qu’il est configuré. Par exemple, vous pouvez accéder au IDistributedApplicationBuilder.Configuration et accéder à la valeur à l’aide de la clé Parameters:value :

var builder = DistributedApplication.CreateBuilder(args);

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

Important

Toutefois, vous n’avez pas besoin d’accéder à cette valeur de configuration vous-même dans l’hôte de l’application. Au lieu de cela, la ParameterResource est utilisée pour passer la valeur du paramètre aux ressources dépendantes. Le plus souvent en tant que variable d’environnement.

Représentation de paramètre dans le manifeste

.NET .NET Aspire utilise un manifeste de déploiement pour représenter les ressources de l’application et leurs relations. Les paramètres sont représentés dans le manifeste sous la forme d’une nouvelle primitive appelée parameter.v0:

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

Valeurs secrètes

Les paramètres peuvent être utilisés pour modéliser des secrets. Lorsqu’un paramètre est marqué comme un secret, il sert d’indicateur au manifeste que la valeur doit être traitée comme un secret. Lorsque vous publiez l'application, il vous sera demandé de saisir la valeur, qui sera ensuite stockée dans un emplacement sécurisé. Lorsque vous exécutez l’application localement, la valeur est lue à partir de la section Parameters de la configuration de l’hôte de l’application.

Considérez l’exemple d’hôte d’application suivant Program.cs fichier :

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

Considérez maintenant le fichier de configuration de l’hôte d’application suivant appsettings.json:

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

La représentation manifeste est la suivante :

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

Valeurs de chaîne de connexion

Les paramètres peuvent être utilisés pour modéliser des chaînes de connexion. Lorsque vous publiez l’application, la valeur est demandée et stockée dans un emplacement sécurisé. Lorsque vous exécutez l’application localement, la valeur est lue à partir de la section ConnectionStrings de la configuration de l’hôte de l’application.

Note

Les chaînes de connexion sont utilisées pour représenter un large éventail d’informations de connexion, notamment les connexions de base de données, les répartiteurs de messages, les URI de point de terminaison et d’autres services. Dans .NET.NET Aspire nomenclature, le terme « chaîne de connexion » est utilisé pour représenter n’importe quel type d’informations de connexion.

Considérez l'exemple suivant de fichier d'application hôte Program.cs :

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Considérez maintenant le fichier de configuration de l’hôte d’application suivant appsettings.json:

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

Pour plus d’informations sur les chaînes de connexion et les références de liaison, et leur représentation dans le manifeste de déploiement, consultez chaînes de connexion et références de liaison.

Exemple de paramètre

Pour exprimer un paramètre, considérez l’exemple de code suivant :

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

Les étapes suivantes sont effectuées :

Ajoute une ressource SQL Server nommée sql et la publie en tant que chaîne de connexion.
Ajoute une base de données nommée db.
Ajoute un paramètre nommé insertionRows.
Ajoute un projet nommé api et l’associe au paramètre de type de ressource de projet Projects.Parameters_ApiService.
Transmet le paramètre insertionRows au projet api.
Fait référence à la base de données db.

La valeur du paramètre insertionRows est lue à partir de la section Parameters du fichier de configuration hôte d’application appsettings.json:

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

Le projet Parameters_ApiService consomme le paramètre insertionRows. Considérez l’exemple de fichier 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();

Partager via