Condividi tramite

Guida introduttiva: Creare la prima Aspire soluzione

Le app native del cloud spesso richiedono connessioni a vari servizi, ad esempio database, soluzioni di archiviazione e memorizzazione nella cache, provider di messaggistica o altri servizi Web. Aspire è progettato per semplificare le connessioni e le configurazioni tra questi tipi di servizi. Questa guida introduttiva illustra come creare una Aspire soluzione modello di applicazione iniziale.

In questo quickstart esplorerai le seguenti attività:

  • Creare un'app di base .NET configurata per usare Aspire.
  • Aggiungere e configurare un'integrazione Aspire per implementare la memorizzazione nella cache in fase di creazione del progetto.
  • Creare un'API e utilizzare il service discovery per connettersi ad essa.
  • Orchestrare la comunicazione tra un'interfaccia utente front-end, un'API back-end e una cache Redis locale.

Prerequisites

Per usare Aspire, è necessario quanto segue installato in locale:

Per altre informazioni, vedere Aspire Configurazione e strumenti e Aspire SDK.

Creare il Aspire modello

Per creare una nuova Aspire Starter Application, è possibile utilizzare Visual Studio, Visual Studio Codeo la CLI di .NET.

Visual Studio fornisce modelli di Aspire che gestiscono alcune configurazioni iniziali per te. Completare i passaggi seguenti per creare un progetto per questo avvio rapido.

  1. Nella parte superiore di Visual Studiopassare a File>Nuovo progetto>.

  2. Nella finestra di dialogo cercare Aspire e selezionare Aspire Starter App (App di avvio). Seleziona Avanti.

    Screenshot del Aspire modello di app di avvio.

  3. Nella schermata Configura il tuo nuovo progetto:

    • Immettere un Nome del progetto di AspireSample.
    • Lasciare i valori predefiniti rimanenti e selezionare Avanti.

  4. Nella schermata Informazioni aggiuntive:

    • Assicurarsi che sia selezionato .NET 9.0 (Supporto termini standard).
    • Assicurarsi che Usa Redis per la memorizzazione nella cache (richiede un runtime di contenitori supportato) sia selezionato e scegliere Crea.
    • Facoltativamente, è possibile selezionare Creare un progetto di test. Per altre informazioni, vedere Scrivere il primo Aspire test.

Visual Studio crea una nuova soluzione strutturata per l'uso di Aspire.

Visual Studio Code fornisce Aspire modelli di progetto che gestiscono automaticamente alcune configurazioni di installazione iniziali. Completare i passaggi seguenti per creare un progetto per questo avvio rapido.

  1. Da una nuova istanza di Visual Studio Code (senza una cartella aperta), selezionare il pulsante Crea progetto .NET.

  2. Selezionare il Aspire modello App di avvio .

    Screenshot del Aspire modello di app di avvio.

  3. Selezionare una cartella per il nuovo progetto e immettere un nome.

Se i modelli non sono già stati installatiAspire, eseguire il comando seguentedotnet new install:

dotnet new install Aspire.ProjectTemplates

Il comando CLI precedente .NET assicura che i modelli Aspire siano disponibili. Per creare l'app Aspire starter dal modello, eseguire il comando seguente dotnet new :

dotnet new aspire-starter --use-redis-cache --output AspireSample

Per ulteriori informazioni, consultare dotnet new. La CLI .NET crea una nuova soluzione strutturata per usare Aspire.

Per altre informazioni sui modelli disponibili, vedere Aspire Modelli.

Testare l'app localmente

L'app di esempio include un'app front-end Blazor che comunica con un progetto API minimo. Il progetto API viene usato per fornire falsi dati meteo al front-end. L'app front-end è configurata per usare l'individuazione dei servizi per connettersi al progetto API. Il progetto API è configurato per utilizzare la memorizzazione nella cache dell'output con Redis. L'app di esempio è ora pronta per il test. Si desidera verificare le condizioni seguenti:

  • I dati meteo vengono recuperati dal progetto API usando l'individuazione del servizio e visualizzati nella pagina meteo.
  • Le richieste successive vengono gestite tramite la cache di output configurata dall'integrazione AspireRedis.

Imposta in Visual Studio il progetto AspireSample.AppHost come progetto di avvio facendo clic con il tasto destro del mouse sul progetto nell' Esplora soluzioni e selezionando Imposta come progetto di avvio. Potrebbe essere già stato impostato automaticamente come progetto di avvio. Dopo aver impostato, premere F5 o (CTRL + F5 per l'esecuzione senza eseguire il debug) per eseguire l'app.

