Migrieren von der ASP.NET-Web-API zu ASP.NET Core

Artikel
11/06/2024

ASP.NET Core fasst die MVC- und Web-API-App-Modelle von ASP.NET 4.x in einem einzelnen Programmiermodell zusammen, das als ASP.NET Core MVC bezeichnet wird.

In diesem Artikel wird gezeigt, wie Sie den Produktcontroller, der in Erste Schritte mit ASP.NET-Web-API 2 erstellt wurde, zu ASP.NET Core migrieren.

Visual Studio 2022 mit der Workload ASP.NET und Webentwicklung
.NET 6.0 SDK

Erstellen des neuen ASP.NET Core-Web-API-Projekts

Visual Studio
Visual Studio Code

Klicken Sie im Menü Datei auf Neu>Projekt.
Geben Sie Web-API in das Suchfeld ein.
Wählen Sie die ASP.NET Core-Web-API-Vorlage aus, und klicken Sie auf Weiter.
Geben Sie im Dialogfeld Neues Projekt konfigurieren dem Projekt den Namen ProductsCore, und wählen Sie dann Weiter aus.
Im Dialogfeld Zusätzliche Informationen:
1. Vergewissern Sie sich, dass das Framework auf .NET 6.0 (Langfristiger Support) festgelegt ist.
2. Vergewissern Sie sich, dass das Kontrollkästchen Controller verwenden (zur Verwendung minimaler APIs deaktivieren) aktiviert ist.
3. Deaktivieren Sie OpenAPI-Unterstützung aktivieren.
4. Klicken Sie auf Erstellen.

Öffnen Sie das integrierte Terminal.
Wechseln Sie mit dem Befehl cd' zu dem Ordner, der den Projektordner enthalten soll.
Führen Sie die folgenden Befehle aus, um ein neues Web-API-Projekt zu erstellen und in Visual Studio Code zu öffnen:
```
dotnet new webapi -o ProductsCore --no-openapi
cd ProductsCore
code -r ../ProductsCore
```

Entfernen der Vorlagendateien vom Typ WeatherForecast

Entfernen Sie die Beispieldateien WeatherForecast.cs und Controllers/WeatherForecastController.cs aus dem neuen Projekt ProductsCore.
Öffnen Sie Properties\launchSettings.json.
Ändern Sie die launchUrl-Eigenschaften von weatherforcast in productscore.

Die Konfiguration für die ASP.NET Core-Web-API

ASP.NET Core verwendet nicht den Ordner App_Start oder die Datei Global.asax. Die Datei web.config wird zur Veröffentlichungszeit hinzugefügt. Weitere Informationen finden Sie unter web.config-Datei.

Die Datei Program.cs enthält Folgendes:

Sie ersetzt Global.asax.
Behandelt alle App-Startaufgaben

Weitere Informationen finden Sie unter Anwendungsstart in ASP.NET Core.

Hier sehen Sie den Anwendungsstartcode aus der ASP.NET Core-Datei Program.cs:

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();

var app = builder.Build();

// Configure the HTTP request pipeline.

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Kopieren des Modells Product

Visual Studio
Visual Studio Code

Klicken Sie im Projektmappen-Explorer mit der rechten Maustaste auf das Projekt. Klicken Sie auf Hinzufügen>Neuer Ordner. Geben Sie dem Ordner den Namen Models.
Klicken Sie mit der rechten Maustaste auf den Ordner Modelle. Wählen Sie Hinzufügen>Klasse aus. Nennen Sie die Klasse Product, und wählen Sie Hinzufügen aus.
Ersetzen Sie den Vorlagenmodellcode durch Folgendes:

namespace ProductsCore.Models
{
    public class Product
    {
        public int Id { get; set; }
        public string? Name { get; set; }
        public string? Category { get; set; }
        public decimal Price { get; set; }
    }
}

Der oben hervorgehobene Code ändert Folgendes:

Die Anmerkung ? wurde hinzugefügt, um die Eigenschaften Name und Category als Nullable-Verweistypen zu deklarieren.

Durch die Verwendung des in C# 8 eingeführten Nullable-Features kann ASP.NET Core bei der Behandlung von Verweistypen zusätzliche Codeflussanalysen und Sicherheit zur Kompilierzeit bereitstellen. Dazu gehört beispielsweise der Schutz vor null-Verweisausnahmen.

In diesem Fall sollen Name und Category Nullable-Typen sein.

Bei ASP.NET Core 6.0-Projekten sind Nullable-Verweistypen standardmäßig aktiviert. Weitere Informationen finden Sie unter Nullable-Verweistypen.

Kopieren von ProductsController

Visual Studio
Visual Studio Code

