Udostępnij za pośrednictwem

Migrowanie z internetowego interfejsu API ASP.NET do ASP.NET Core

  • Artykuł

ASP.NET Core łączy modele MVC i aplikacji interfejsu API sieci Web ASP.NET 4.x w jeden model programowania znany jako ASP.NET Core MVC.

W tym artykule pokazano, jak przeprowadzić migrację kontrolera Products utworzonego w temacie Getting Started with ASP.NET Web API 2 (Wprowadzenie do internetowego interfejsu API 2 ) do ASP.NET Core.

Wymagania wstępne

Tworzenie nowego projektu internetowego interfejsu API platformy ASP.NET Core

  1. W menu Plik wybierz pozycję Nowy>projekt.
  2. Wprowadź internetowy interfejs API w polu wyszukiwania.
  3. Wybierz szablon internetowego interfejsu API platformy ASP.NET Core i wybierz pozycję Dalej.
  4. W oknie dialogowym Konfigurowanie nowego projektu nadaj projektowi nazwę ProductsCore i wybierz pozycję Dalej.
  5. W oknie dialogowym Dodatkowe informacje:
    1. Upewnij się, że platforma .NET 6.0 (obsługa długoterminowa).
    2. Upewnij się, że pole wyboru Użyj kontrolerów (usuń zaznaczenie pola wyboru, aby używać minimalnych interfejsów API) jest zaznaczone.
    3. Usuń zaznaczenie pola wyboru Włącz obsługę interfejsu OpenAPI.
    4. Wybierz pozycję Utwórz.

Usuwanie plików szablonów WeatherForecast

  1. WeatherForecast.cs Usuń pliki i Controllers/WeatherForecastController.cs z nowego projektu ProductsCore.
  2. Otwórz plik Properties\launch Ustawienia.json.
  3. Zmień launchUrl właściwości z weatherforcast na productscore.

Konfiguracja internetowego interfejsu API platformy ASP.NET Core

ASP.NET Core nie używa folderu App_Start ani pliku Global.asax . Plik web.config jest dodawany w czasie publikowania. Aby uzyskać więcej informacji, zobacz plik web.config.

Plik Program.cs:

  • Zastępuje plik Global.asax.
  • Obsługuje wszystkie zadania uruchamiania aplikacji.

Aby uzyskać więcej informacji, zobacz Uruchamianie aplikacji na platformie ASP.NET Core.

Poniżej przedstawiono kod uruchamiania aplikacji w pliku 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();

Kopiowanie modelu produktu

  1. W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt. Wybierz pozycję Dodaj>nowy folder. Nadaj folderowi nazwę Models.
  2. Kliknij prawym przyciskiem myszy folder Models . Wybierz pozycję Dodaj>klasę. Nadaj klasie nazwę Product i wybierz pozycję Dodaj.
  3. Zastąp kod modelu szablonu następującym kodem:
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; }
    }
}

Powyższy wyróżniony kod zmienia następujące zmiany:

  • Adnotacja ? została dodana w celu zadeklarowania Name właściwości i Category jako typów odwołań dopuszczanych do wartości null.

Korzystając z funkcji dopuszczającej wartość null wprowadzoną w języku C# 8, ASP.NET Core może zapewnić dodatkową analizę przepływu kodu i bezpieczeństwo czasu kompilacji w obsłudze typów odwołań. Na przykład ochrona przed wyjątkami referencyjnymi null .

W tym przypadku intencją jest to, że Name typy i Category mogą być typy dopuszczające wartość null.

projekty ASP.NET Core 6.0 domyślnie umożliwiają korzystanie z typów odwołań dopuszczanych do wartości null. Aby uzyskać więcej informacji, zobacz Typy referencyjne dopuszczane do wartości null.

Kopiowanie elementu ProductsController

  1. Kliknij prawym przyciskiem myszy folder Controllers .
  2. Wybierz pozycję Dodaj > kontroler....
  3. W oknie dialogowym Dodawanie nowego elementu szkieletu wybierz pozycję Kontroler mvc — pusty , a następnie wybierz pozycję Dodaj.
  4. Nadaj kontrolerowi nazwę ProductsController i wybierz pozycję Dodaj.
  5. Zastąp kod kontrolera szablonu następującym kodem:
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;
    }
}

