Migrar da API Web ASP.NET para o ASP.NET Core

Este artigo mostra como migrar o controlador de produtos criado em Introdução ao ASP.NET Web API 2 para o ASP.NET Core.

Prerequisites

Criar o novo projeto de API Web do ASP.NET Core

Remover os arquivos de modelo WeatherForecast

1. Remova os arquivos de exemplo WeatherForecast.cs e Controllers/WeatherForecastController.cs do novo projeto ProductsCore .
2. Abra propriedades\launchSettings.jsativadas.
3. Altere as propriedades de launchUrl de weatherforcast para productscore.

A configuração da API Web do ASP.NET Core

ASP.NET Core não usa a pasta App_Start nem o arquivo Global.asax. O arquivo web.config é adicionado no momento da publicação. Para obter mais informações, consulte web.config arquivo.

O arquivo Program.cs:

• Substitui Global.asax.
• Lida com todas as tarefas de inicialização do aplicativo.

Saiba mais em Inicialização de aplicativos no ASP.NET Core.

O seguinte mostra o código de inicialização do aplicativo no arquivo Program.cs core do ASP.NET:

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

Copie o modelo Produto

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

O código realçado anterior altera o seguinte:

• A anotação ? foi adicionada para declarar as propriedades Name e Category como tipos de referência anuláveis.

Ao utilizar o recurso Anulável introduzido no C# 8, o ASP.NET Core pode proporcionar uma análise de fluxo de código mais aprofundada e garantir maior segurança em tempo de compilação no tratamento de tipos de referência. Por exemplo, a proteção contra exceções de referência null.

Nesse caso, a intenção é que o Name e Category possam ser tipos anuláveis.

ASP.NET Core em projetos do .NET 6 habilitam tipos de referência anuláveis por padrão. Para obter mais informações, confira Tipos de referência anuláveis.

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

O código realçado anterior altera o seguinte, para migrar para ASP.NET Core:

• Remova as instruções de uso para os seguintes componentes do ASP.NET 4.x que não existem no ASP.NET Core:

  • Classe ApiController
  • Namespace System.Web.Http
  • Interface IHttpActionResult

• Altera a instrução using ProductsApp.Models; para using ProductsCore.Models;.

• Define o namespace raiz como ProductsCore.

• Altera ApiController para ControllerBase.

• Adiciona using Microsoft.AspNetCore.Mvc; para resolver a referência ControllerBase.

• Altera o tipo de retorno da ação GetProduct de IHttpActionResult para ActionResult<Product>. Para obter mais informações, consulte Tipos de retorno da ação do controlador.

• Simplifica a instrução GetProduct da ação return para a seguinte instrução:

  return product;
  

• Adiciona os seguintes atributos que são explicados nas próximas seções:

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

Routing

O ASP.NET Core fornece um modelo de hospedagem mínimo no qual o middleware de roteamento de pontos de extremidade encapsula todo o pipeline de middleware, portanto, as rotas podem ser adicionadas diretamente ao WebApplication sem uma chamada explícita para UseEndpoints ou UseRouting para registrar rotas.

UseRouting ainda pode ser usado para especificar em que local ocorre a correspondência de rotas, mas UseRouting não precisa ser chamado explicitamente se as rotas devem ser correspondidas no início do pipeline do middleware.

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

Observação: as rotas adicionadas diretamente ao WebApplication são executadas no fim do pipeline.

Roteamento no ProductsController migrado

O ProductsController migrado contém os seguintes atributos realçados:

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

• O atributo [Route]configura o padrão de roteamento de atributos do controlador.

• O atributo [ApiController] torna o roteamento de atributo um requisito para todas as ações nesse controlador.

• O roteamento de atributos dá suporte a tokens, como [controller] e [action]. Em runtime, cada token é substituído pelo nome do controlador ou da ação, respectivamente, ao qual o atributo foi aplicado. Os tokens:

  • Reduz ou elimina a necessidade de usar cadeias de caracteres codificadas para a rota.
  • Certifique-se de que as rotas permaneçam sincronizadas com os controladores e ações correspondentes quando as refatorações de renomeação automática forem aplicadas.

• As solicitações http get estão habilitadas para ações de ProductController com os seguintes atributos:

  • Atributo [HttpGet] aplicado à ação GetAllProducts.
  • Atributo [HttpGet("{id}")] aplicado à ação GetProduct.

Execute o projeto migrado e navegue até /api/products. Por exemplo: https://localhost:<port>/api/products. Uma lista completa de três produtos é exibida. Navegue até /api/products/1. O primeiro produto aparece.

Exibir ou baixar código de exemplo (como baixar)

Recursos adicionais

• Criar APIs da Web com ASP.NET Core
• Tipos de retorno de ação do controlador na API Web do ASP.NET Core
• Versão de compatibilidade para ASP.NET Core MVC

Este artigo demonstra as etapas necessárias para migrar de ASP.NET API Web 4.x para ASP.NET Core MVC.

Exibir ou baixar código de exemplo (como baixar)

Prerequisites