Klicken Sie mit der rechten Maustaste auf den Ordner Controller.
Wählen Sie Hinzufügen > Controller... aus.
Wählen Sie im Dialogfeld Neues Gerüstelement hinzufügen die Option MVC-Controller – leer und anschließend Hinzufügen aus.
Nennen Sie den Controller ProductsController, und wählen Sie Hinzufügen aus.
Ersetzen Sie den Vorlagencontrollercode durch Folgendes:

using Microsoft.AspNetCore.Mvc;
using ProductsCore.Models;

namespace ProductsCore.Controllers;

[Route("api/[controller]")]
[ApiController]
public class ProductsController : ControllerBase
{
    Product[] products = new Product[]
    {
            new Product
            {
                Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1
            },
            new Product
            {
                Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M
            },
            new Product
            {
                Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M
            }
    };

    [HttpGet]
    public IEnumerable<Product> GetAllProducts()
    {
        return products;
    }

    [HttpGet("{id}")]
    public ActionResult<Product> GetProduct(int id)
    {
        var product = products.FirstOrDefault((p) => p.Id == id);
        if (product == null)
        {
            return NotFound();
        }
        return product;
    }
}

Der oben hervorgehobene Code ändert Folgendes, um zu ASP.NET Core zu migrieren:

Er entfernt using-Anweisungen für die folgenden ASP.NET 4.x-Komponenten, die in ASP.NET Core nicht vorhanden sind:
- ApiController-Klasse
- System.Web.Http-Namespace
- IHttpActionResult-Schnittstelle
Er ändert die using ProductsApp.Models;-Anweisung in using ProductsCore.Models;.
Er legt den Stammnamespace auf ProductsCore fest.
Ändert ApiController in ControllerBase.
Er fügt using Microsoft.AspNetCore.Mvc; hinzu, um den ControllerBase-Verweis aufzulösen.
Er ändert den Rückgabetyp der GetProduct-Aktion von IHttpActionResult in ActionResult<Product>. Weitere Informationen finden Sie unter Rückgabetypen für Controlleraktionen in der ASP.NET Core-Web-API.
Er vereinfacht die return-Anweisung der GetProduct-Aktion wie folgt:
```
return product;
```
Er fügt die folgenden Attribute hinzu. Diese werden in den nächsten Abschnitten noch näher erläutert:
- [Route("api/[controller]")]
- [ApiController]
- [HttpGet]
- [HttpGet("{id}")]

Routing

ASP.NET Core bietet ein minimales Hostingmodell, bei dem die Endpunktrouting-Middleware die gesamte Middlewarepipeline umschließt. Daher können Routen direkt der Webanwendung (WebApplication) hinzugefügt werden, ohne explizit UseEndpoints oder UseRouting aufzurufen, um Routen zu registrieren.

UseRouting kann weiterhin verwendet werden, um anzugeben, wo der Routenabgleich erfolgt, UseRouting muss aber nicht explizit aufgerufen werden, wenn Routen am Anfang der Middlewarepipeline übereinstimmen sollen.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();

var app = builder.Build();

// Configure the HTTP request pipeline.

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Hinweis: Routen, die WebApplication direkt hinzugefügt werden, werden am Ende der Pipeline ausgeführt.

Routing im migrierten Controller `ProductsController`

Der migrierte Controller ProductsController enthält die folgenden hervorgehobenen Attribute:

using Microsoft.AspNetCore.Mvc;
using ProductsCore.Models;

namespace ProductsCore.Controllers;

[Route("api/[controller]")]
[ApiController]
public class ProductsController : ControllerBase
{
    Product[] products = new Product[]
    {
            new Product
            {
                Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1
            },
            new Product
            {
                Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M
            },
            new Product
            {
                Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M
            }
    };

    [HttpGet]
    public IEnumerable<Product> GetAllProducts()
    {
        return products;
    }

    [HttpGet("{id}")]
    public ActionResult<Product> GetProduct(int id)
    {
        var product = products.FirstOrDefault((p) => p.Id == id);
        if (product == null)
        {
            return NotFound();
        }
        return product;
    }
}

Das [Route]-Attribut konfiguriert das Attributroutingmuster des Controllers.
Das [ApiController]-Attribut legt fest, dass Attributrouting bei allen Aktionen in diesem Controller erforderlich ist.
Attributrouting unterstützt Token wie [controller] und [action]. Zur Laufzeit wird jedes Token durch den Namen des Controllers bzw. der Aktion ersetzt, auf den bzw. auf die das Attribut angewendet wurde. Für die Token gilt Folgendes:
- Sie sorgen dafür, dass weniger hartcodierte Zeichenfolgen für die Route verwendet werden müssen (oder gar keine).
- Sie stellen sicher, dass Routen mit den entsprechenden Controllern und Aktionen synchronisiert bleiben, wenn Umgestaltungen durch automatisches Umbenennen angewendet werden.
HTTP GET-Anforderungen werden für ProductController-Aktionen mit den folgenden Attributen aktiviert:
- [HttpGet]-Attribut, angewendet auf die GetAllProducts-Aktion
- [HttpGet("{id}")]-Attribut, angewendet auf die GetProduct-Aktion

