Avvio rapido: Crea la tua prima soluzione .NET.NET Aspire

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. .NET .NET Aspire è progettato per semplificare le connessioni e le configurazioni tra questi tipi di servizi. Questa guida introduttiva illustra come creare una soluzione modello di applicazione iniziale .NET.NET Aspire.

In questo quickstart esplorerai le seguenti attività:

Prerequisiti

Per usare .NET.NET Aspire, è necessario che il codice seguente sia installato in locale:

• .NET 8.0 o .NET 9.0
• Un runtime di contenitore conforme a OCI, ad esempio:
  • Docker Desktop o Podman. Per ulteriori informazioni, vedere Runtime del container.
• Un ambiente di sviluppo integrato (IDE) o un editor di codice, ad esempio:
  • Visual Studio 2022 versione 17.9 o successiva (facoltativo)
  • Visual Studio Code (facoltativo)
    • C# Dev Kit: Estensione (facoltativa)
  • JetBrains Rider con .NET.NET Aspire plug-in (facoltativo)

Per altre informazioni, vedere .NET.NET Aspire configurazione e strumentie .NET.NET Aspire SDK.

Creare il modello di .NET.NET Aspire

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

dotnet new install Aspire.ProjectTemplates

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

Per altre informazioni sui modelli disponibili, vedere .NET.NET 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 .NET AspireRedis.

dotnet dev-certs https --trust

dotnet run --project AspireSample/AspireSample.AppHost

1. L'app visualizza il dashboard .NET.NET Aspire 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.

   

   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.

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

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

Esplorare il dashboard .NET.NET Aspire

Quando si esegue un progetto .NET.NET Aspire, viene avviata una dashboard per monitorare varie parti dell'app. Il dashboard è simile allo screenshot seguente:

Visitare ogni pagina usando il riquadro di spostamento a sinistra per visualizzare informazioni diverse sulle risorse .NET.NET Aspire:

• Risorse: elenca le informazioni di base per tutti i singoli progetti di .NET nel progetto .NET 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.

  

• 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.

  

Per altre informazioni, vedere .NET.NET Aspire panoramica del dashboard.

Informazioni sulla struttura della soluzione .NET.NET Aspire

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: un progetto condiviso .NET.NET Aspire per gestire le configurazioni riutilizzate nei progetti della soluzione relative a resilienza , alla scoperta del servizio e alla telemetria .
• AspireSample.Web: progetto app ASP.NET CoreBlazor con configurazioni di servizio .NET Aspire predefinite, questo progetto dipende dal progetto AspireSample.ServiceDefaults. Per altre informazioni, vedere impostazioni predefinite del servizio .NET.NET Aspire.

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
     │    └─── Program.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 soluzione .NET.NET Aspire svolge un ruolo nella composizione dell'app. *. Il progetto di 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.

.NET .NET Aspire progetto ospite

Il progetto *.AppHost è responsabile del ruolo di orchestrazione e imposta la proprietà IsAspireHost del file di progetto su true:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <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="9.0.0" />
    <PackageReference Include="Aspire.Hosting.Redis" Version="9.0.0" />
  </ItemGroup>

</Project>

Per ulteriori informazioni, vedere la panoramica sull'orchestrazione .NET.NET Aspire e .NET.NET Aspire SDK.

Si consideri il file Program.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 hai utilizzato in precedenza il .NET host generico o il ASP.NET Core host Web, il modello di programmazione dell'host dell'app e il pattern del costruttore dovrebbero esserti familiari. Il codice precedente:

• Crea un'istanza di IDistributedApplicationBuilder chiamando DistributedApplication.CreateBuilder().
• Chiama AddRedis con il nome "cache" per aggiungere un Redisserver 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 .NET.NET 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 .NET.NET 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 ulteriori informazioni, consultare l'orchestrazione .NET.NET Aspire: 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 ulteriori informazioni, vedere la panoramica dell'orchestrazione .NET.NET Aspire.

.NET .NET Aspire progetto predefinito 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 .NET.NET Aspire contiene la proprietà IsAspireSharedProject 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="9.0.0" />
    <PackageReference Include="Microsoft.Extensions.ServiceDiscovery" Version="9.0.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.10.1" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.10.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Runtime" Version="1.10.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 impostazioni predefinite del servizio .NET.NET Aspire.

Orchestrare la comunicazione dei servizi

.NET .NET Aspire fornisce funzionalità di orchestrazione per facilitare la configurazione delle connessioni e la comunicazione tra le diverse parti dell'app. Il progetto Aspiraspiramsample.AppHost ha aggiunto il AspireSample.ApiService e i progetti di AspireSample.Web al modello di applicazione. Ha anche dichiarato i nomi come "webfrontend" per Blazor front-end, "apiservice" per il riferimento al progetto API. È stata aggiunta anche una risorsa Redisserver 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 la scoperta 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 "cache"Redis 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 risolto all'indirizzo corretto del progetto API.

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

Vedere anche

• Panoramica delle integrazioni .NET.NET Aspire
• rilevamento del servizio in .NET.NET Aspire
• .NET .NET Aspire predefinite del servizio
• controlli di integrità in .NET.NET Aspire
• .NET .NET Aspire telemetria
• Risoluzione dei problemi del certificato non attendibile localhost in .NET Aspire

Passaggi successivi