Configurazione dell'app

Suggerimento

Questo contenuto è un estratto dell'eBook, Blazor per gli sviluppatori di Web Forms ASP.NET per Azure, disponibile in .NET Docs o come PDF scaricabile gratuitamente che può essere letto offline.

Scarica PDF

Il modo principale per caricare la configurazione dell'app in Web Forms riguarda le voci del file web.config, sia nel server che in un file di configurazione correlato a cui fa riferimento web.config. È possibile usare l'oggetto statico ConfigurationManager per interagire con le impostazioni dell'app, le stringhe di connessione al repository dei dati e altri fornitori di configurazione estesa aggiunti all'app. È tipico visualizzare le interazioni con la configurazione dell'app, come illustrato nel codice seguente:

var configurationValue = ConfigurationManager.AppSettings["ConfigurationSettingName"];
var connectionString = ConfigurationManager.ConnectionStrings["MyDatabaseConnectionName"].ConnectionString;

Con ASP.NET Core e Blazor lato server, il file web.config PUÒ essere presente se l'app è ospitata in un server IIS di Windows. Tuttavia, non esiste alcuna interazione ConfigurationManager con questa configurazione ed è possibile ricevere una configurazione dell'app più strutturata da altre origini. Verrà illustrato come viene raccolta la configurazione e come è possibile accedere alle informazioni di configurazione da un file web.config.

Origini della configurazione

ASP.NET Core riconosce che esistono molte origini di configurazione da usare per la propria app. Il framework cerca di offrire il meglio di queste funzionalità per impostazione predefinita. La configurazione viene letta e aggregata da queste varie origini ASP.NET Core. I valori caricati successivamente per la stessa chiave di configurazione hanno la precedenza sui valori precedenti.

ASP.NET Core è stato progettato per essere compatibile con il cloud e per semplificare la configurazione delle app sia per gli operatori che per gli sviluppatori. ASP.NET Core è compatibile con l'ambiente e sa se è in esecuzione nell'ambiente Production o Development. L'indicatore di ambiente viene impostato nella variabile di ambiente di sistema ASPNETCORE_ENVIRONMENT. Se non viene configurato alcun valore, l'app viene eseguita per impostazione predefinita nell'ambiente Production.

L'app può attivare e aggiungere la configurazione da diverse origini, in base al nome dell'ambiente. Per impostazione predefinita, la configurazione viene caricata dalle risorse seguenti nell'ordine elencato:

1. il file appsettings.json, se presente
2. il file appsettings. {ENVIRONMENT_NAME}.json, se presente
3. File dei segreti utente su disco, se presente
4. Variabili di ambiente
5. Argomenti della riga di comando

appsettings.json formato e accesso

Il file appsettings.json può essere gerarchico con valori strutturati come il codice JSON seguente:

{
  "section0": {
    "key0": "value",
    "key1": "value"
  },
  "section1": {
    "key0": "value",
    "key1": "value"
  }
}

Quando viene presentato il JSON precedente, il sistema di configurazione rendere flat i valori figlio e fa riferimento ai relativi percorsi gerarchici completi. Un carattere di due punti (:) separano ogni proprietà nella gerarchia. Ad esempio, la chiave di configurazione section1:key0 accede al valore section1 dell'oggetto letterale key0.

Segreti utente

I segreti utente sono:

• Valori di configurazione archiviati in un file JSON nella workstation dello sviluppatore, al di fuori della cartella di sviluppo dell'app.
• Viene caricato solo quando viene eseguito nell'ambiente Development.
• Associato a un'app specifica.
• Gestito con il comando user-secrets dell’interfaccia della riga di comando di .NET.

Configurare l'app per l'archiviazione dei segreti eseguendo il comando user-secrets:

dotnet user-secrets init

Il comando precedente aggiunge un elemento UserSecretsId al file di progetto. L'elemento contiene un GUID, usato per associare i segreti all'app. È quindi possibile definire un segreto con il comando set. Ad esempio:

dotnet user-secrets set "Parent:ApiKey" "12345"

Il comando precedente rende disponibile la chiave di configurazione Parent:ApiKey nella workstation di uno sviluppatore con il valore 12345.

Per altre informazioni sulla creazione, l'archiviazione e la gestione dei segreti utente, vedere il documento Archiviazione sicura dei segreti delle app nello sviluppo in ASP.NET Core.

Variabili di ambiente

Il successivo set di valori caricati nella configurazione dell'app è costituito dalle variabili di ambiente del sistema. Tutte le impostazioni delle variabili di ambiente del sistema sono ora accessibili attraverso l'API di configurazione. I valori gerarchici vengono appiattiti e separati dai caratteri di due punti quando vengono letti all'interno dell'app. Tuttavia, alcuni sistemi operativi non consentono l'uso del carattere di due punti per i nomi delle variabili di ambiente. ASP.NET Core risolve questa limitazione convertendo i valori con doppi caratteri di sottolineatura (__) in un punto e virgola quando si accede. È possibile eseguire l'override del valore Parent:ApiKey della sezione dei segreti dell'utente precedente con la variabile di ambiente Parent__ApiKey.

