Gemeinsam mit .NET 5 ist auch eine neue Version von ASP.NET Core erschienen. Die Neuerungen sind überschaubar und die Breaking Changes werden nur wenige betreffen. Das macht ein Upgrade von bestehenden Projekten auf .NET 5 schnell und unkompliziert. Eine Ausnahme bildet dabei das Blazor Framework, welches noch relativ jung ist und deswegen noch stärker angepasst wird. Dieser Blogbeitrag beschreibt die wichtigsten Neuerungen und zeigt wie eine Migration durchgeführt werden kann.
Record Types und Model Binding
Eine der großen Änderungen in C# 9 sind Record Types. Mit diesen ist es einfach, ein unveränderbares (immutable) Objekt zu erzeugen. Immutable Objekte sind bei APIs wünschenswert, da diese durch die Anwendung gereicht werden können, ohne dass eine Methode Werte im Objekt verändern kann. Record Types können jetzt beim Model Binding in MVC Controllern verwendet werden.
// Vorherige C# Versionen (mutable) public EdgeDevice { [Required] public string Name { get; set; } [Range(-273, 10000)] public int Temperature { get; set; } } // Vorherige C# Versionen (immutable) public EdgeDevice { [Required] public string Name { get; } [Range(-273, 10000)] public int Temperature { get; } public EdgeDevice(string name, int temperature) { Name = name; temperature = temperature; } } public class EdgeDeviceController { [HttpPost] public IActionResult AddDevice(EdgeDevice device) { ... } } // C# 9 public record EdgeDevice([Required] string Name, [Range(-273, 10000)] int Temperature);
Vor C# 9 musste man sich entscheiden, ob man entweder ein mutable Objekt oder ein immutable Objekt mit Konstruktor verwenden möchte. Record Types verbinden das Beste aus beiden Welten. Die Objekte sind immutable, können aber trotzdem über Objekt-Initialisierung erstellt werden. Zusätzlich wird bei Record Types die ToString() und Equals() Methoden überschrieben, was das Testen und Debuggen von APIs erleichtert. Ein weiterer Vorteil ist, dass die neue Syntax deutlich kompakter und auf das wesentliche beschränkt ist. Für mehr Informationen zu den Neuerungen in C# 9, gibt es unseren Blogpost: Welche Neuerungen kommen mit C# 9?.
Open API
Es war schon in vorherigen Versionen möglich, über Swashbuckle (oder andere Libraries) eine Middleware einzubinden, die die API im Projekt automatisch analysiert und daraus eine Open API bzw. ein Swagger Dokument erzeugt. Dieses Dokument wird über einen Endpunkt zusammen mit einer optionalen Web UI bereitgestellt, die das Testen von APIs erleichtert und Tools wie Postman teilweise überflüssig macht.
Ab jetzt ist die Open API-Integration standardmäßig aktiviert, wenn ein neues API-Projekt angelegt wird. Es empfiehlt sich auch bei bestehenden API-Projekten die Open API-Integration nachzuziehen, da sie Entwicklern und Testern die Arbeit erleichtert und schnell erledigt ist.
Wird ein neues API-Projekt mittels F5 gestartet, öffnet sich nun im Browser direkt die Open API UI. Auch das war in vorherigen Versionen schon möglich, ist jetzt aber standardmäßig aktiviert.
Sonstige Neuerungen
Für SignalR wurden sogenannte Hub Filter eingefügt. Diese sind ähnlich zu den Controller Filtern und ermöglichen das Ausführen von Code vor und nach einer Hub-Methode. Dies dient beispielsweise zum Debuggen oder Validieren von Nachrichten. Außerdem können jetzt mehrere Hub-Methoden parallel ausgeführt werden.
Auch in Kestrel wurden einige Neuerungen eingebaut, zum Beispiel das Ändern von Endpunkten im laufenden Betrieb oder Unterstützung von Server Name Indication (SNI).
Zur vereinfachten Authentifizierung mit dem Azure Active Directory existiert jetzt das neue Paket Microsoft.Identity.Web. Es ermöglicht das Abfragen von Informationen mittels der Microsoft Graph API. Das Paket kann auch in älteren ASP.NET Core Versionen verwendet werden.
Neben den oben genannten Änderungen gab es auch einige Neuerungen im Blazor Framework. Eine offizielle Übersicht über alle Neuerungen hierzu befindet sich hier.
Migrieren eines bestehenden Projekts
Durch die überschaubare Anzahl an Breaking Changes ist eine Migration schnell erledigt und sollte nur in wenigen Fällen zu Problemen führen.
Erster Schritt ist die Installation des .NET 5 SDKs. Mit der neusten Visual Studio 2019 Version ist dieses bereits installiert. Falls im Projekt eine global.json Datei verwendet wird, muss auch diese angepasst werden, um das neue SDK zu nutzen.
Der nächste Schritt ist das Ändern der Target Framework Version in den Projektdateien von netcoreapp3.1 auf net5.0.
Anschließend müssen nur noch die Paketverweise angepasst werden. Das kann entweder über die NuGet Oberfläche in Visual Studio oder von Hand erledigt werden. Dazu müssen die Pakete Microsoft.AspNetCore.*,
Microsoft.EntityFrameworkCore.*, Microsoft.Extensions.* und System.Net.Http.Json auf die neuste Version bzw. auf eine Version ab 5.0.0 gebracht werden.
Der größte Breaking Change ist das Model Binding von DateTime-Objekten. In älteren Versionen wurde beim Model Binding ein DateTime-Objekt mit der Zeitzone des Servers erstellt. Ab .NET 5 werden die DateTime-Objekte immer mit UTC als Zeitzone erzeugt. Werden über APIs Zeiten versendet, muss geprüft werden, ob sich noch alles so verhält wie gewünscht. Generell ist es empfehlenswert, Zeiten immer in der UTC-Zeitzone zu speichern und erst bei der Anzeige in die lokale Zeitzone umzuwandeln.
In den meisten Fällen ist die Migration damit abgeschlossen. In wenigen Fällen kann es noch zu Problemen kommen, die aber meistens über Compilerfehler oder Warnungen angezeigt werden. Die offizielle Liste der Breaking Changes findet sich hier.
Auch beim Hosting im Azure App Service oder Docker ist die Umstellung schnell gemacht. Im Azure App Service muss der Stack von .NET Core auf .NET umgestellt und die Framework Version .NET 5 ausgewählt werden. In Docker-Dateien wird das neue Docker Image mcr.microsoft.com/dotnet/aspnet:5.0 als Basis verwendet. Vorsicht ist bei der Azure Function App geboten. Hier gibt es zum Zeitpunkt des Blogposts noch keine Unterstützung für .NET 5.
Fazit
Das ASP.NET Core Framework hat eine gewisse Reife erreicht, was an der überschaubaren Anzahl an Neuerungen und Breaking Changes zu sehen ist. Neben allen funktionalen Änderungen hat sich in .NET 5 auch die Performance weiter verbessert. Projekte, die aktuell in der Entwicklung sind, sollten auf die neue Version aktualisiert werden. Da es sich bei .NET 5 um keinen LTS-Release handelt, sollte bei Projekten, die sich in Wartung befinden, gut überlegt werden, ob ein Upgrade sinnvoll ist.
Sprechen Sie uns an, wenn auch Sie Fragen zu Themen rund um .NET haben oder Hilfe bei Portierung Ihrer Anwendung nach .NET 5.0 in Ihrem Unternehmen benötigen. Wir führen Sie gerne ans Ziel.