daohualiuxiang
/
AspNetCore.Docs
mirror of https://github.com/dotnet/AspNetCore.Docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
AspNetCore.Docs/aspnetcore/migration/webapi.md

14 KiB
Raw Permalink Blame History

title author description ms.author ms.custom ms.date uid
Migrate from ASP.NET Web API to ASP.NET Core ardalis Learn how to migrate a web API implementation from ASP.NET 4.x Web API to ASP.NET Core MVC. wpickett mvc 01/31/2022 migration/webapi

Migrate from ASP.NET Web API to ASP.NET Core

ASP.NET Core combines ASP.NET 4.x's MVC and Web API app models into a single programming model known as ASP.NET Core MVC.

:::moniker range=">= aspnetcore-6.0" This article shows how to migrate the Products controller created in Getting Started with ASP.NET Web API 2 to ASP.NET Core.

Prerequisites

Visual Studio

[!INCLUDE]

Visual Studio Code

[!INCLUDE]

Create the new ASP.NET Core Web API project

Visual Studio

  1. From the File menu, select New > Project.
  2. Enter Web API in the search box.
  3. Select the ASP.NET Core Web API template and select Next.
  4. In the Configure your new project dialog, name the project ProductsCore and select Next.
  5. In the Additional information dialog:
    1. Confirm the Framework is .NET 6.0 (Long-term support).
    2. Confirm the checkbox for Use controllers(uncheck to use minimal APIs) is checked.
    3. Uncheck Enable OpenAPI support.
    4. Select Create.

Visual Studio Code

  1. Open the integrated terminal.

  2. Change directories (cd) to the folder that will contain the project folder.

  3. Run the following commands to create a new web API project and open it in Visual Studio Code:

    dotnet new webapi -o ProductsCore --no-openapi
cd ProductsCore
code -r ../ProductsCore

Remove the WeatherForecast template files

  1. Remove the WeatherForecast.cs and Controllers/WeatherForecastController.cs example files from the new ProductsCore project.
  2. Open Properties\launchSettings.json.
  3. Change launchUrl properties from weatherforcast to productscore.

The configuration for ASP.NET Core Web API

ASP.NET Core doesn't use the App_Start folder or the Global.asax file. The web.config file is added at publish time. For more information, see xref:host-and-deploy/iis/web-config.

The Program.cs file:

  • Replaces Global.asax.
  • Handles all app startup tasks.

For more information, see xref:fundamentals/startup.

The following shows the application startup code in the ASP.NET Core Program.cs file:

[!code-csharp]

Copy the Product model

Visual Studio

  1. In Solution Explorer, right-click the project. Select Add > New Folder. Name the folder Models.
  2. Right-click the Models folder. Select Add > Class. Name the class Product and select Add.
  3. Replace the template model code with the following:

Visual Studio Code

  1. Add a folder named Models.
  2. Add a Product class to the Models folder with the following code:

[!code-csharp]

The preceding highlighted code changes the following:

  • The ? annotation has been added to declare the Name and Category properties as nullable reference types.

By utilizing the Nullable feature introduced in C# 8, ASP.NET Core can provide additional code flow analysis and compile-time safety in the handling of reference types. For example, protecting against null reference exceptions.

In this case, the intent is that the Name and Category can be nullable types.

ASP.NET Core 6.0 projects enable nullable reference types by default. For more information, see Nullable reference types.

Copy the ProductsController

Visual Studio

  1. Right-click the Controllers folder.
  2. Select Add > Controller....
  3. In Add New Scaffolded Item dialog, select Mvc Controller - Empty then select Add.
  4. Name the controller ProductsController and select Add.
  5. Replace the template controller code with the following:

Visual Studio Code

  1. Add a ProductsController class to the Controllers folder with the following code:

[!code-csharp]

The preceding highlighted code changes the following, to migrate to ASP.NET Core:

  • Removes using statements for the following ASP.NET 4.x components that don't exist in ASP.NET Core:

    • ApiController class
    • System.Web.Http namespace
    • IHttpActionResult interface

  • Changes the using ProductsApp.Models; statement to using ProductsCore.Models;.

  • Sets the root namespace to ProductsCore.

  • Changes ApiController to xref:Microsoft.AspNetCore.Mvc.ControllerBase.

  • Adds using Microsoft.AspNetCore.Mvc; to resolve the ControllerBase reference.

  • Changes the GetProduct action's return type from IHttpActionResult to ActionResult<Product>. For more info, see Controller action return types.

  • Simplifies the GetProduct action's return statement to the following statement:

    return product;

  • Adds the following attributes which are explained in the next sections:

    • [Route("api/[controller]")]
    • [ApiController]
    • [HttpGet]
    • [HttpGet("{id}")]

Routing

ASP.NET Core provides a minimal hosting model in which the endpoint routing middleware wraps the entire middleware pipeline, therefore routes can be added directly to the xref:Microsoft.AspNetCore.Builder.WebApplication without an explicit call to xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseEndpoints%2A or xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseRouting%2A to register routes.

UseRouting can still be used to specify where route matching happens, but UseRouting doesn't need to be explicitly called if routes should be matched at the beginning of the middleware pipeline.

[!code-csharp]

Note: Routes added directly to the xref:Microsoft.AspNetCore.Builder.WebApplication execute at the end of the pipeline.

