Parametri esterni

Articolo
12/13/2024

Gli ambienti forniscono contesto per l'esecuzione dell'applicazione. I parametri esprimono la possibilità di richiedere un valore esterno durante l'esecuzione dell'app. I parametri possono essere usati per fornire valori all'app durante l'esecuzione in locale o per richiedere valori durante la distribuzione. Possono essere usati per modellare un'ampia gamma di scenari, tra cui segreti, stringhe di connessione e altri valori di configurazione che possono variare tra gli ambienti.

Valori dei parametri

I valori dei parametri vengono letti dalla sezione Parameters della configurazione dell'host dell'app e vengono usati per fornire valori all'app durante l'esecuzione in locale. Quando si pubblica l'app, se il valore non è configurato, viene richiesto di specificarlo.

Si consideri il seguente file host dell'app di esempio 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);

Il codice precedente aggiunge un parametro denominato value all'host dell'app. Il parametro viene quindi passato al progetto di Projects.ApiService come variabile di ambiente denominata EXAMPLE_VALUE.

Configurare i valori dei parametri

L'aggiunta di parametri al generatore è solo un aspetto della configurazione. È inoltre necessario specificare il valore per il parametro . Il valore può essere fornito nel file di configurazione dell'host dell'app, impostato come segreto utente o configurato in qualsiasi altra configurazione standard. Quando i valori dei parametri non vengono trovati, vengono richiesti quando si pubblica l'app.

Considera il seguente file di configurazione dell'host dell'app appsettings.json:

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

Il JSON precedente configura un parametro nella sezione Parameters della configurazione dell'host dell'applicazione. In altre parole, l'host dell'app è in grado di trovare il parametro come configurato. Ad esempio, è possibile accedere al IDistributedApplicationBuilder.Configuration e accedere al valore usando la chiave Parameters:value:

var builder = DistributedApplication.CreateBuilder(args);

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

Importante

Tuttavia, non è necessario accedere a questo valore di configurazione manualmente nell'host dell'app. Viene invece usato il ParameterResource per passare il valore del parametro alle risorse dipendenti. La maggior parte delle volte come variabile di ambiente.

Rappresentazione dei parametri nel manifesto

.NET .NET Aspire usa un manifesto di distribuzione per rappresentare le risorse dell'app e le loro relazioni. I parametri vengono rappresentati nel manifesto come nuova primitiva denominata parameter.v0:

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

Valori segreti

I parametri possono essere usati per modellare i segreti. Quando un parametro è contrassegnato come segreto, funge da hint per il manifesto che il valore deve essere considerato come segreto. Quando si pubblica l'app, il valore viene richiesto e archiviato in una posizione sicura. Quando si esegue l'app in locale, il valore viene letto dalla sezione Parameters della configurazione dell'host dell'app.

Si consideri il file di host dell'app di esempio seguente 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();

Ora considerate il seguente file di configurazione dell'host dell'app appsettings.json:

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

La rappresentazione del manifesto è la seguente:

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

Valori della stringa di connessione

I parametri possono essere usati per modellare le stringhe di connessione. Quando si pubblica l'app, il valore viene richiesto e archiviato in una posizione sicura. Quando si esegue l'app in locale, il valore viene letto dalla sezione ConnectionStrings della configurazione dell'host dell'app.

Nota

Le stringhe di connessione vengono usate per rappresentare un'ampia gamma di informazioni di connessione, tra cui connessioni di database, broker di messaggi, URI endpoint e altri servizi. Nella nomenclatura .NET.NET Aspire, il termine "stringa di connessione" viene usato per rappresentare qualsiasi tipo di informazione relativa a connessione.

Si consideri il file di host dell'app di esempio seguente Program.cs:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Ora, considera il seguente file di configurazione dell'host dell'app appsettings.json:

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

Per ulteriori informazioni sulle stringhe di connessione e sulla loro rappresentazione nel manifesto di distribuzione, vedere Stringa di connessione e riferimenti di associazione.

Esempio di parametro

Per esprimere un parametro, prendere in considerazione il codice di esempio seguente:

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

Vengono eseguiti i passaggi seguenti:

Aggiunge una risorsa SQL Server denominata sql e la pubblica come stringa di connessione.
Aggiunge un database denominato db.
Aggiunge un parametro denominato insertionRows.
Aggiunge un progetto denominato api e lo associa al parametro type-type della risorsa del progetto Projects.Parameters_ApiService.
Passa il parametro insertionRows al progetto api.
Fa riferimento al database db.

Il valore del parametro insertionRows viene letto dalla sezione Parameters del file di configurazione dell'host dell'app appsettings.json:

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

Il progetto Parameters_ApiService utilizza il parametro insertionRows. Si consideri il file di esempio 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();

Condividi tramite