Poprzedni wyróżniony kod zmienia następujący kod, aby przeprowadzić migrację do ASP.NET Core:

  • Usuwa instrukcje using dla następujących składników ASP.NET 4.x, które nie istnieją w ASP.NET Core:

    • Klasa ApiController
    • System.Web.Http Obszaru nazw
    • IHttpActionResult Interfejs

  • Zmienia instrukcję using ProductsApp.Models; na using ProductsCore.Models;.

  • Ustawia przestrzeń nazw katalogu głównego na ProductsCore.

  • Zmiany ApiController w pliku ControllerBase.

  • Dodaje using Microsoft.AspNetCore.Mvc; element , aby rozwiązać problem z odwołaniem ControllerBase .

  • GetProduct Zmienia typ zwracany akcji z IHttpActionResult na ActionResult<Product>. Aby uzyskać więcej informacji, zobacz Zwracane typy akcji kontrolera.

  • Upraszcza instrukcję GetProduct akcji return w następującej instrukcji:

    return product;

  • Dodaje następujące atrybuty, które zostały wyjaśnione w następnych sekcjach:

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

Routing

ASP.NET Core zapewnia minimalny model hostingu, w którym oprogramowanie pośredniczące routingu punktu końcowego opakowuje cały potok oprogramowania pośredniczącego, dlatego trasy można dodać bezpośrednio do WebApplication bez jawnego wywołania UseEndpoints lub UseRouting zarejestrowania tras.

UseRouting Można nadal używać do określania, gdzie odbywa się dopasowywanie tras, ale UseRouting nie musi być jawnie wywoływane, jeśli trasy powinny być dopasowane na początku potoku oprogramowania pośredniczącego.

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

Uwaga: trasy dodane bezpośrednio do WebApplication wykonania na końcu potoku.

Routing w zmigrowanym ProductsController

Migrowany ProductsController plik zawiera następujące wyróżnione atrybuty:

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

  • Atrybut [Route] konfiguruje wzorzec routingu atrybutów kontrolera.

  • Atrybut [ApiController] sprawia, że routing atrybutów jest wymagany dla wszystkich akcji w tym kontrolerze.

  • Routing atrybutów obsługuje tokeny, takie jak [controller] i [action]. W czasie wykonywania każdy token jest zastępowany odpowiednio nazwą kontrolera lub akcji, do której zastosowano atrybut. Tokeny:

    • Zmniejsza lub eliminuje konieczność używania ciągów zakodowanych w kodzie dla trasy.
    • Upewnij się, że trasy pozostają zsynchronizowane z odpowiednimi kontrolerami i akcjami po zastosowaniu automatycznej refaktoryzacji zmiany nazwy.

  • Żądania HTTP Get są włączone dla ProductController akcji z następującymi atrybutami:

    • [HttpGet] atrybut zastosowany do GetAllProducts akcji.
    • [HttpGet("{id}")] atrybut zastosowany do GetProduct akcji.

Uruchom zmigrowany projekt i przejdź do /api/productsadresu . Na przykład: https://localhost:<port>/api/products. Zostanie wyświetlona pełna lista trzech produktów. Przejdź do /api/products/1. Zostanie wyświetlony pierwszy produkt.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Dodatkowe zasoby

W tym artykule przedstawiono kroki wymagane do migracji z internetowego interfejsu API ASP.NET 4.x do ASP.NET Core MVC.

Wyświetl lub pobierz przykładowy kod (jak pobrać)

Wymagania wstępne

Zapoznaj się z projektem internetowego interfejsu API ASP.NET 4.x

W tym artykule użyto projektu ProductsApp utworzonego w artykule Wprowadzenie do ASP.NET internetowego interfejsu API 2. W tym projekcie skonfigurowano podstawowy projekt internetowego interfejsu API ASP.NET 4.x w następujący sposób.

W Global.asax.cssystemie jest wykonywane wywołanie metody :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);
        }
    }
}

Klasa WebApiConfig znajduje się w folderze App_Start i ma metodę statyczną 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 }
            );
        }
    }
}

Poprzednia klasa:

  • Konfiguruje routing atrybutów, chociaż nie jest on rzeczywiście używany.
  • Konfiguruje tabelę routingu. Przykładowy kod oczekuje, że adresy URL będą zgodne z formatem /api/{controller}/{id}, z {id} opcjonalnym.

W poniższych sekcjach przedstawiono migrację projektu internetowego interfejsu API do ASP.NET Core MVC.

Tworzenie projektu docelowego

Utwórz nowe puste rozwiązanie w programie Visual Studio i dodaj projekt internetowego interfejsu API ASP.NET 4.x, aby przeprowadzić migrację:

  1. W menu Plik wybierz pozycję Nowy>projekt.
  2. Wybierz szablon Puste rozwiązanie i wybierz pozycję Dalej.
  3. Nadaj rozwiązaniu nazwę WebAPIMigration. Wybierz pozycję Utwórz.
  4. Dodaj istniejący projekt ProductsApp do rozwiązania.