È necessario considerare attendibile il certificato ASP.NET Corelocalhost prima di eseguire l'app. Eseguire il comando seguente:

dotnet dev-certs https --trust

Per ulteriori informazioni, consultare Risoluzione dei problemi relativi al certificato localhost non attendibile in Aspire. Per informazioni dettagliate sulla risoluzione delle questioni relative ai certificati localhost su Linux, fare riferimento a ASP.NET Core: questione del repository GitHub numero #32842.

In Visual Studio Codepremere F5 per avviare l'app. Ti viene chiesto di selezionare una lingua e viene suggerito C#. Selezionare C# e quindi selezionare il progetto AspireSample.AppHost con la Configurazione Predefinita:

Screenshot della configurazione di avvio Visual Studio Code per il progetto AspireSample.AppHost.

Se è la prima volta che si esegue Aspireo si tratta di un nuovo computer con una nuova installazione .NET, viene richiesto di installare un certificato di localhost autofirmato e il progetto non verrà avviato:

Screenshot del Visual Studio Code che si interrompe su un'eccezione e invita a creare un certificato autofirmato attendibile.

Selezionare Sìe viene visualizzato un messaggio informativo che indica che il certificato autofirmato è stato creato correttamente :

Una screenshot del messaggio di successo Visual Studio Code per la creazione di un certificato autofirmato.

Se si verifica ancora un problema, chiudere tutte le finestre del browser e riprovare. Per ulteriori informazioni, consultare Risoluzione dei problemi relativi al certificato localhost non attendibile in Aspire.

Tip

Se si usa MacOS e Safari, quando il browser viene aperto se la pagina è vuota, potrebbe essere necessario aggiornare manualmente la pagina.

dotnet run --project AspireSample/AspireSample.AppHost

Per altre informazioni, vedere dotnet run.

  1. L'app visualizza il Aspire dashboard nel browser. Esamini il dashboard in modo più dettagliato in un secondo momento. Per il momento, trovare il progetto webfrontend nell'elenco delle risorse e selezionare l'endpoint localhost del progetto.

    Una schermata del Dashboard, con enfasi sull'endpoint Aspire del progetto web-frontend di localhost.

    La pagina principale dell'applicazione webfrontend visualizza "Hello, world!"

  2. Passare dalla home page alla pagina meteo usando il menu di navigazione a sinistra. Nella pagina meteo vengono visualizzati i dati meteo. Prendere nota mentale di alcuni dei valori rappresentati nella tabella delle previsioni.

  3. Continuare ad aggiornare occasionalmente la pagina per 10 secondi. Entro 10 secondi, vengono restituiti i dati memorizzati nella cache. Alla fine viene visualizzato un set diverso di dati meteo, poiché i dati vengono generati in modo casuale e la cache viene aggiornata.

la pagina Meteo dell'app webfrontend che mostra i dati meteo recuperati dall'API.

🤓 Felicitazioni! Hai creato ed eseguito la tua prima soluzione Aspire! Per arrestare l'app, chiudere la finestra del browser.

Per arrestare l'app in Visual Studio, selezionare Arresta il Debugging dal menu Debug.

Per arrestare l'app in Visual Studio Code, premere MAIUSC + F5oppure selezionare il pulsante Arresta nella parte superiore della finestra:

Screenshot del pulsante di arresto Visual Studio Code.

Per arrestare l'app, premere CTRL + C nella finestra del terminale.

Esaminare quindi la struttura e altre funzionalità della nuova Aspire soluzione.

Esplorare il Aspire dashboard

Quando si esegue un Aspire progetto, viene avviato un dashboard che consente di monitorare varie parti dell'app. Il dashboard è simile allo screenshot seguente:

Screenshot del Aspire dashboard che illustra la scheda Progetti.

