Delen via

Quickstart: Uw eerste .NET.NET Aspire-oplossing bouwen

  • Artikel

Cloudeigen apps vereisen vaak verbindingen met verschillende services, zoals databases, opslag- en cachingoplossingen, berichtenproviders of andere webservices. .NET .NET Aspire is ontworpen om verbindingen en configuraties tussen deze typen services te stroomlijnen. In deze quickstart ziet u hoe u een .NET.NET Aspire Starter-toepassingssjabloonoplossing maakt.

In deze quickstart verkent u de volgende taken:

  • Maak een eenvoudige .NET-app die is ingesteld voor het gebruik van .NET Aspire.
  • Voeg een .NET.NET Aspire-integratie toe en configureer deze om caching te implementeren tijdens het maken van een project.
  • Maak een API en gebruik servicedetectie om er verbinding mee te maken.
  • Coördineer de communicatie tussen een front-end UI, een back-end API en een lokale Redis-cache.

Voorwaarden

Als u met .NET.NET Aspirewilt werken, hebt u het volgende lokaal geïnstalleerd:

Zie .NET.NET Aspire setup en hulpprogramma'sen .NET.NET Aspire SDK-voor meer informatie.

De .NET.NET Aspire-sjabloon maken

Als u een nieuwe .NET Aspire Starter-toepassing wilt maken, kunt u Visual Studio, Visual Studio Codeof de .NET CLI gebruiken.

Visual Studio biedt .NET Aspire sjablonen die enkele initiële configuraties voor u verwerken. Voer de volgende stappen uit om een project te maken voor deze quickstart:

  1. Ga bovenaan Visual Studionaar Bestand>Nieuw>Project.

  2. Zoek in het dialoogvenster naar Aspire en selecteer .NET.NET Aspire Starter-app. Kies Volgende.

    Een schermopname van de sjabloon .NET.NET Aspire Starter-app.

  3. In het scherm Uw nieuwe project configureren:

    • Voer een projectnaam van AspireSamplein.
    • Laat rest van de waarden op standaard staan en selecteer Volgende.

  4. Op het scherm Aanvullende informatie:

    • Zorg ervoor dat .NET 9.0 (Standaard Term Ondersteuning) is geselecteerd.
    • Zorg ervoor dat Redis gebruiken voor caching (hiervoor is een ondersteunde containerruntime vereist) is ingeschakeld en selecteer maken.
    • U kunt desgewenst Een testproject makenselecteren. Zie Uw eerste .NET.NET Aspire testschrijven voor meer informatie.

Visual Studio maakt een nieuwe oplossing die is gestructureerd om .NET Aspirete gebruiken.

Visual Studio Code biedt .NET Aspire projectsjablonen die enkele initiële configuraties voor u verwerken. Voer de volgende stappen uit om een project te maken voor deze quickstart:

  1. Selecteer in een nieuw exemplaar van Visual Studio Code (zonder een map te openen) de knop Maak project .NET.

  2. Selecteer de sjabloon .NET.NET Aspire Starter-app.

    Een schermopname van de sjabloon .NET.NET Aspire Starter-app.

Als u de .NET.NET Aspire-sjablonen nog niet hebt geïnstalleerd, voert u de volgende dotnet new install opdracht uit:

dotnet new install Aspire.ProjectTemplates

De voorgaande .NET CLI-opdracht zorgt ervoor dat de .NET Aspire sjablonen beschikbaar zijn. Als u de .NET.NET Aspire Starter-app wilt maken op basis van de sjabloon, voert u de volgende dotnet new opdracht uit:

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

Voor meer informatie, zie dotnet new. De .NET CLI maakt een nieuwe oplossing die is gestructureerd voor het gebruik van .NET Aspire.

Zie .NET.NET Aspire sjablonenvoor meer informatie over de beschikbare sjablonen.

De app lokaal testen

De voorbeeld-app bevat een front-end-Blazor-app die communiceert met een minimaal API-project. Het API-project wordt gebruikt om valse weergegevens aan de front-end te leveren. De front-end-app is geconfigureerd voor het gebruik van servicedetectie om verbinding te maken met het API-project. Het API-project is geconfigureerd voor het gebruik van uitvoercache met Redis. De voorbeeld-app is nu klaar voor testen. U wilt de volgende voorwaarden controleren:

  • Weerdata wordt opgehaald uit het API-project met behulp van service-ontdekking en weergegeven op de weerpagina.
  • Volgende aanvragen worden verwerkt via de uitvoercaching die is geconfigureerd door de .NET AspireRedis-integratie.

