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 da API Web 2 para o ASP.NET Core.

Prerequisites

Criar o novo projeto ASP.NET Core Web API

Remova os ficheiros de modelo WeatherForecast

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

A configuração para ASP.NET Core Web API

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

O ficheiro Program.cs

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

Para obter mais informações, consulte arranque da aplicação no ASP.NET Core.

A seguir mostra o código de inicialização do aplicativo no arquivo 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();

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 Nullable introduzido no C# 8, ASP.NET Core pode fornecer análise de fluxo de código adicional e segurança em tempo de compilação no processamento de tipos de referência. Por exemplo, protegendo contra exceções de referência null.

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

ASP.NET Core em projetos .NET 6 habilita tipos de referência anuláveis por defeito. Para obter mais informações, consulte 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 destacado anterior altera o seguinte, para migrar para ASP.NET Core:

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

  • ApiController classe
  • System.Web.Http espaço de nomes
  • IHttpActionResult Interface

• Altera a declaraçã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 mais informações, veja Tipos de retorno de ação do controlador.

• Simplifica a instrução GetProduct da ação return para a seguinte declaraçã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 oferece um modelo de hospedagem simplificado, no qual o middleware de roteamento de endpoints envolve todo o pipeline de middleware. Assim, as rotas podem ser adicionadas diretamente ao WebApplication sem a necessidade de uma chamada explícita para UseEndpoints ou UseRouting para registrar rotas.

UseRouting ainda pode ser usado para especificar onde a combinação de rotas ocorre, mas UseRouting não precisa ser explicitamente chamada se as rotas devem ser combinadas no início do pipeline de 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();

Nota: Rotas adicionadas diretamente ao WebApplication são executadas no final 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 atributos um requisito para todas as ações neste controlador.

• Roteamento de atributos suporta tokens, como [controller] e [action]. No tempo de execução, cada token é substituído pelo nome do controlador ou 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, ao aplicar refatorações automáticas de renomeação, as rotas permaneçam sincronizadas com os controladores e ações correspondentes.

• As solicitações HTTP Get são habilitadas para ações ProductController com os seguintes atributos:

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

Execute o projeto migrado e navegue até /api/products. Por exemplo: https://localhost:<port>/api/products. É apresentada uma lista completa de três produtos. Navegue até /api/products/1. Aparece o primeiro produto.

Visualizar ou descarregar amostra de código (como descarregar)

Recursos adicionais

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

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

Visualizar ou descarregar amostra de código (como descarregar)

Prerequisites

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

Revisão do projeto de API Web ASP.NET 4.x

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

Em Global.asax.cs, é feita uma chamada 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 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 roteamento de atributos, embora ele não esteja sendo usado na verdade.
• Configura a tabela de roteamento. O código de exemplo espera que as URLs correspondam ao formato /api/{controller}/{id}, com {id} sendo opcional.

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

Criar o projeto de destino

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

1. No menu Arquivo, selecione Novo>Projeto.
2. Selecione o modelo Solução em Branco e selecione Avançar.
3. Dê um nome à 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 ASP.NET Core Web Application à solução.
2. Na caixa de diálogo Configurar seu novo projeto, nomeie o projeto ProductsCoree selecione Criar.
3. Na caixa de diálogo Criar um novo aplicativo Web ASP.NET Core, certifique-se de que .NET Core e ASP.NET Core 3.1 estejam selecionados. Selecione o modelo de projeto de API e selecione Criar.
4. Remova os ficheiros 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 ou 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.

Para obter mais informações, consulte arranque da aplicação 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 Modelos do projeto original para o novo.
2. Altere o namespace raiz dos arquivos copiados para ProductsCore.
3. Atualize a instrução using ProductsApp.Models; para using ProductsCore.Models;.

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

• ApiController classe
• System.Web.Http espaço de nomes
• IHttpActionResult Interface

Faça as seguintes alterações:

1. Altere ApiController para ControllerBase. Adicione using Microsoft.AspNetCore.Mvc; para resolver a referência 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 declaração GetProduct da ação return para o seguinte:

   return product;
   

Configurar roteamento

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

As seguintes chamadas UseRouting e UseEndpoints:

• Registe a correspondência de rotas e a execução de pontos finais no pipeline de middleware .
• Substitua o ficheiro do projecto 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 atributos do controlador. O atributo [ApiController] torna o roteamento de atributos um requisito para todas as ações neste controlador.

   O roteamento de atributos suporta tokens, como [controller] e [action]. No tempo de execução, cada token é substituído pelo nome do controlador ou ação, respectivamente, ao qual o atributo foi aplicado. Os tokens:

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

2. Habilite solicitações HTTP Get para ações 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. É apresentada uma lista completa de três produtos. Navegue até /api/products/1. Aparece o primeiro produto.

Recursos adicionais

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