Argomenti della riga di comando

Le configurazioni possono anche essere fornite come argomenti della riga di comando all'avvio dell'app. Usare la notazione a doppio trattino (--) o a barra obliqua (/) per indicare il nome del valore di configurazione da impostare e il valore da configurare. La sintassi è simile ai comandi seguenti:

dotnet run CommandLineKey1=value1 --CommandLineKey2=value2 /CommandLineKey3=value3
dotnet run --CommandLineKey1 value1 /CommandLineKey2 value2
dotnet run Parent:ApiKey=67890

Restituzione di web.config

Se l'app è stata distribuita su Windows in IIS, il file web.config configura comunque IIS per gestire l'applicazione. Per impostazione predefinita, IIS aggiunge un riferimento al modulo ASP.NET Core (ANCM). ANCM è un modulo IIS nativo che ospita l'app al posto del server Web Kestrel. Questa sezioneweb.config è simile al markup XML seguente:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <location path="." inheritInChildApplications="false">
    <system.webServer>
      <handlers>
        <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
      </handlers>
      <aspNetCore processPath=".\MyApp.exe"
                  stdoutLogEnabled="false"
                  stdoutLogFile=".\logs\stdout"
                  hostingModel="inprocess" />
    </system.webServer>
  </location>
</configuration>

La configurazione specifica dell'app può essere definita annidando un elemento environmentVariables nell'elemento aspNetCore. I valori definiti in questa sezione vengono presentati all'app ASP.NET Core come variabili di ambiente. Le variabili di ambiente vengono caricate in modo appropriato durante il segmento di avvio dell'app.

<aspNetCore processPath="dotnet"
      arguments=".\MyApp.dll"
      stdoutLogEnabled="false"
      stdoutLogFile=".\logs\stdout"
      hostingModel="inprocess">
  <environmentVariables>
    <environmentVariable name="ASPNETCORE_ENVIRONMENT" value="Development" />
    <environmentVariable name="Parent:ApiKey" value="67890" />
  </environmentVariables>
</aspNetCore>

Leggere la configurazione nell'app

ASP.NET Core fornisce la configurazione delle app tramite l'interfaccia IConfiguration. Questa interfaccia di configurazione deve essere richiesta dai componenti Blazor, dalle pagine Blazor e da qualsiasi altra classe gestita da ASP.NET Core che richiede l'accesso alla configurazione. Il framework ASP.NET Core popolerà automaticamente questa interfaccia con la configurazione risolta configurata in precedenza. In una pagina Blazor o nel markup Razor di un componente, è possibile iniettare l'oggetto IConfiguration con una direttiva @inject all'inizio del file .razor, in questo modo:

@inject IConfiguration Configuration

L'istruzione precedente rende l'oggetto IConfiguration disponibile come variabile Configuration in tutto il resto del modello Razor.

Le singole impostazioni di configurazione possono essere lette specificando la gerarchia delle impostazioni di configurazione ricercate come parametro dell'indicizzatore:

var mySetting = Configuration["section1:key0"];

È possibile recuperare intere sezioni di configurazione usando il metodo GetSection per recuperare una raccolta di chiavi in una posizione specifica, con una sintassi simile a GetSection("section1") per recuperare la configurazione della sezione1 nell'esempio precedente.

Configurazione fortemente tipizzata

Con Web Forms è stato possibile creare un tipo di configurazione fortemente tipizzato ereditato dal tipo ConfigurationSection e dai tipi associati. Un ConfigurationSection consentiva di configurare alcune regole aziendali e l'elaborazione di tali valori di configurazione.

In ASP.NET Core, è possibile specificare una gerarchia di classi che riceverà i valori di configurazione. Queste classi:

• Non è necessario ereditare da una classe padre.
• Deve includere public proprietà che corrispondono alle proprietà e ai riferimenti di tipo della struttura di configurazione da acquisire.

Per l'esempio appsettings.json precedente, è possibile definire le classi seguenti per acquisire i valori:

public class MyConfig
{
    public MyConfigSection section0 { get; set;}

    public MyConfigSection section1 { get; set;}
}

public class MyConfigSection
{
    public string key0 { get; set; }

    public string key1 { get; set; }
}

Questa gerarchia di classi può essere popolata aggiungendo la riga seguente al metodo Startup.ConfigureServices (o alla posizione appropriata in Program.cs usando la proprietà builder.Services anziché services):

services.Configure<MyConfig>(Configuration);

Nella parte restante dell'app è possibile aggiungere un parametro di input alle classi o a una direttiva @inject nei modelli Razor di tipo IOptions<MyConfig> per ricevere le impostazioni di configurazione fortemente tipate. La proprietà IOptions<MyConfig>.Value restituirà il valore MyConfig popolato dalle impostazioni di configurazione.

@inject IOptions<MyConfig> options
@code {
    var MyConfiguration = options.Value;
    var theSetting = MyConfiguration.section1.key0;
}

Altre informazioni sulla funzionalità Opzioni sono disponibili nel documento Opzioni modello in ASP.NET Core.

PrecedenteSuccessivo