Stel in Visual Studiohet AspireSample.AppHost project in als het opstartproject door met de rechtermuisknop op het project te klikken in de Solution Explorer- en Instellen als opstartprojectte selecteren. Het is mogelijk al automatisch ingesteld als het opstartproject. Druk na het instellen op F5 of (Ctrl + F5 om zonder foutopsporing uit te voeren) om de app uit te voeren.

U moet het ASP.NET Corelocalhost-certificaat vertrouwen voordat u de app uitvoert. Voer de volgende opdracht uit:

dotnet dev-certs https --trust

Voor meer informatie, zie Problemen met niet-vertrouwde certificaten localhost in .NET Aspireoplossen. Zie ASP.NET Corevoor uitgebreide informatie over het oplossen van problemen met localhost certificaten op Linux: GitHub opslagplaatsprobleem #32842.

Druk in Visual Studio Codeop F5- om de app te starten. U wordt gevraagd om te selecteren welke taal en C# wordt voorgesteld. Selecteer C# en selecteer vervolgens het project AspireSample.AppHost met de Standaardconfiguratie:

Een schermopname van de Visual Studio Code startconfiguratie voor het Project AspireSample.AppHost.

Als dit de eerste keer is dat u .NET Aspireuitvoert, of als het een nieuwe computer met een nieuwe .NET installatie is, wordt u gevraagd een zelfondertekend localhost-certificaat te installeren. Het project wordt dan niet gestart:

Een schermopname van de Visual Studio Code die stopt bij een uitzondering en vraagt om een vertrouwd zelfondertekend certificaat te maken.

Selecteer Jaen u ziet een informatiebericht dat aangeeft dat het zelfondertekende certificaat is gemaakt:

Een schermopname van het bericht Visual Studio Code geslaagd voor het maken van een zelfondertekend certificaat.

Als u nog steeds een probleem ondervindt, sluit u alle browservensters en probeert u het opnieuw. Zie Problemen met niet-vertrouwde localhost-certificaten in .NET Aspireoplossen voor meer informatie.

Tip

Als u macOS gebruikt en Safari gebruikt, moet u de pagina mogelijk handmatig vernieuwen wanneer uw browser wordt geopend als de pagina leeg is.

dotnet run --project AspireSample/AspireSample.AppHost

Voor meer informatie, zie dotnet run.

  1. De app geeft het .NET.NET Aspire dashboard weer in de browser. U bekijkt het dashboard later in meer detail. Zoek voorlopig het webfrontend project in de lijst met resources en selecteer het localhost-eindpunt van het project.

    Een schermopname van het .NET Aspire Dashboard, waarin het localhost-eindpunt van het webfrontend-project wordt gemarkeerd.

    Op de startpagina van de webfrontend-app wordt 'Hallo wereld!' weergegeven

  2. Navigeer vanaf de startpagina naar de weerpagina via de navigatie aan de linkerkant. Op de weerpagina worden de weergegevens weergegeven. Noteer een aantal waarden in de prognosetabel.

  3. Blijf de pagina af en toe 10 seconden vernieuwen. Binnen 10 seconden worden de gegevens in de cache geretourneerd. Uiteindelijk wordt een andere set van weergegevens weergegeven, omdat de gegevens willekeurig worden gegenereerd en de cache wordt bijgewerkt.

De weerpagina van de webfrontend-app met de weergegevens die zijn opgehaald uit de API.

🤓 Gefeliciteerd! U hebt uw eerste .NET.NET Aspire oplossing gemaakt en uitgevoerd. Sluit het browservenster om de app te stoppen.

Als u de app in Visual Studiowilt stoppen, selecteert u de Foutopsporing stoppen in het menu Foutopsporing.

Als u de app in Visual Studio Codewilt stoppen, drukt u op Shift + F5of selecteert u de knop Stoppen boven in het venster:

Een schermopname van de knop Visual Studio Code stoppen.

Als u de app wilt stoppen, drukt u op Ctrl + C- in het terminalvenster.

Onderzoek vervolgens de structuur en andere functies van uw nieuwe .NET.NET Aspire-oplossing.

Het .NET.NET Aspire-dashboard verkennen

Wanneer u een .NET.NET Aspire-project uitvoert, wordt een dashboard gestart dat u gebruikt om verschillende onderdelen van uw app te bewaken. Het dashboard lijkt op de volgende schermopname:

Een schermopname van het .NET.NET Aspire Dashboard, waarin het tabblad Projecten wordt weergegeven.