Führen Sie das migrierte Projekt aus, und navigieren Sie zu /api/products. Beispiel: https://localhost:<port>/api/products. Eine vollständige Liste mit drei Produkten wird angezeigt. Navigieren Sie zu /api/products/1. Das erste Produkt wird angezeigt.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Zusätzliche Ressourcen

In diesem Artikel werden die Schritte veranschaulicht, die für die Migration der ASP.NET 4.x-Web-API zu ASP.NET Core MVC erforderlich sind.

Anzeigen oder Herunterladen von Beispielcode (Vorgehensweise zum Herunterladen)

Voraussetzungen

Visual Studio 2019 Version 16.4 oder höher mit der Workload ASP.NET und Webentwicklung.
.NET Core 3.1 SDK

Überprüfen des ASP.NET 4.x-Web-API-Projekts

In diesem Artikel wird das Projekt ProductsApp verwendet, das in Erste Schritte mit ASP.NET-Web-API 2 erstellt wurde. In diesem Projekt wird ein einfaches ASP.NET 4.x-Web-API-Projekt wie folgt konfiguriert:

In Global.asax.cs wird WebApiConfig.Register aufgerufen:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Routing;

namespace ProductsApp
{
    public class WebApiApplication : System.Web.HttpApplication
    {
        protected void Application_Start()
        {
            GlobalConfiguration.Configure(WebApiConfig.Register);
        }
    }
}

Die WebApiConfig-Klasse befindet sich im Ordner App_Start und verfügt über eine statische Register-Methode:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web.Http;

namespace ProductsApp
{
    public static class WebApiConfig
    {
        public static void Register(HttpConfiguration config)
        {
            // Web API configuration and services

            // Web API routes
            config.MapHttpAttributeRoutes();

            config.Routes.MapHttpRoute(
                name: "DefaultApi",
                routeTemplate: "api/{controller}/{id}",
                defaults: new { id = RouteParameter.Optional }
            );
        }
    }
}

Für die obige Klasse gilt Folgendes:

Sie konfiguriert das Attributrouting (auch wenn es eigentlich gar nicht verwendet wird).
Sie konfiguriert die Routingtabelle. Der Beispielcode erwartet, dass URLs dem Format /api/{controller}/{id} entsprechen, wobei {id} optional ist.

In den folgenden Abschnitten wird die Migration des Web-API-Projekts zu ASP.NET Core MVC veranschaulicht.

Erstellen des Zielprojekts

Erstellen Sie eine neue leere Projektmappe in Visual Studio, und fügen Sie das ASP.NET 4.x-Web-API-Projekt hinzu, das migriert werden soll:

Klicken Sie im Menü Datei auf Neu>Projekt.
Wählen Sie die Vorlage Leere Projektmappe und anschließend Weiter aus.
Nennen Sie die Projektmappe WebAPIMigration. Klicken Sie auf Erstellen.
Fügen Sie der Projektmappe das vorhandene Projekt ProductsApp hinzu.

Fügen Sie ein neues API-Projekt als Ziel für die Migration hinzu:

Fügen Sie der Projektmappe ein neues Projekt vom Typ ASP.NET Core-Webanwendung hinzu.
Geben Sie im Dialogfeld Neues Projekt konfigurieren dem Projekt den Namen ProductsCore, und wählen Sie Erstellen aus.
Vergewissern Sie sich, dass im Dialogfeld Neue ASP.NET Core-Webanwendung erstellen die Optionen .NET Core und ASP.NET Core 3.1 ausgewählt sind. Wählen Sie die Projektvorlage API aus, und klicken Sie auf Erstellen.
Entfernen Sie die Beispieldateien WeatherForecast.cs und Controllers/WeatherForecastController.cs aus dem neuen Projekt ProductsCore.

Die Projektmappe enthält nun zwei Projekte. In den folgenden Abschnitten wird die Migration der Inhalte des Projekts ProductsApp zum Projekt ProductsCore erläutert.

Migrating Configuration (Migrieren der Konfiguration)

ASP.NET Core verwendet nicht den Ordner App_Start oder die Datei Global.asax. Außerdem wird die Datei web.config zur Veröffentlichungszeit hinzugefügt.

Die Startup-Klasse:

Sie ersetzt Global.asax.
Behandelt alle App-Startaufgaben

Weitere Informationen finden Sie unter Anwendungsstart in ASP.NET Core.

Migrieren von Modellen und Controllern

