Freigeben über

Upgrade auf .NET.NET Aspire 9.0

  • Artikel

.NET .NET Aspire 9.0 ist jetzt allgemein verfügbar. In diesem Artikel lernen Sie die Schritte zum Aktualisieren Ihrer vorhandenen .NET Aspire 8.x-Projekte auf .NET Aspire 9.0 kennen. Es gibt einige Möglichkeiten, wie Sie Ihre Projekte auf .NET.NET Aspire 9.0 aktualisieren können:

  • Aktualisieren Sie Ihre Projekte manuell auf .NET.NET Aspire 9.0.
  • Verwenden Sie den Upgrade-Assistenten, um Ihre Projekte auf .NET.NET Aspire 9.0 zu aktualisieren.

Trinkgeld

Wenn Sie bei .NET.NET Aspireneu sind, gibt es keinen Grund, etwas zu aktualisieren. Weitere Informationen finden Sie unter .NET.NET Aspire Einrichtung und Werkzeuge.

Voraussetzungen

Bevor Sie Ihre Projekte auf .NET.NET Aspire 9.0 aktualisieren, stellen Sie sicher, dass Sie über die folgenden Voraussetzungen verfügen:

Anmerkung

Sie können die .NET.NET Aspire Workload deinstallieren, da Sie sie nicht mehr benötigen.

dotnet workload uninstall aspire

Weitere Informationen finden Sie unter dotnet workload uninstall.

Wenn Sie die .NET.NET Aspire-Arbeitslast nicht deinstallieren und das neue .NET.NET Aspire-SDK- sowie die Vorlagen verwenden, werden sowohl .NET Aspire 8.0- als auch .NET Aspire 9.0-Vorlagen angezeigt.

Manuelles Upgrade auf .NET.NET Aspire 9.0

Um Ihre Projekte auf .NET.NET Aspire 9.0 zu aktualisieren, müssen Sie Ihre Projektdateien aktualisieren. Die folgenden Schritte führen Sie durch den Prozess:

  • Bearbeiten Sie Ihre App-Host-Projektdatei, um das neue .NET.NET Aspire 9.0 SDK (Aspire.AppHost.Sdk) zu verwenden.
  • Aktualisieren Sie die NuGet-Pakete in Ihren Projektdateien auf die neuesten Versionen.
  • Passen Sie Ihre Program.cs Datei an, um die neuen APIs zu verwenden, und entfernen Sie alle veralteten APIs.

Bearbeiten Sie die App-Hostprojektdatei

Um Ihr App-Hostprojekt auf .NET.NET Aspire 9.0 zu aktualisieren, müssen Sie die Projektdatei aktualisieren, um das neue 📦Aspire.AppHost.Sdkzu verwenden:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

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

</Project>

Optional aktualisieren Sie den Zielframework-Moniker (TFM)

.NET Aspire 9.0 läuft auf .NET 9.0, aber Sie können es auch auf .NET 8.0 ausführen. Anders ausgedrückt: Da Sie das .NET Aspire SDK verwenden und auf Version 9.0-Pakete verweisen, können Sie weiterhin auf .NET 8.0 abzielen. Wenn Sie Ihr .NET Aspire 9.0-Projekt auf .NET 9.0 ausführen möchten, müssen Sie die TargetFramework-Eigenschaft in der Projektdatei aktualisieren.

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
-   <TargetFramework>net8.0</TargetFramework>
+   <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

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

</Project>

Weitere Informationen zu TFMs finden Sie unter Target Frameworks in SDK-Formatprojekten: Neueste Versionen.

Allgemeine Unterschiede beim App-Hostprojekt

Wenn Sie alle vorherigen Schritte befolgt haben, sollte die App-Hostprojektdatei wie folgt aussehen:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
-   <TargetFramework>net8.0</TargetFramework>
+   <TargetFramework>net9.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
-   <PackageReference Include="Aspire.Hosting.AppHost" Version="8.0.0" />
+   <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  </ItemGroup>

</Project>

Die Änderungen umfassen das Hinzufügen des Aspire.AppHost.Sdk, das Update der TargetFramework-Eigenschaft auf net9.0und das Update des Aspire.Hosting.AppHost-Pakets auf Version 9.0.0.

Passen Sie Ihre Program.cs Datei an

Mit der Einführung von .NET.NET Aspire 9.0 gibt es einige einschneidende Änderungen. Einige APIs wurden ursprünglich als experimentell (mit dem ExperimentalAttribute) markiert und jetzt entfernt, während andere APIs jetzt als ObsoleteAttribute mit Details zu neuen Ersatz-APIs zugeschrieben werden. Sie müssen Ihre Program.cs Datei (und potenziell andere betroffene APIs) anpassen, um die neuen APIs zu verwenden. Wenn Sie den Upgrade-Assistenten verwenden, um Ihre Projekte zu aktualisieren, wird Ihre Program.cs Datei in den meisten Fällen automatisch angepasst.

Die vollständige Liste der Breaking Changes in .NET.NET Aspire 9.0 finden Sie in Breaking changes in .NET.NET Aspire 9.0.

Verwenden Sie den Upgrade-Assistenten

Der Upgrade-Assistent ist ein Tool, mit dem gezielte Projekte auf die neueste Version aktualisiert werden können. Wenn Sie noch nicht vertraut mit dem Upgrade-Assistenten sind, gibt es zwei Modalitäten, aus denen Sie wählen können:

Unabhängig davon, wie Sie den Upgrade-Assistenten installieren, können Sie ihn verwenden, um Ihre .NET Aspire 8.x-Projekte auf .NET Aspire 9.0 zu aktualisieren.