Ga naar elke pagina met behulp van de linkernavigatiebalk om verschillende informatie over de .NET.NET Aspire resources weer te geven:

  • Resources: bevat basisinformatie voor alle afzonderlijke .NET projecten in uw .NET Aspire-project, zoals de app-status, eindpuntadressen en de omgevingsvariabelen die zijn geladen.

  • Console: geeft de console-uitvoer weer van elk van de projecten in uw app.

  • Structured: Geeft gestructureerde logboeken weer in tabelindeling. Deze logboeken bieden ook ondersteuning voor basisfilters, vrije zoekopdrachten en filteren op logboekniveau. U moet de logboeken uit de apiservice en de webfrontendzien. U kunt de details van elke logboekvermelding uitvouwen door de knop Weergave aan de rechterkant van de rij te selecteren.

  • Traces: geeft de traceringen voor uw toepassing weer, waarmee aanvraagpaden via uw apps kunnen worden bijgehouden. Zoek een aanvraag voor /weather en selecteer Weergave aan de rechterkant van de pagina. Het dashboard moet de aanvraag in fasen weergeven terwijl deze door de verschillende onderdelen van uw app loopt.

    Een schermopname met een .NET.NET Aspire dashboard trace voor de webfrontend/weather-route.

  • Metingen: geeft verschillende instrumenten en meters weer die zichtbaar zijn en de bijbehorende dimensies voor uw app. Metrische gegevens stellen filters voorwaardelijk beschikbaar op basis van hun beschikbare dimensies.

    Een schermopname met een pagina met metrische gegevens van het Aspire dashboard voor de webfrontend.

Zie .NET.NET Aspire dashboardoverzichtvoor meer informatie.

Inzicht in de .NET.NET Aspire oplossingsstructuur

De oplossing bestaat uit de volgende projecten:

  • AspireSample.ApiService: er wordt een ASP.NET Core minimale API-project gebruikt om gegevens aan de front-end te leveren. Dit project is afhankelijk van het gedeelde AspireSample.ServiceDefaults project.
  • AspireSample.AppHost: een orchestratorproject dat is ontworpen om de verschillende projecten en services van uw app te verbinden en te configureren. De orchestrator moet worden ingesteld als het Startup-projecten is afhankelijk van de projecten AspireSample.ApiService en AspireSample.Web projecten.
  • AspireSample.ServiceDefaults: een .NET.NET Aspire gedeeld project voor het beheren van configuraties die opnieuw worden gebruikt in de projecten in uw oplossing met betrekking tot tolerantie, servicedetectieen telemetrie.
  • AspireSample.Web: Een ASP.NET CoreBlazor App-project met standaardserviceconfiguraties .NET Aspire, is dit project afhankelijk van het AspireSample.ServiceDefaults project. Zie .NET.NET Aspire standaardinstellingenvoor meer informatie.

Uw AspireSample map moet er ongeveer uitzien als de volgende structuur:

└───📂 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

De startersprojecten verkennen

Elk project in een .NET.NET Aspire oplossing speelt een rol in de samenstelling van uw app. De *.Web-project is een standaard ASP.NET CoreBlazor-app die een front-end gebruikersinterface biedt. Zie Wat is er nieuw in ASP.NET Core 9.0: Blazorvoor meer informatie. De *. ApiService project is een standaardproject ASP.NET Core Minimale API-sjabloon. Beide projecten zijn afhankelijk van de *. ServiceDefaults project, een gedeeld project dat wordt gebruikt voor het beheren van configuraties die opnieuw worden gebruikt in projecten in uw oplossing.

De twee projecten die in deze quickstart van belang zijn, zijn de *. AppHost en *. ServiceDefaults projecten die in de volgende secties worden beschreven.

.NET .NET Aspire host project

De *. AppHost project is verantwoordelijk voor het fungeren als de orchestrator en stelt de eigenschap IsAspireHost van het projectbestand in op 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>

Voor meer informatie, zie .NET.NET Aspire orkestratieoverzicht en .NET.NET Aspire SDK.

Bekijk het Program.cs bestand van het project 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();

