Migrer de l’API Web ASP.NET vers ASP.NET Core

Cet article explique comment migrer le contrôleur Produits créé dans Prise en main de l’API Web ASP.NET 2 vers ASP.NET Core.

Prérequis

Créer le nouveau projet d’API web ASP.NET Core

Supprimer les fichiers de modèle WeatherForecast

1. Supprimez les fichiers d’exemple WeatherForecast.cs et Controllers/WeatherForecastController.cs du nouveau projet ProductsCore.
2. Ouvrez Properties\launchSettings.json.
3. Faites passer launchUrl propriétés de weatherforcast à productscore.

Configuration de l’API web ASP.NET Core API

ASP.NET Core n’utilise pas le dossier App_Start ou le fichier Global.asax. Le fichier web.config est ajouté au moment de la publication. Pour plus d’informations, consultez web.config file.

Le fichier Program.cs :

• Remplace Global.asax.
• Gère toutes les tâches de démarrage de l’application.

Pour plus d’informations, consultez Start-up de l’application dans ASP.NET Core.

Voici le code de démarrage de l’application dans le fichier ASP.NET Core 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();

Copier le modèle de produit

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; }
    }
}

Le code en surbrillance précédent modifie les éléments suivants :

• L’annotation ? a été ajoutée pour déclarer les propriétés Name et Category en tant que types références pouvant accepter la valeur Null.

L’utilisation de la fonctionnalité pouvant accepter la valeur Null présentée dans C# 8 permet à ASP.NET Core de fournir une analyse de flux de code et une sécurité au moment de la compilation supplémentaires, lors de la gestion des types références. Par exemple, la protection contre les exceptions de référence null.

Dans ce cas, l’intention est que et le Name et Category puissent être des types Nullables.

Les projets ASP.NET Core 6.0 activent les types de référence nullables par défaut. Pour plus d’informations, consultez Types référence pouvant accepter la valeur Null.

Copier le ProductsController

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;
    }
}

Le code mis en surbrillance précédent modifie ce qui suit pour migrer vers ASP.NET Core :

• Supprime les instructions d’utilisation pour les composants 4.x ASP.NET suivants qui n’existent pas dans ASP.NET Core :

  • Classe ApiController
  • Espace de noms System.Web.Http
  • Interface IHttpActionResult

• Fais passer l’instruction using ProductsApp.Models; à using ProductsCore.Models;.

• Définit l’espace de noms racine comme ProductsCore.

• Remplace ApiController par ControllerBase.

• Ajoute using Microsoft.AspNetCore.Mvc; pour résoudre la référence ControllerBase.

• Faites passer le type de retour d’action GetProduct de IHttpActionResult à ActionResult<Product>. Pour plus d’informations, consultez Types de retour d’action de contrôleur.

• Simplifie l’instruction return de l’action GetProduct en l’instruction suivante :

  return product;
  

• Ajoute les attributs suivants qui sont expliqués dans les sections suivantes :

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

Routage

ASP.NET Core fournit un modèle d’hébergement minimal dans lequel l’intergiciel de routage du point de terminaison encapsule l’ensemble du pipeline d’intergiciel. Par conséquent, les itinéraires peuvent être ajoutés directement au WebApplication sans appel explicite à UseEndpoints ou UseRouting pour inscrire des itinéraires.

UseRouting peut toujours être utilisé pour spécifier où la correspondance de route se produit, mais UseRouting n'a pas besoin d'être explicitement appelée si les routes doivent être mises en correspondance au début du pipeline d’intergiciel.

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();

Remarque : Itinéraires ajoutés directement à l’ WebApplication exécution à la fin du pipeline.

Routage dans le migré ProductsController

Le migré ProductsController contient les attributs suivants mis en évidence :

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;
    }
}

• L’ attribut [Route]configure le modèle de routage des attributs du contrôleur.

• L’attribut [ApiController] rend le routage d’attribut obligatoire pour toutes les actions de ce contrôleur.

• Le routage d’attributs prend en charge les jetons, tels que [controller] et [action]. Au moment de l’exécution, chaque jeton est remplacé par le nom du contrôleur ou de l’action, respectivement, auquel l’attribut a été appliqué. Les jetons :

  • Réduit ou élimine la nécessité d’utiliser des chaînes codées en dur pour l’itinéraire.
  • Vérifiez que les itinéraires restent synchronisés avec les contrôleurs et les actions correspondants lorsque des refactorisations de renommage automatiques sont appliquées.

• Les requêtes HTTP Get sont activées pour ProductController actions avec les attributs suivants :

  • L’attribut [HttpGet] appliqué à l’action GetAllProducts.
  • L’attribut [HttpGet("{id}")] appliqué à l’action GetProduct.

Exécutez le projet migré, puis accédez à /api/products. Par exemple : https://localhost:<port>/api/produits. Une liste complète de trois produits s’affiche. Accédez à /api/products/1. Le premier produit s’affiche.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Ressources supplémentaires

• Créer des API web avec ASP.NET Core
• Types de retour des actions des contrôleurs dans l’API web ASP.NET Core
• Version de compatibilité pour ASP.NET Core MVC

Cet article décrit les étapes requises pour migrer de l’API web ASP.NET 4.x vers le MVC ASP.NET Core.

Affichez ou téléchargez l’exemple de code (procédure de téléchargement)

Prérequis

• Visual Studio 2019 version 16.4 ou ultérieure avec la charge de travail Développement ASP.NET et web
• Kit SDK .NET Core 3.1