Zum Upgrade des .NET Aspire-App-Hostprojekts auf .NET Aspire 9.0 mit Visual Studioklicken Sie mit der rechten Maustaste auf das Projekt im -Projektmappen-Explorer und wählen Sie -Upgradeaus.

Wichtig

Wenn der Upgrade-Assistent noch nicht installiert ist, werden Sie aufgefordert, ihn zu installieren.

Der Upgrade-Assistent zeigt ein Willkommenspaket an. Wählen Sie die Option Aspire Upgrades aus:

Visual Studio: Willkommensseite des Upgrade-Assistenten mit .NET Aspire App-Hostprojekt.

Mit der Auswahl der Option Aspire Upgrades zeigt der Upgrade-Assistent die auswählbaren Zielkomponenten für das Upgrade an. Lassen Sie alle Optionen aktiviert, und wählen Sie Upgradeauswahlaus:

Visual Studio: Upgrade-Assistent .NET Aspire auswählbare Komponenten zum Upgrade.

Nachdem Sie die zu aktualisierenden Komponenten ausgewählt haben, zeigt der Upgrade-Assistent die Ergebnisse des Upgradevorgangs an. Wenn alles erfolgreich war, werden neben jeder Komponente grüne Häkchen angezeigt:

Visual Studio: Upgrade-Assistent .NET Aspire App-Hostprojekt erfolgreich aktualisiert.

Um das .NET.NET Aspire App-Hostprojekt zu aktualisieren, stellen Sie sicher, dass Sie die Upgrade Assistant CLI installiert haben. Öffnen Sie eine Terminalsitzung im Stammverzeichnis der .NET.NET Aspire App-Hostprojektdatei, und führen Sie den folgenden Befehl aus:

upgrade-assistant upgrade

Die Ausgabe ist interaktiv und erwartet von Ihnen, dass Sie den Upgradetyp auswählen. Wählen Sie die Option Aspire Upgrades aus:

 Selected options
────────────────────────────────────────────────────────────────────────────────────
 Source project     ..\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj

 Steps
────────────────────────────────
 Source project / Upgrade type
────────────────────────────────

How do you want to upgrade project AspireSample.AppHost?

> Aspire upgrades
    Upgrade to latest .NET Aspire version (aspire.latest)

  Upgrade project to a newer .NET version
    In-place project upgrade (framework.inplace)

  NuGet upgrades
    NuGet central package management (CPM) (nuget.cpm)

  Navigation
    Back
    Exit

Verwenden Sie die Tastatur, um nach oben ↑ oder nach unten ↓zu navigieren, und wählen Sie die Option Aspire Upgrade aus. Der Upgrade-Assistent fordert zur endgültigen Bestätigung auf. Geben Sie Y- ein, um mit dem Upgrade fortzufahren:

 Selected options
────────────────────────────────────────────────────────────────────────────────────
 Source project     ..\AspireSample\AspireSample.AppHost\AspireSample.AppHost.csproj
 Upgrade type       aspire.latest

 Steps
──────────────────────────────────────────
 Source project / Upgrade type / Upgrade
──────────────────────────────────────────

We have gathered all required options and are ready to do the upgrade. Do you want to continue? [y/n] (y):

Nach Abschluss des Upgradevorgangs zeigt der Upgrade-Assistent die Ergebnisse des Upgradevorgangs an:

Finalizing operation...
Complete: 3 succeeded, 0 failed, 7 skipped.

Aktualisieren der NuGet-Pakete

Um die neuesten Updates in Ihrer .NET.NET Aspire-Lösung zu nutzen, aktualisieren Sie alle NuGet-Pakete auf Version 9.0.0.

Visual Studio: Aktualisieren aller NuGet-Pakete für die .NET Aspire-Lösung.

Um Ihr App-Hostprojekt zu aktualisieren, verwenden Sie den folgenden .NET CLI-Befehl, um das Aspire.Hosting.AppHost Paket auf Version 9.0.0zu aktualisieren:

dotnet add package Aspire.Hosting.AppHost --version 9.0.0

Wenn bereits ein Paketverweis vorhanden ist, aktualisiert der dotnet add package Befehl den Verweis auf die angegebene Version. Weitere Informationen finden Sie unter dotnet add package.

Nachdem das App-Hostprojekt aktualisiert wurde, sollte die Projektdatei wie folgt aussehen:

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

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

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
    <IsAspireHost>true</IsAspireHost>
    <UserSecretsId>0afc20a6-cd99-4bf7-aae1-1359b0d45189</UserSecretsId>
  </PropertyGroup>

  <ItemGroup>
-   <PackageReference Include="Aspire.Hosting.AppHost" Version="8.0.0" />
+   <PackageReference Include="Aspire.Hosting.AppHost" Version="9.0.0" />
  </ItemGroup>

</Project>

Trinkgeld

Außerdem möchten Sie die NuGet-Pakete in Ihren anderen Projekten auf die neuesten Versionen aktualisieren.

Überprüfen Sie die Aktualisierung

Stellen Sie wie bei jedem Upgrade sicher, dass die App erwartungsgemäß ausgeführt wird und dass alle Tests bestehen. Erstellen Sie die Lösung, und suchen Sie nach Vorschlägen, Warnungen oder Fehlern im Ausgabefenster – beheben Sie alles, was zuvor kein Problem war. Wenn Probleme auftreten, informieren Sie uns, indem Sie ein GitHub Problemeinreichen.