Als u de .NET Generic Host- of de ASP.NET Core-webhost eerder hebt gebruikt, moet het programmeermodel en het opbouwpatroon van de app-host bekend zijn. De voorgaande code:

  • Hiermee maakt u een IDistributedApplicationBuilder exemplaar door aanroep van DistributedApplication.CreateBuilder().
  • Roept AddRedis aan met de naam "cache" om een Redisserver toe te voegen aan de app, waarbij de geretourneerde waarde wordt toegewezen aan een variabele met de naam cache, wat van het type IResourceBuilder<RedisResource>is.
  • Roeping van AddProject met de generieke typeparameter en de details van het project, waarbij het AspireSample.ApiService project aan het toepassingsmodel wordt toegevoegd. Dit is een van de fundamentele bouwstenen van .NET.NET Aspireen wordt gebruikt om servicedetectie en communicatie tussen de projecten in uw app te configureren. Het naamargument "apiservice" wordt gebruikt om het project in het toepassingsmodel te identificeren en later te gebruiken door projecten die ermee willen communiceren.
  • Roept AddProject opnieuw aan, deze keer voegt u het AspireSample.Web project toe aan het toepassingsmodel. Het koppelt ook meerdere aanroepen om de cache en apiService variabelen aan WithReference door te geven. De WithReference-API is een andere fundamentele API van .NET.NET Aspire, waarmee servicedetectie- of verbindingsreeksconfiguratie wordt ingevoerd in het project dat wordt toegevoegd aan het toepassingsmodel. Daarnaast worden aanroepen naar de WaitFor-API gebruikt om ervoor te zorgen dat de cache en apiService resources beschikbaar zijn voordat het AspireSample.Web project wordt gestart. Voor meer informatie, zie .NET.NET Aspire orchestratie: Wachten op bronnen.

Ten slotte wordt de app gebouwd en uitgevoerd. De DistributedApplication.Run()-methode is verantwoordelijk voor het starten van de app en alle bijbehorende afhankelijkheden. Raadpleeg .NET.NET Aspire orkestratieoverzichtvoor meer informatie.

Fooi

De aanroep naar AddRedis maakt een lokale Redis-container aan die de app kan gebruiken. Als u liever naar een bestaand Redis exemplaar verwijst, kunt u de AddConnectionString methode gebruiken om te verwijzen naar een bestaande verbindingsreeks. Raadpleeg bestaande bronnenvoor meer informatie.

standaardproject voor .NET-.NET Aspire-service

De *. ServiceDefaults project is een gedeeld project dat wordt gebruikt voor het beheren van configuraties die opnieuw worden gebruikt in de projecten in uw oplossing. Dit project zorgt ervoor dat alle afhankelijke services dezelfde tolerantie, servicedetectie en OpenTelemetry configuratie delen. Een gedeeld .NET.NET Aspire projectbestand bevat de eigenschap IsAspireSharedProject ingesteld als 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.1.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>

In het standaardproject van de service wordt een extensiemethode weergegeven op het IHostApplicationBuilder type, met de naam AddServiceDefaults. Het standaardproject van de service op basis van de sjabloon is een uitgangspunt en u kunt het aanpassen aan uw behoeften. Zie .NET.NET Aspire servicestandaardenvoor meer informatie.

Servicecommunicatie organiseren

.NET .NET Aspire biedt indelingsfuncties om te helpen bij het configureren van verbindingen en communicatie tussen de verschillende onderdelen van uw app. Het project AspireSample.AppHost heeft het project AspireSample.ApiService en AspireSample.Web projecten toegevoegd aan het toepassingsmodel. Het heeft ook hun namen gedeclareerd als "webfrontend" voor Blazor front-end, "apiservice" voor de API-projectreferentie. Daarnaast is er een Redisserver resource met het label "cache" toegevoegd. Deze namen worden gebruikt voor het configureren van servicedetectie en communicatie tussen de projecten in uw app.

De front-end-app definieert een getypte HttpClient die wordt gebruikt om te communiceren met het API-project.

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

De HttpClient is geconfigureerd voor het gebruik van servicedetectie. Bekijk de volgende code uit het Program.cs-bestand van het project 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();

De voorgaande code:

  • Roept AddServiceDefaultsaan, waarbij de gedeelde standaardwaarden voor de app worden geconfigureerd.
  • Roept AddRedisOutputCache aan met dezelfde connectionName die is gebruikt bij het toevoegen van de Redis container "cache" aan het toepassingsmodel. Hiermee configureert u de app voor het gebruik van Redis voor uitvoercache.
  • Roept AddHttpClient aan en configureert de HttpClient.BaseAddress als "https+http://apiservice". Dit is de naam die is gebruikt bij het toevoegen van het API-project aan het toepassingsmodel en met geconfigureerde servicediscovery wordt automatisch doorverwezen naar het juiste adres van het API-project.

Zie HTTP-aanvragen maken met de HttpClient-klasse voor meer informatie.

Zie ook

Volgende stappen

Zelfstudie: .NET Aspire toevoegen aan een bestaande .NET-app