Dodaj nowy projekt interfejsu API, aby przeprowadzić migrację do:

  1. Dodaj nowy projekt aplikacji internetowej ASP.NET Core do rozwiązania.
  2. W oknie dialogowym Konfigurowanie nowego projektu Nadaj projektowi nazwę ProductsCore i wybierz pozycję Utwórz.
  3. W oknie dialogowym Tworzenie nowej aplikacji internetowej platformy ASP.NET Core upewnij się, że wybrano pozycję .NET Core i ASP.NET Core 3.1. Wybierz szablon projektu interfejsu API , a następnie wybierz pozycję Utwórz.
  4. WeatherForecast.cs Usuń pliki i Controllers/WeatherForecastController.cs z nowego projektu ProductsCore.

Rozwiązanie zawiera teraz dwa projekty. W poniższych sekcjach opisano migrację zawartości projektu ProductsApp do projektu ProductsCore .

Migrowanie konfiguracji

ASP.NET Core nie używa folderu App_Start ani pliku Global.asax . Ponadto plik web.config jest dodawany w czasie publikowania.

Klasa Startup:

  • Zastępuje plik Global.asax.
  • Obsługuje wszystkie zadania uruchamiania aplikacji.

Aby uzyskać więcej informacji, zobacz Uruchamianie aplikacji na platformie ASP.NET Core.

Migrowanie modeli i kontrolerów

Poniższy kod pokazuje, że ProductsController element ma zostać zaktualizowany dla 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);
        }
    }
}

Zaktualizuj element ProductsController dla ASP.NET Core:

  1. Skopiuj Controllers/ProductsController.cs folder Models z oryginalnego projektu do nowego.
  2. Zmień przestrzeń nazw katalogu głównego skopiowanych plików na ProductsCore.
  3. Zaktualizuj instrukcję using ProductsApp.Models; na using ProductsCore.Models;.

Następujące składniki nie istnieją w ASP.NET Core:

  • Klasa ApiController
  • System.Web.Http Obszaru nazw
  • IHttpActionResult Interfejs

Wprowadź następujące zmiany:

  1. Zmień ApiController na ControllerBase. Dodaj using Microsoft.AspNetCore.Mvc; , aby rozwiązać problem z odwołaniem ControllerBase .

  2. Usuń folder using System.Web.Http;.

  3. GetProduct Zmień typ zwracany akcji z IHttpActionResult na ActionResult<Product>.

  4. Uprość instrukcję GetProductreturn akcji na następujące:

    return product;

Configure routing (Konfigurowanie routingu)

Szablon projektu ASP.NET Core API zawiera konfigurację routingu punktów końcowych w wygenerowany kod.

Następujące UseRouting wywołania i UseEndpoints :

  • Zarejestruj dopasowywanie tras i wykonywanie punktu końcowego w potoku oprogramowania pośredniczącego.
  • Zastąp plik projektu App_Start/WebApiConfig.cs ProductsApp.
public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();

    app.UseAuthorization();

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

Skonfiguruj routing w następujący sposób:

  1. Oznacz klasę ProductsController następującymi atrybutami:

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

    [Route] Powyższy atrybut konfiguruje wzorzec routingu atrybutów kontrolera. Atrybut [ApiController] sprawia, że routing atrybutów jest wymagany dla wszystkich akcji w tym kontrolerze.

    Routing atrybutów obsługuje tokeny, takie jak [controller] i [action]. W czasie wykonywania każdy token jest zastępowany odpowiednio nazwą kontrolera lub akcji, do której zastosowano atrybut. Tokeny:

    • Zmniejsz liczbę ciągów magicznych w projekcie.
    • Upewnij się, że trasy pozostają zsynchronizowane z odpowiednimi kontrolerami i akcjami po zastosowaniu automatycznej refaktoryzacji zmiany nazwy.

  2. Włącz żądania HTTP Get do ProductsController akcji:

    • [HttpGet] Zastosuj atrybut do GetAllProducts akcji.
    • [HttpGet("{id}")] Zastosuj atrybut do GetProduct akcji.

Uruchom zmigrowany projekt i przejdź do /api/productsadresu . Zostanie wyświetlona pełna lista trzech produktów. Przejdź do /api/products/1. Zostanie wyświetlony pierwszy produkt.

Dodatkowe zasoby