• Visual Studio 2019 16.4 ou posterior com ASP.NET e carga de trabalho de desenvolvimento
• SDK do .NET Core 3.1.

Analisar o projeto de API Web ASP.NET 4.x

Este artigo usa o projeto ProductsApp criado no Introdução à API Web ASP.NET 2. Nesse projeto, um projeto básico de API Web ASP.NET 4.x é configurado da seguinte maneira.

Em Global.asax.cs, uma chamada é feita para 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);
        }
    }
}

A classe WebApiConfig é encontrada na pasta App_Start e tem um método de Register estático:

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

A classe anterior:

• Configura o roteamento do atributo, embora ele não esteja sendo usado de fato.
• Configura a tabela de roteamento. O código de exemplo espera que as URLs correspondam ao formato /api/{controller}/{id}, sendo {id} opcional.

As seções a seguir demonstram a migração do projeto de API Web para ASP.NET Core MVC.

Criar o projeto de destino

Crie uma nova solução em branco no Visual Studio e adicione o ASP.NET projeto de API Web 4.x para migrar:

1. No menu Arquivo, selecione Novo>Projeto.
2. Selecione o modelo Solução em Branco e selecione Avançar.
3. Nomeie a solução WebAPIMigration. Selecione Criar.
4. Adicione o projeto ProductsApp existente à solução.

Adicione um novo projeto de API para migrar para:

1. Adicione um novo projeto de aplicativo Web ASP.NET Core à solução.
2. Na caixa de diálogo Configure seu novo projeto, nomeie o projeto ProductsCore e selecione Criar.
3. Na caixa de diálogo Criar um novo aplicativo Web ASP.NET Core, confirme se .NET Core e ASP.NET Core 3.1 estão selecionados. Selecione o modelo de projeto de API e selecione Criar.
4. Remova os arquivos de exemplo WeatherForecast.cs e Controllers/WeatherForecastController.cs do novo projeto ProductsCore .

A solução agora contém dois projetos. As seções a seguir explicam a migração do conteúdo do projeto ProductsApp para o projeto ProductsCore.

Migrar configuração

ASP.NET Core não usa a pasta App_Start nem o arquivo Global.asax. Além disso, o arquivo web.config é adicionado no momento da publicação.

A classe Startup:

• Substitui Global.asax.
• Lida com todas as tarefas de inicialização do aplicativo.

Saiba mais em Inicialização de aplicativos no ASP.NET Core.

Migrar modelos e controladores

O código a seguir mostra o ProductsController a ser atualizado para 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);
        }
    }
}

Atualize o ProductsController para ASP.NET Core:

1. Copie Controllers/ProductsController.cs e a pasta Models do projeto original para o novo.
2. Altere o namespace raiz dos arquivos copiados para ProductsCore.
3. Atualize a declaração using ProductsApp.Models; para using ProductsCore.Models;.

Os seguintes componentes não existem no ASP.NET Core:

• Classe ApiController
• Namespace System.Web.Http
• Interface IHttpActionResult

Faça as seguintes alterações:

1. Altere ApiController para ControllerBase. Adicione using Microsoft.AspNetCore.Mvc; para resolver a referência de ControllerBase.

2. Excluir using System.Web.Http;.

3. Altere o tipo de retorno da ação GetProduct de IHttpActionResult para ActionResult<Product>.

4. Simplifique a instrução GetProduct da ação return para o seguinte:

   return product;
   

Configurar o roteamento

O modelo de projeto de API ASP.NET Core inclui a configuração de roteamento de pontos de extremidade no código gerado.

As seguintes chamadas UseRouting e UseEndpoints:

• Registre a correspondência de rota e a execução do ponto de extremidade no pipeline middleware.
• Substitua o arquivo do projeto App_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();
    });
}

Configure o roteamento da seguinte maneira:

1. Marque a classe ProductsController com os seguintes atributos:

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

   O atributo [Route] anterior configura o padrão de roteamento de atributo do controlador. O atributo [ApiController] torna o roteamento de atributo um requisito para todas as ações nesse controlador.

   O roteamento de atributo dá suporte a tokens, como [controller] e [action]. Em runtime, cada token é substituído pelo nome do controlador ou da ação, respectivamente, ao qual o atributo foi aplicado. Os tokens:

   • Reduza o número de cadeias de caracteres mágicas no projeto.
   • Certifique-se de que as rotas permaneçam sincronizadas com os controladores e ações correspondentes quando as refatorações de renomeação automática forem aplicadas.

2. Habilite solicitações HTTP GET para as ações do ProductsController:

   • Aplique o atributo [HttpGet] à ação GetAllProducts.
   • Aplique o atributo [HttpGet("{id}")] à ação GetProduct.

Execute o projeto migrado e navegue até /api/products. Uma lista completa de três produtos é exibida. Navegue até /api/products/1. O primeiro produto aparece.

Recursos adicionais

• Criar APIs da Web com ASP.NET Core
• Tipos de retorno de ação do controlador na API Web do ASP.NET Core
• Versão de compatibilidade para ASP.NET Core MVC