Der folgende Code zeigt den Controller ProductsController, der für ASP.NET Core aktualisiert werden soll:

using ProductsApp.Models;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Web.Http;

namespace ProductsApp.Controllers
{
    public class ProductsController : ApiController
    {
        Product[] products = new Product[] 
        { 
            new Product
            {
                Id = 1, Name = "Tomato Soup", Category = "Groceries", Price = 1
            }, 
            new Product
            {
                Id = 2, Name = "Yo-yo", Category = "Toys", Price = 3.75M
            }, 
            new Product
            {
                Id = 3, Name = "Hammer", Category = "Hardware", Price = 16.99M
            } 
        };

        public IEnumerable<Product> GetAllProducts()
        {
            return products;
        }

        public IHttpActionResult GetProduct(int id)
        {
            var product = products.FirstOrDefault((p) => p.Id == id);
            if (product == null)
            {
                return NotFound();
            }
            return Ok(product);
        }
    }
}

Aktualisieren Sie den Controller ProductsController für ASP.NET Core:

Kopieren Sie Controllers/ProductsController.cs und den Ordner Models aus dem ursprünglichen Projekt in das neue Projekt.
Ändern Sie den Stammnamespace der kopierten Dateien in ProductsCore.
Ändern Sie die using ProductsApp.Models;-Anweisung in using ProductsCore.Models;.

Die folgenden Komponenten sind in ASP.NET Core nicht vorhanden:

ApiController-Klasse
System.Web.Http-Namespace
IHttpActionResult-Schnittstelle

Nehmen Sie die folgenden Änderungen vor:

Wechseln von ApiController zu ControllerBase. Fügen Sie using Microsoft.AspNetCore.Mvc; hinzu, um den ControllerBase-Verweis aufzulösen.
Löschen Sie using System.Web.Http;.
Ändern Sie den Rückgabetyp der GetProduct-Aktion von IHttpActionResult in ActionResult<Product>.
Vereinfachen Sie die return-Anweisung der GetProduct-Aktion wie folgt:
```
return product;
```

Konfigurieren des Routings

Die API-Projektvorlage von ASP.NET Core enthält die Endpunktroutingkonfiguration im generierten Code.

Die folgenden Aufrufe von UseRouting und UseEndpoints bewirken Folgendes:

Sie registrieren den Routenabgleich und die Endpunktausführung in der Middlewarepipeline.
Sie ersetzen die Datei App_Start/WebApiConfig.cs des Projekts ProductsApp.

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();

    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Konfigurieren Sie das Routing wie folgt:

Markieren Sie die ProductsController-Klasse mit den folgenden Attributen:
```
[Route("api/[controller]")]
[ApiController]
```
Das obige [Route]-Attribut konfiguriert das Attributroutingmuster des Controllers. Das [ApiController]-Attribut legt fest, dass Attributrouting bei allen Aktionen in diesem Controller erforderlich ist.

Attributrouting unterstützt Token wie [controller] und [action]. Zur Laufzeit wird jedes Token durch den Namen des Controllers bzw. der Aktion ersetzt, auf den bzw. auf die das Attribut angewendet wurde. Für die Token gilt Folgendes:
- Sie verringern die Anzahl von Magic-Befehlszeichenfolgen im Projekt.
- Sie stellen sicher, dass Routen mit den entsprechenden Controllern und Aktionen synchronisiert bleiben, wenn Umgestaltungen durch automatisches Umbenennen angewendet werden.
Aktivieren Sie HTTP GET-Anforderungen für die Aktionen vom Typ ProductsController:
- Wenden Sie das [HttpGet]-Attribut auf die GetAllProducts-Aktion an.
- Wenden Sie das [HttpGet("{id}")]-Attribut auf die GetProduct-Aktion an.

Führen Sie das migrierte Projekt aus, und navigieren Sie zu /api/products. Eine vollständige Liste mit drei Produkten wird angezeigt. Navigieren Sie zu /api/products/1. Das erste Produkt wird angezeigt.

Freigeben über

Migrieren von der ASP.NET-Web-API zu ASP.NET Core

Voraussetzungen

Erstellen des neuen ASP.NET Core-Web-API-Projekts

Entfernen der Vorlagendateien vom Typ WeatherForecast

Die Konfiguration für die ASP.NET Core-Web-API

Kopieren des Modells Product

Kopieren von ProductsController

Routing

Routing im migrierten Controller ProductsController

Zusätzliche Ressourcen

Voraussetzungen

Überprüfen des ASP.NET 4.x-Web-API-Projekts

Erstellen des Zielprojekts

Migrating Configuration (Migrieren der Konfiguration)

Migrieren von Modellen und Controllern

Konfigurieren des Routings

Zusätzliche Ressourcen

Zusätzliche Ressourcen

Routing im migrierten Controller `ProductsController`