Freigeben über

Upgrade auf eine neue .NET-Version

Neue .NET-Versionen werden jedes Jahr veröffentlicht. Viele Entwickler beginnen mit dem Upgradeprozess, sobald die neue Version verfügbar ist, während andere warten, bis die von ihnen verwendete Version nicht mehr unterstützt wird. Beim Upgrade-Prozess sind mehrere Aspekte zu beachten.

Häufige Gründe für das Upgrade auf eine neue .NET-Version:

  • Die aktuell verwendete .NET-Version wird nicht mehr unterstützt
  • Die neue Version unterstützt ein neues Betriebssystem
  • Die neue Version verfügt über eine wichtige API, Leistung oder Sicherheitsfunktion

Upgrade der Entwicklungsumgebung

Zum Upgrade auf eine neue .NET-Version ist das .NET SDK die primäre zu installierende Komponente. Sie enthält eine aktualisierte .NET CLI, Buildsystem und Laufzeitversion.

Die .NET-Website bietet Installationsprogramme und Archive, die Sie auf alle unterstützten Betriebssysteme und Architekturen herunterladen und verwenden können.

Einige Betriebssysteme verfügen über einen Paket-Manager, mit dem Sie auch eine neue .NET-Version installieren können, was Sie vielleicht bevorzugen.

Visual Studio installiert automatisch neue .NET SDK-Versionen. Für Visual Studio-Benutzer reicht es aus, ein Upgrade auf eine neuere Visual Studio-Version durchzuführen.

Quellcode aktualisieren

Die einzige erforderliche Änderung, um eine Anwendung zu aktualisieren, ist die Aktualisierung der TargetFramework-Eigenschaft in einer Projektdatei auf die neuere .NET-Version.

So funktioniert's:

  • Öffnen Sie die Projektdatei (die *.csproj-, *.vbproj- oder *.fsproj-Datei).
  • Ändern Sie den Wert der <TargetFramework>-Eigenschaft beispielsweise von net6.0 zu net8.0.
  • Das gleiche Muster gilt für die <TargetFrameworks>-Eigenschaft, wenn sie verwendet wird.

Tipp

Die Funktion zur Modernisierung und Aufrüstung der GitHub Copilot-App kann diese Änderungen automatisch durchführen.

Der nächste Schritt besteht darin, das Projekt (oder die Projektmappe) mit dem neuen SDK zu erstellen. Wenn zusätzliche Änderungen erforderlich sind, gibt das SDK Warnungen und Fehler aus, die Sie anleiten.

Möglicherweise müssen Sie dotnet workload restore ausführen, um Workloads mit der neuen SDK-Version wiederherzustellen.

Weitere Ressourcen:

Versionsfixierung

Wenn Sie Entwicklungstools wie das .NET SDK, Visual Studio oder andere Komponenten aktualisieren, können neue Verhaltensweisen, Analysewarnungen oder Breaking Changes auftreten, die sich auf Ihren Buildprozess auswirken. Durch das Anheften an eine Version können Sie Ihre Entwicklungsumgebung aktualisieren und gleichzeitig die Kontrolle behalten, wann bestimmte Komponenten in Ihren Projekten aktualisiert werden.

Das Anheften von Versionen bietet mehrere Vorteile:

  • Vorhersehbare Builds: Stellt konsistente Buildergebnisse auf unterschiedlichen Computern und CI/CD-Umgebungen sicher.
  • Schrittweise Einführung: Ermöglicht Es Ihnen, neue Features inkrementell und nicht alle gleichzeitig zu übernehmen.
  • Vermeiden Sie unerwartete Änderungen: Verhindert, dass neue Analyseregeln, SDK-Verhalten oder Paketversionen Buildfehler verursachen.
  • Teamkoordination: Ermöglicht Teams das Upgrade zu einem geplanten Zeitpunkt anstatt einzeln, wenn Tools aktualisiert werden.
  • Debuggen und Problembehandlung: Erleichtert das Isolieren von Problemen, wenn Sie steuern, welche Versionen geändert wurden.

