Condividi tramite

Parametri esterni

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 Parameters sezione della configurazione di AppHost e vengono usati per fornire valori all'app durante l'esecuzione in locale. Quando si esegue o si pubblica l'app, se il valore non è configurato, viene richiesto di specificarlo.

Si consideri il file AppHost AppHost.cs di esempio seguente:

var builder = DistributedApplication.CreateBuilder(args);

// Add a parameter named "example-parameter-name"
var parameter = builder.AddParameter("example-parameter-name");

builder.AddProject<Projects.ApiService>("api")
       .WithEnvironment("ENVIRONMENT_VARIABLE_NAME", parameter);

Il codice precedente aggiunge un parametro denominato example-parameter-name ad AppHost. Il parametro viene quindi passato al progetto di Projects.ApiService come variabile di ambiente denominata ENVIRONMENT_VARIABLE_NAME.

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 appHost, impostato come segreto utente o configurato in qualsiasi altra configurazione standard. Quando i valori dei parametri non vengono trovati, vengono richiesti quando si esegue o si pubblica l'app.

Prendere in considerazione il file appsettings.jsondi configurazione AppHost seguente:

{
    "Parameters": {
        "example-parameter-name": "local-value"
    }
}

L'oggetto precedente JSON configura un parametro nella Parameters sezione della configurazione di AppHost. In altre parole, AppHost è in grado di trovare il parametro come configurato. Ad esempio, è possibile accedere al IDistributedApplicationBuilder.Configuration e accedere al valore usando la chiave Parameters:example-parameter-name:

var builder = DistributedApplication.CreateBuilder(args);

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

Important

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

Richiedere i valori dei parametri nel dashboard

Se il codice aggiunge parametri ma non li imposta, verrà visualizzato un prompt per configurare i Aspire valori nel dashboard. Viene visualizzato il messaggio Parametri non risolti ed è possibile selezionare Immettere i valori per risolvere il problema:

Screenshot dell'avviso del Aspire dashboard visualizzato quando sono presenti parametri non risolti.

Quando si seleziona Invio valori, Aspire viene visualizzato un modulo che è possibile usare per configurare i valori per ognuno dei parametri mancanti.

È anche possibile controllare il modo in cui il dashboard visualizza questi parametri usando questi metodi:

  • WithDescription: usare questo metodo per fornire una descrizione di testo che consente agli utenti di comprendere lo scopo del parametro. Per fornire una descrizione formattata in Markdown, usare il enableMarkdown: true parametro .
  • WithCustomInput: utilizzare questo metodo per fornire un metodo di callback che personalizza la finestra di dialogo dei parametri. Ad esempio, in questo callback è possibile personalizzare il valore predefinito, il tipo di input, l'etichetta e il testo segnaposto.

Questo codice illustra come impostare una descrizione e usare il callback:

#pragma warning disable ASPIREINTERACTION001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.

var externalServiceUrl = builder.AddParameter("external-service-url")
    .WithDescription("The URL of the external service.")
    .WithCustomInput(p => new()
    {
        InputType = InputType.Text,
        Value = "https://example.com",
        Name = p.Name,
        Placeholder = $"Enter value for {p.Name}",
        Description = p.Description
    });
var externalService = builder.AddExternalService("external-service", externalServiceUrl);

#pragma warning restore ASPIREINTERACTION001

Il codice esegue il rendering di questo controllo nel dashboard:

Screenshot della finestra di dialogo di completamento dei parametri del Aspire dashboard con le personalizzazioni.

Note

La finestra di dialogo del parametro del dashboard include una casella di controllo Salva nei segreti utente. Selezionare questa opzione per archiviare i valori sensibili nei segreti utente di AppHost per una protezione aggiuntiva. Per altre informazioni sui valori dei parametri dei segreti, vedere Valori dei segreti.

Rappresentazione dei parametri nel manifesto

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

{
  "resources": {
    "example-parameter-name": {
      "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 Parameters sezione della configurazione di AppHost.

Si consideri il file AppHost AppHost.cs di esempio seguente:

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

Si consideri ora il file appsettings.jsondi configurazione AppHost seguente:

{
    "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 ConnectionStrings sezione della configurazione di AppHost.

Note

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 Aspire denominazione, il termine "stringa di connessione" viene usato per rappresentare qualsiasi tipo di informazioni di connessione.

Si consideri il file AppHost AppHost.cs di esempio seguente:

var builder = DistributedApplication.CreateBuilder(args);

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

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

builder.Build().Run();

Note

L'utilizzo di WaitFor con una stringa di connessione farà attendere implicitamente la risorsa a cui la stringa di connessione si collega.

Si consideri ora il file appsettings.jsondi configurazione AppHost seguente:

{
    "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.

Creare stringhe di connessione con espressioni di riferimento

Se si vuole costruire una stringa di connessione dai parametri e assicurarsi che sia gestita correttamente sia nello sviluppo che nell'ambiente di produzione, usare AddConnectionString con un oggetto ReferenceExpression.

Ad esempio, se si dispone di un parametro segreto che archivia una piccola parte di una stringa di connessione, usare questo codice per inserirlo:

var secretKey = builder.AddParameter("secretkey", secret: true);

var connectionString = builder.AddConnectionString(
    "composedconnectionstring",
    ReferenceExpression.Create($"Endpoint=https://api.contoso.com/v1;Key={secretKey}"));

builder.AddProject<Projects.AspireReferenceExpressions_CatalogAPI>("catalogapi")
       .WithReference(connectionString)
       .WaitFor(connectionString);

È anche possibile usare espressioni di riferimento per aggiungere testo alle stringhe di connessione create dalle Aspire risorse. Ad esempio, quando si aggiunge una risorsa PostgreSQL alla soluzione Aspire, il server di database gira in un contenitore e viene formulata una stringa di connessione. Nel codice seguente, la proprietà Include Error Details aggiuntiva viene aggiunta a tale stringa di connessione prima che venga passata ai progetti consumatori.

var postgres = builder.AddPostgres("postgres");
var database = postgres.AddDatabase("db");

var pgConnectionString = builder.AddConnectionString(
    "pgdatabase",
    ReferenceExpression.Create($"{database};Include Error Details=true"));

builder.AddProject<Projects.AspireReferenceExpressions_CustomerAPI>("customerapi")
       .WithReference(pgConnectionString)
       .WaitFor(pgConnectionString);

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 per il insertionRows parametro viene letto dalla Parameters sezione del file appsettings.jsondi configurazione AppHost :

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

Vedere anche

  • Last updated on