Visitare ogni pagina usando lo spostamento a sinistra per visualizzare informazioni diverse sulle Aspire risorse:

  • Risorse: elenca le informazioni di base per tutti i singoli progetti di .NET nel progetto Aspire, come lo stato dell’applicazione, gli indirizzi degli endpoint e le variabili di ambiente caricate.

  • Console: visualizza l'output della console da ogni progetto nell'app.

  • Strutturata: mostra i log strutturati in formato tabella. Questi log supportano anche filtri di base, ricerca in formato libero e filtro a livello di log. Dovresti vedere i log del apiservice e del webfrontend. È possibile espandere i dettagli di ogni voce di log selezionando il pulsante Visualizza sul lato destro della riga.

  • Tracce: Visualizza le tracce per la tua applicazione, che consentono di monitorare i percorsi delle richieste tramite le tue app. Trova una richiesta per /weather e seleziona Visualizza a destra della pagina. Il dashboard dovrebbe visualizzare la richiesta in fasi durante lo spostamento tra le diverse parti dell'app.

    Screenshot che mostra una traccia del dashboard per il percorso /weather del webfrontend.Aspire

  • Metriche: visualizza vari strumenti e contatori disponibili e le loro dimensioni corrispondenti per l'app. Le metriche espongono in modo condizionale i filtri in base alle dimensioni disponibili.

    Uno screenshot che mostra una pagina delle metriche del dashboard Aspire per l'interfaccia web.

Per altre informazioni, vedere Aspire Panoramica del dashboard.

Comprendere la struttura della Aspire soluzione

La soluzione è costituita dai progetti seguenti:

  • AspireSample.ApiService: viene usato un progetto API minimo ASP.NET Core per fornire dati al front-end. Questo progetto dipende dal progetto condiviso AspireSample.ServiceDefaults.
  • AspireSample.AppHost: un progetto di orchestrazione progettato per connettere e configurare i diversi progetti e servizi della tua app. L'orchestratore deve essere impostato come progetto di avvio e dipende dai progetti AspireSample.ApiService e AspireSample.Web.
  • AspireSample.ServiceDefaults: progetto Aspire condiviso per gestire le configurazioni riutilizzate nei progetti nella soluzione in relazione alla resilienza, all'individuazione dei servizi e ai dati di telemetria.
  • AspireSample.Web: progetto app ASP.NET CoreBlazor con configurazioni di servizio Aspire predefinite, questo progetto dipende dal progetto AspireSample.ServiceDefaults. Per altre informazioni, vedere Aspire Impostazioni predefinite del servizio.

La directory AspireSample dovrebbe essere simile alla seguente struttura:

└───📂 AspireSample
     ├───📂 AspireSample.ApiService
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.ApiService.csproj
     │    └─── Program.cs
     ├───📂 AspireSample.AppHost
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.AppHost.csproj
     │    └─── AppHost.cs
     ├───📂 AspireSample.ServiceDefaults
     │    ├─── AspireSample.ServiceDefaults.csproj
     │    └─── Extensions.cs
     ├───📂 AspireSample.Web
     │    ├───📂 Components
     │    │    ├───📂 Layout
     │    │    │    ├─── MainLayout.razor
     │    │    │    ├─── MainLayout.razor.css
     │    │    │    ├─── NavMenu.razor
     │    │    │    └─── NavMenu.razor.css
     │    │    ├───📂 Pages
     │    │    │    ├─── Counter.razor
     │    │    │    ├─── Error.razor
     │    │    │    ├─── Home.razor
     │    │    │    └─── Weather.razor
     │    │    ├─── _Imports.razor
     │    │    ├─── App.razor
     │    │    └─── Routes.razor
     │    ├───📂 Properties
     │    │    └─── launchSettings.json
     │    ├───📂 wwwroot
     │    │    ├───📂 bootstrap
     │    │    │    ├─── bootstrap.min.css
     │    │    │    └─── bootstrap.min.css.map
     │    │    ├─── app.css
     │    │    └─── favicon.png
     │    ├─── appsettings.Development.json
     │    ├─── appsettings.json
     │    ├─── AspireSample.Web.csproj
     │    ├─── Program.cs
     │    └─── WeatherApiClient.cs
     └─── AspireSample.sln

Esplorare i progetti iniziali

Ogni progetto in una Aspire soluzione svolge un ruolo nella composizione dell'app. Il progetto *.Web è un'app ASP.NET CoreBlazor standard che fornisce un'interfaccia utente front-end. Per altre informazioni, vedere Novità di ASP.NET Core 9.0: Blazor. Il progetto *.ApiService è un progetto standard ASP.NET Core di modello API minimo. Entrambi questi progetti dipendono dal *. ServiceDefaults progetto, ovvero un progetto condiviso usato per gestire le configurazioni riutilizzate tra i progetti nella soluzione.