Routing in the migrated ProductsController

The migrated ProductsController contains the following highlighted attributes:

[!code-csharp]

  • The [Route] attribute configures the controller's attribute routing pattern.

  • The [ApiController] attribute makes attribute routing a requirement for all actions in this controller.

  • Attribute routing supports tokens, such as [controller] and [action]. At runtime, each token is replaced with the name of the controller or action, respectively, to which the attribute has been applied. The tokens:

    • Reduces or eliminates the need to use hard coded strings for the route.
    • Ensure routes remain synchronized with the corresponding controllers and actions when automatic rename refactorings are applied.

  • HTTP Get requests are enabled for ProductController actions with the following attributes:

    • [HttpGet] attribute applied to the GetAllProducts action.
    • [HttpGet("{id}")] attribute applied to the GetProduct action.

Run the migrated project, and browse to /api/products. For example: https://localhost:<port>/api/products. A full list of three products appears. Browse to /api/products/1. The first product appears.

View or download sample code (how to download)

Additional resources

:::moniker-end

:::moniker range="< aspnetcore-6.0" This article demonstrates the steps required to migrate from ASP.NET 4.x Web API to ASP.NET Core MVC.

View or download sample code (how to download)

Prerequisites

[!INCLUDE prerequisites]

Review ASP.NET 4.x Web API project

This article uses the ProductsApp project created in Getting Started with ASP.NET Web API 2. In that project, a basic ASP.NET 4.x Web API project is configured as follows.

In Global.asax.cs, a call is made to WebApiConfig.Register:

[!code-csharp]

The WebApiConfig class is found in the App_Start folder and has a static Register method:

[!code-csharp]

The preceding class:

  • Configures attribute routing, although it's not actually being used.
  • Configures the routing table. The sample code expects URLs to match the format /api/{controller}/{id}, with {id} being optional.

The following sections demonstrate migration of the Web API project to ASP.NET Core MVC.

Create the destination project

Create a new blank solution in Visual Studio and add the ASP.NET 4.x Web API project to migrate:

  1. From the File menu, select New > Project.
  2. Select the Blank Solution template and select Next.
  3. Name the solution WebAPIMigration. Select Create.
  4. Add the existing ProductsApp project to the solution.

Add a new API project to migrate to:

  1. Add a new ASP.NET Core Web Application project to the solution.
  2. In the Configure your new project dialog, Name the project ProductsCore, and select Create.
  3. In the Create a new ASP.NET Core Web Application dialog, confirm that .NET Core and ASP.NET Core 3.1 are selected. Select the API project template, and select Create.
  4. Remove the WeatherForecast.cs and Controllers/WeatherForecastController.cs example files from the new ProductsCore project.

The solution now contains two projects. The following sections explain migrating the ProductsApp project's contents to the ProductsCore project.

Migrate configuration

ASP.NET Core doesn't use the App_Start folder or the Global.asax file. Additionally, the web.config file is added at publish time.

The Startup class:

  • Replaces Global.asax.
  • Handles all app startup tasks.

For more information, see xref:fundamentals/startup.

Migrate models and controllers

The following code shows the ProductsController to be updated for ASP.NET Core:

[!code-csharp]

Update the ProductsController for ASP.NET Core:

  1. Copy Controllers/ProductsController.cs and the Models folder from the original project to the new one.
  2. Change the copied files' root namespace to ProductsCore.
  3. Update the using ProductsApp.Models; statement to using ProductsCore.Models;.

The following components don't exist in ASP.NET Core:

  • ApiController class
  • System.Web.Http namespace
  • IHttpActionResult interface

Make the following changes:

  1. Change ApiController to xref:Microsoft.AspNetCore.Mvc.ControllerBase. Add using Microsoft.AspNetCore.Mvc; to resolve the ControllerBase reference.

  2. Delete using System.Web.Http;.

  3. Change the GetProduct action's return type from IHttpActionResult to ActionResult<Product>.

  4. Simplify the GetProduct action's return statement to the following:

    return product;

Configure routing

The ASP.NET Core API project template includes endpoint routing configuration in the generated code.

The following xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseRouting%2A and xref:Microsoft.AspNetCore.Builder.EndpointRoutingApplicationBuilderExtensions.UseEndpoints%2A calls:

  • Register route matching and endpoint execution in the middleware pipeline.
  • Replace the ProductsApp project's App_Start/WebApiConfig.cs file.

[!code-csharp]

Configure routing as follows:

  1. Mark the ProductsController class with the following attributes:

    [Route("api/[controller]")]
[ApiController]

    The preceding [Route] attribute configures the controller's attribute routing pattern. The [ApiController] attribute makes attribute routing a requirement for all actions in this controller.

    Attribute routing supports tokens, such as [controller] and [action]. At runtime, each token is replaced with the name of the controller or action, respectively, to which the attribute has been applied. The tokens:

    • Reduce the number of magic strings in the project.
    • Ensure routes remain synchronized with the corresponding controllers and actions when automatic rename refactorings are applied.

  2. Enable HTTP Get requests to the ProductsController actions:

    • Apply the [HttpGet] attribute to the GetAllProducts action.
    • Apply the [HttpGet("{id}")] attribute to the GetProduct action.

Run the migrated project, and browse to /api/products. A full list of three products appears. Browse to /api/products/1. The first product appears.

Additional resources