In den folgenden Abschnitten werden verschiedene Mechanismen zum Steuern von Versionen verschiedener Komponenten in Ihren .NET-Projekten beschrieben:

Steuern der SDK-Version mit global.json

Sie können die .NET SDK-Version für ein Projekt oder eine Lösung mithilfe einer global.json-Datei festlegen. Diese Datei gibt an, welche SDK-Version beim Ausführen von .NET CLI-Befehlen verwendet werden soll, und ist unabhängig von der Laufzeitversion, auf die Ihr Projekt abzielt.

Erstellen Sie eineglobal.jsonDatei in Ihrem Lösungsstammverzeichnis :

dotnet new globaljson --sdk-version 9.0.100 --roll-forward latestFeature

Mit diesem Befehl wird die folgende global.json Datei erstellt, die das SDK an Version 9.0.100 oder einen späteren Patch- oder Featureband innerhalb der Hauptversion 9.0 anheftet:

{
  "sdk": {
    "version": "9.0.100",
    "rollForward": "latestFeature"
  }
}

Die rollForward Richtlinie steuert, wie die SDK-Version ausgewählt wird, wenn die genaue Version nicht verfügbar ist. Diese Konfiguration stellt sicher, dass Ihr Projekt beim Upgrade von Visual Studio oder beim Installieren eines neuen SDK weiterhin SDK 9.0.x verwendet, bis Sie die global.json Datei explizit aktualisieren.

Weitere Informationen finden Sie unter global.json Übersicht.

Steuern des Analyseverhaltens

Codeanalysatoren können neue Warnungen hinzufügen oder das Verhalten zwischen Versionen ändern. Sie können Analyseversionen steuern, um mithilfe der AnalysisLevel Eigenschaft konsistente Builds zu verwalten. Mit dieser Eigenschaft können Sie eine bestimmte Version von Analyseregeln sperren und verhindern, dass beim Upgrade des SDK neue Regeln eingeführt werden.

<PropertyGroup>
  <AnalysisLevel>9.0</AnalysisLevel>
</PropertyGroup>

Bei Festlegung auf 9.0,, sind nur die Analyseregeln aktiviert, die mit .NET 9 ausgeliefert wurden, auch wenn Sie das .NET 10 SDK verwenden. Dadurch wird verhindert, dass sich neue .NET 10-Analyseregeln auf Ihren Build auswirken, bis Sie bereit sind, sie zu beheben.

Weitere Informationen finden Sie unter AnalysisLevel.

Steuern von NuGet-Paketversionen

Durch die konsistente Verwaltung von Paketversionen in projekten können Sie unerwartete Updates verhindern und zuverlässige Builds verwalten.

Paketsperrdateien

Paketsperrdateien stellen sicher, dass Paketwiederherstellungsvorgänge die gleichen Paketversionen in verschiedenen Umgebungen verwenden. Die Sperrdatei (packages.lock.json) zeichnet die genauen Versionen aller Pakete und deren Abhängigkeiten auf.

Aktivieren Sie Sperrdateien in Ihrer Projektdatei:

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
</PropertyGroup>

Um sicherzustellen, dass Builds fehlschlagen, wenn die Sperrdatei nicht mehr aktuell ist:

<PropertyGroup>
  <RestorePackagesWithLockFile>true</RestorePackagesWithLockFile>
  <RestoreLockedMode>true</RestoreLockedMode>
</PropertyGroup>

Führen Sie dotnet restore aus, um die Datei packages.lock.json nach dem Aktivieren der Sperrdateien zu erstellen. Fügen Sie diese Datei zum Versionskontrollsystem hinzu.

Zentrale Paketverwaltung

Mit der zentralen Paketverwaltung (CPM) können Sie Paketversionen an einem zentralen Ort für alle Projekte in einer Lösung verwalten. Dieser Ansatz vereinfacht die Versionsverwaltung und sorgt für Konsistenz in allen Projekten.