I due progetti di interesse in questo quickstart sono i progetti *.AppHost e *.ServiceDefaults descritti in dettaglio nelle sezioni seguenti.

Aspire progetto ospite

Il progetto *.AppHost è responsabile di agire come orchestratore di sviluppo locale.

<Project Sdk="Microsoft.NET.Sdk">

  <Sdk Name="Aspire.AppHost.Sdk" Version="9.5.2" />

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <UserSecretsId>2aa31fdb-0078-4b71-b953-d23432af8a36</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\AspireSample.ApiService\AspireSample.ApiService.csproj" />
    <ProjectReference Include="..\AspireSample.Web\AspireSample.Web.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Aspire.Hosting.AppHost" Version="13.0.0" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="13.0.0" />
  </ItemGroup>

</Project>

Per altre informazioni, vedere Aspire Panoramica dell'orchestrazione e Aspire SDK.

Si consideri il file AppHost.cs del progetto AspireSample.AppHost:

var builder = DistributedApplication.CreateBuilder(args);

var cache = builder.AddRedis("cache");

var apiService = builder.AddProject<Projects.AspireSample_ApiService>("apiservice");

builder.AddProject<Projects.AspireSample_Web>("webfrontend")
    .WithExternalHttpEndpoints()
    .WithReference(cache)
    .WaitFor(cache)
    .WithReference(apiService)
    .WaitFor(apiService);

builder.Build().Run();

Se in precedenza è stato usato l'host.NET generico o l'hostASP.NET Core Web, il modello di programmazione AppHost e il modello di generatore dovrebbero essere familiari. Il codice precedente:

  • Crea un'istanza di IDistributedApplicationBuilder chiamando DistributedApplication.CreateBuilder().
  • Chiama AddRedis con il nome "cache" per aggiungere un server Redis all'app, assegnando il valore restituito a una variabile denominata cache, di tipo IResourceBuilder<RedisResource>.
  • Chiama AddProject con il parametro di tipo generico fornito nei dettagli del progetto, aggiungendo il progetto AspireSample.ApiService al modello di applicazione. Si tratta di uno dei blocchi predefiniti fondamentali di Aspiree viene usato per configurare l'individuazione dei servizi e la comunicazione tra i progetti nell'app. L'argomento nome "apiservice" viene usato per identificare il progetto nel modello di applicazione e usato in seguito dai progetti che vogliono comunicare con esso.
  • Chiama di nuovo AddProject, questa volta aggiungendo il progetto AspireSample.Web al modello di applicazione. Concatena inoltre più chiamate a WithReference passando le variabili cache e apiService. L'API WithReference è un'altra API fondamentale di Aspire, che inserisce informazioni di individuazione del servizio o configurazione della stringa di connessione nel progetto aggiunto al modello di applicazione. Inoltre, le chiamate all'API di WaitFor vengono usate per assicurarsi che le risorse cache e apiService siano disponibili prima dell'avvio del progetto AspireSample.Web. Per altre informazioni, vedere Aspire Orchestrazione: In attesa di risorse.

Infine, l'app viene compilata ed eseguita. Il metodo DistributedApplication.Run() è responsabile dell'avvio dell'app e di tutte le relative dipendenze. Per altre informazioni, vedere Aspire Panoramica dell'orchestrazione.

Tip

La chiamata a AddRedis crea un contenitore Redis locale da usare per l'app. Se si preferisce puntare semplicemente a un'istanza di Redis esistente, è possibile usare il metodo AddConnectionString per fare riferimento a una stringa di connessione esistente. Per altre informazioni, vedere Fare riferimento alle risorse esistenti.

Aspire progetto di impostazioni predefinite del servizio

Il progetto *.ServiceDefaults è un progetto condiviso utilizzato per gestire le configurazioni riutilizzate nei progetti nella tua soluzione. Questo progetto garantisce che tutti i servizi dipendenti condividano la stessa resilienza, l'individuazione dei servizi e la configurazione OpenTelemetry. Un file di progetto condiviso Aspire contiene la IsAspireSharedProject proprietà impostata come true:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireSharedProject>true</IsAspireSharedProject>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />

    <PackageReference Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="10.0.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.14.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.14.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.14.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.14.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.14.0" />
  </ItemGroup>

</Project>