Évaluez le projet d’API Web ASP.NET 4.x

Cet article utilise le projet ProductsApp créé dans Prise en main de l’API Web ASP.NET 2. Dans ce projet, un projet d’API web ASP.NET 4.x de base est configuré comme suit.

Dans Global.asax.cs, un appel est effectué à WebApiConfig.Register :

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);
        }
    }
}

La classe WebApiConfig se trouve dans le dossier App_Start et a une méthode statique Register :

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 }
            );
        }
    }
}

La classe précédente :

• Configure le routage d’attributs, bien qu’il ne soit pas réellement utilisé.
• Configure la table de routage. L’exemple de code s’attend à ce que les URL correspondent au format /api/{controller}/{id}, avec {id} une valeur facultative.

Les sections suivantes illustrent la migration du projet d’API web vers le MVC ASP.NET Core.

Créer le projet de destination

Créez une solution vide dans Visual Studio et ajoutez le projet d’API web ASP.NET 4.x pour migrer :

1. Dans le menu Fichier, sélectionnez Nouveau>Projet.
2. Sélectionnez le modèle Solution vide, puis sélectionnez Suivant.
3. Nommez la solution WebAPIMigration. Sélectionnez Create (Créer).
4. Ajoutez le projet ProductsApp existant à la solution.

Ajoutez un nouveau projet d’API vers laquelle effectuer la migration :

1. Ajoutez un nouveau projet d’application web ASP.NET Core à la solution.
2. Dans la boîte de dialogue Configurer votre nouveau projet, nommez le projet ProductsCore, puis sélectionnez Créer.
3. Dans la boîte de dialogue Créer une application web ASP.NET Core, vérifiez que .NET Core et ASP.NET Core 3.1 sont sélectionnés. Sélectionnez le modèle de projet API, puis sélectionnez Créer.
4. Supprimez les fichiers d’exemple WeatherForecast.cs et Controllers/WeatherForecastController.cs du nouveau projet ProductsCore.

La solution contient maintenant deux projets. Les sections suivantes expliquent la migration du contenu du projet ProductsApp vers le projet ProductsCore.

Migrer une configuration

ASP.NET Core n’utilise pas le dossier App_Start ou le fichier Global.asax. De plus, le fichier web.config est ajouté au moment de la publication.

La classe Startup :

• Remplace Global.asax.
• Gère toutes les tâches de démarrage de l’application.

Pour plus d’informations, consultez Start-up de l’application dans ASP.NET Core.

Migrer des modèles et des contrôleurs

Le code suivant montre le ProductsController à mettre à jour pour ASP.NET Core :

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);
        }
    }
}

Mettez à jour pour ProductsController ASP.NET Core :

1. Copiez Controllers/ProductsController.cs et le dossier Modèles du projet d’origine vers le nouveau.
2. Remplacez l’espace de noms racine des fichiers copiés par ProductsCore.
3. Mettez à jour l’instruction using ProductsApp.Models; vers using ProductsCore.Models;.

Les composants suivants n’existent pas dans ASP.NET Core :

• Classe ApiController
• Espace de noms System.Web.Http
• Interface IHttpActionResult

Apportez les changements suivants :

1. Remplacez ApiController par ControllerBase. Ajoutez using Microsoft.AspNetCore.Mvc; pour résoudre la référence ControllerBase.

2. Supprimez using System.Web.Http;.

3. Faites passer le type de retour d’action GetProduct de IHttpActionResult à ActionResult<Product>.

4. Simplifiez l’instruction GetProduct de l’action return comme suit :

   return product;
   

Configurer le routage

Le modèle de projet d’API ASP.NET Core inclut la configuration du routage des points de terminaison dans le code généré.

Les appels suivants UseRouting et UseEndpoints :

• Inscrivez la correspondance de route et l’exécution du point de terminaison dans le pipeline d’intergiciel.
• Remplacez le fichier du projet ProductsAppApp_Start/WebApiConfig.cs.

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

    app.UseHttpsRedirection();

    app.UseRouting();

    app.UseAuthorization();

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

Configurez le routage comme suit :

1. Marquez la classe ProductsController avec les attributs suivants :

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

   L’ attribut [Route] précédent configure le modèle de routage des attributs du contrôleur. L’attribut [ApiController] rend le routage d’attribut obligatoire pour toutes les actions de ce contrôleur.

   Le routage d’attributs prend en charge les jetons, tels que [controller] et [action]. Au moment de l’exécution, chaque jeton est remplacé par le nom du contrôleur ou de l’action, respectivement, auquel l’attribut a été appliqué. Les jetons :

   • Réduisez le nombre de chaînes magiques dans le projet.
   • Vérifiez que les itinéraires restent synchronisés avec les contrôleurs et les actions correspondants lorsque des refactorisations de renommage automatiques sont appliquées.

2. Activez les requêtes HTTP Get pour les actions ProductsController :

   • Appliquez l’attribut [HttpGet] à l’action GetAllProducts.
   • Appliquez l’attribut [HttpGet("{id}")] à l’action GetProduct.

Exécutez le projet migré, puis accédez à /api/products. Une liste complète de trois produits s’affiche. Accédez à /api/products/1. Le premier produit s’affiche.

Ressources supplémentaires

• Créer des API web avec ASP.NET Core
• Types de retour des actions des contrôleurs dans l’API web ASP.NET Core
• Version de compatibilité pour ASP.NET Core MVC