Erstellen Sie eine Datei "Directory.Packages.props" im Lösungsstamm :

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>

  <ItemGroup>
    <PackageVersion Include="Azure.Identity" Version="1.17.0" />
    <PackageVersion Include="Microsoft.Extensions.AI" Version="9.10.1" />
  </ItemGroup>
</Project>

Verweisen Sie in Ihren Projektdateien auf Pakete, ohne eine Version anzugeben:

<ItemGroup>
  <PackageReference Include="Azure.Identity" />
  <PackageReference Include="Microsoft.Extensions.AI" />
</ItemGroup>

Paketquellenzuordnung

Mit der Paketquellzuordnung können Sie steuern, welche NuGet-Feeds für bestimmte Pakete verwendet werden, um die Sicherheit und Zuverlässigkeit zu verbessern.

Konfigurieren sie die Quellzuordnung in Ihrer nuget.config Datei:

<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
    <add key="contoso" value="https://contoso.com/packages/" />
  </packageSources>

  <packageSourceMapping>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
    <packageSource key="contoso">
      <package pattern="Contoso.*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Diese Konfiguration stellt sicher, dass alle Pakete, die mit Contoso. beginnen, nur aus dem contoso-Feed wiederhergestellt werden, während andere Pakete von nuget.org stammen.

Weitere Informationen finden Sie unter NuGet-Paketwiederherstellung.

MsBuild-Version steuern

Visual Studio unterstützt die parallele Installation mehrerer Versionen. Sie können beispielsweise Visual Studio 2026 und Visual Studio 2022 auf demselben Computer installieren. Jede Visual Studio-Version enthält ein entsprechendes .NET SDK. Wenn Sie Visual Studio aktualisieren, wird auch die enthaltene SDK-Version aktualisiert. Sie können jedoch weiterhin ältere SDK-Versionen verwenden, indem Sie sie separat von der .NET-Downloadseite installieren.

MSBuild-Versionen entsprechen Visual Studio-Versionen. Beispielsweise enthält Visual Studio 2022, Version 17.8, MSBuild 17.8. Das .NET SDK enthält auch MSBuild. Wenn Sie dotnet build verwenden, nutzen Sie die MSBuild-Version, die durch global.json oder das neueste installierte SDK angegeben wird.

So verwenden Sie eine bestimmte MSBuild-Version:

  • Verwenden Sie dotnet build mit einer angehefteten SDK-Version in global.json.
  • Starten Sie die entsprechende Visual Studio Developer-Eingabeaufforderung, die die Umgebung für die MSBuild dieser Visual Studio-Version einrichtet.
  • Rufen Sie MSBuild direkt aus einer bestimmten Visual Studio-Installation auf (z. B "C:\Program Files\Microsoft Visual Studio\2022\Enterprise\MSBuild\Current\Bin\MSBuild.exe". ).

Weitere Informationen finden Sie unter .NET SDK, MSBuild und Visual Studio-Versionsverwaltung.

Aktualisieren von Continuous Integration (CI)

CI-Pipelines folgen einem ähnlichen Updateprozess wie Projektdateien und Dockerfiles. In der Regel können Sie CI-Pipelines aktualisieren, indem Sie nur Versionswerte ändern.

Update der Hostingumgebung

Es gibt viele Muster, die für Hostinganwendungen verwendet werden. Wenn die Hostingumgebung die .NET-Laufzeit enthält, muss die neue Version der .NET-Laufzeit installiert werden. Unter Linux müssen Abhängigkeiten installiert werden, die sich jedoch in der Regel zwischen den verschiedenen .NET-Versionen nicht ändern.

Bei Containern müssen FROM Anweisungen geändert werden, um neue Versionsnummern einzuschließen.

Im folgenden Dockerfile-Beispiel wird das Abrufen eines ASP.NET Core 9.0-Images veranschaulicht.

FROM mcr.microsoft.com/dotnet/aspnet:9.0

In einem Clouddienst wie Azure App Service ist eine Konfigurationsänderung erforderlich.

Siehe auch

  • Last updated on