Il progetto dei valori predefiniti del servizio espone un metodo di estensione sul tipo IHostApplicationBuilder, chiamato AddServiceDefaults. Il progetto predefinito del servizio dal modello è un punto di partenza ed è possibile personalizzarlo in base alle proprie esigenze. Per altre informazioni, vedere Aspire Impostazioni predefinite del servizio.

Orchestrare la comunicazione dei servizi

Aspire offre funzionalità di orchestrazione per facilitare la configurazione delle connessioni e la comunicazione tra le diverse parti dell'app. Il progetto AspireSample.AppHost ha aggiunto i progetti AspireSample.ApiService e AspireSample.Web al modello dell'applicazione. Ha anche dichiarato i nomi come "webfrontend" per Blazor front-end e "apiservice" per il riferimento al progetto API. È stata aggiunta anche una risorsa server Redis etichettata "cache". Questi nomi vengono usati per configurare l'individuazione e la comunicazione dei servizi tra i progetti nell'app.

L'app front-end definisce un HttpClient tipizzato utilizzato per comunicare con il progetto API.

namespace AspireSample.Web;

public class WeatherApiClient(HttpClient httpClient)
{
    public async Task<WeatherForecast[]> GetWeatherAsync(
        int maxItems = 10,
        CancellationToken cancellationToken = default)
    {
        List<WeatherForecast>? forecasts = null;

        await foreach (var forecast in 
            httpClient.GetFromJsonAsAsyncEnumerable<WeatherForecast>(
                "/weatherforecast", cancellationToken))
        {
            if (forecasts?.Count >= maxItems)
            {
                break;
            }
            if (forecast is not null)
            {
                forecasts ??= [];
                forecasts.Add(forecast);
            }
        }

        return forecasts?.ToArray() ?? [];
    }
}

public record WeatherForecast(DateOnly Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

Il HttpClient è configurato per utilizzare il rilevamento dei servizi. Si consideri il codice seguente dal file Program.cs del progetto AspireSample.Web:

using AspireSample.Web;
using AspireSample.Web.Components;

var builder = WebApplication.CreateBuilder(args);

// Add service defaults & Aspire client integrations.
builder.AddServiceDefaults();
builder.AddRedisOutputCache("cache");

// Add services to the container.
builder.Services.AddRazorComponents()
    .AddInteractiveServerComponents();

builder.Services.AddHttpClient<WeatherApiClient>(client =>
    {
        // This URL uses "https+http://" to indicate HTTPS is preferred over HTTP.
        // Learn more about service discovery scheme resolution at https://aka.ms/dotnet/sdschemes.
        client.BaseAddress = new("https+http://apiservice");
    });

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error", createScopeForErrors: true);
    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
}

app.UseHttpsRedirection();

app.UseAntiforgery();

app.UseOutputCache();

app.MapStaticAssets();

app.MapRazorComponents<App>()
    .AddInteractiveServerRenderMode();

app.MapDefaultEndpoints();

app.Run();

Il codice precedente:

  • Chiama AddServiceDefaults, configurando le impostazioni predefinite condivise per l'app.
  • Chiama AddRedisOutputCache con la stessa connectionName usata al momento dell'aggiunta del contenitore Redis"cache" al modello di applicazione. In questo modo l'app viene configurata in modo da usare Redis per la memorizzazione nella cache dell'output.
  • Chiama AddHttpClient e configura l'HttpClient.BaseAddress in modo che sia "https+http://apiservice". Questo è il nome che è stato utilizzato quando si è aggiunto il progetto API al modello di applicazione e, con la configurazione del rilevamento dei servizi, viene automaticamente associato all'indirizzo corretto del progetto API.

Per altre informazioni, vedere Effettuare richieste HTTP con la classe HttpClient.

Aspire Interfaccia a riga di comando (CLI)

L'interfaccia della Aspire riga di comando (aspire comando ) è uno strumento multipiattaforma che fornisce funzionalità della riga di comando per creare, gestire, eseguire e pubblicare progetti poliglotta Aspire . Usare l'interfaccia della Aspire riga di comando per semplificare i flussi di lavoro di sviluppo e coordinare i servizi per le applicazioni distribuite.

Per altre informazioni, vedere Aspire Panoramica dell'interfaccia della riga di comando e Installare l'interfaccia Aspire della riga di comando.

Vedere anche

Passaggi successivi

Esercitazione: Aggiungi Aspire a un'applicazione esistente .NET

  • Last updated on