Jak stworzyć prostą aplikację w .NET Core

Wraz z rozwojem oprogramowania typu open source i pojawianiem się coraz bardziej zaawansowanych technologii, Microsoft z każdym rokiem coraz chętniej angażuje się w inicjatywy open source’owe. Jedną z nich jest .NET Core.

Ten framework umożliwia deweloperom i organizacjom wspierającym technologię Microsoft rozpoczęcie migracji do modelu open source, a tym, którzy mają doświadczenie głównie w technologiach open source, na rozpoczęcie pracy z narzędziami i frameworkami Microsoft.

To otwiera nowe możliwości migracji starszych systemów do nowoczesnej architektury. Łączy je ze sobą, mimo iż nie są łatwo integrowalne oraz tworzy nowe oprogramowanie z zespołami przeszkolonymi w zakresie różnych narzędzi i metod z całej branży .

W tym artykule przyjrzymy się, jak zbudować proste API REST z podstawową implementacją CRUD-a, dla mocków, które mają nazwę i opis.

Kopia kodu źródłowego użytego w tym artykule jest dostępna na GitHubie.

Konfiguracja projektu

Jeśli nie masz jeszcze .NET, pobierz kopię dla swojego systemu operacyjnego tutaj.

Ten projekt został zainicjowany poleceniem dotnet new webapi -o ItemsAPI, które tworzy podstawy boilerplate aplikacji .NET Core w folderze ItemsAPI. Plik konfiguracyjny projektu dla tej aplikacji jest tworzony w ItemsAPI.csproj:

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.App" />
    <PackageReference Include="Microsoft.AspNetCore.Razor.Design" Version="2.2.0" PrivateAssets="All" />
  </ItemGroup>

</Project>

Ten plik określa szczegóły konfiguracji dla samego projektu, takie jak wersja .NET frameworka i pakiety wymagane do aplikacji. Ten projekt nie używa żadnych dodatkowych pakietów, ale jeśli zostałyby dodane, trafiłyby do <ItemGroup> jako kolejny wpis <PackageReference>.

Punkt wejścia aplikacji

Plik, który definiuje punkt wejścia dla naszej aplikacji, to Program.cs:

using Microsoft.AspNetCore;
using Microsoft.AspNetCore.Hosting;

namespace ItemsAPI
{
    public class Program
    {
        public static void Main(string[] args)
        {
            CreateWebHostBuilder(args).Build().Run();
        }

        public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
            WebHost.CreateDefaultBuilder(args)
                .UseStartup<Startup>();
    }
}

Gdy ta apka zostanie uruchomiona komendą dotnet run, wywoływana jest metoda Main, a następnie wywoływana jest funkcja CreateWebHostBuilder, tworząc tworząc builder za pomocą klasy Startup (która zawiera konfigurację uruchamiania aplikacji).

Konfiguracja Startup

Następnym krokiem jest wspomniana powyżej klasa Startup w Startup.cs:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;

namespace ItemsAPI
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices(IServiceCollection services)
        {
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }

            app.UseHttpsRedirection();
            app.UseMvc();
        }
    }
}

W tej klasie zdefiniowana jest następująca konfiguracja uruchamiania:

• usługi, w metodzie ConfigureServices
• pipeline żądań HTTP, w metodzie Configure

W Configure jest również sprawdzane to, czy aplikacja działa obecnie w trybie developerskim. Jest to oczywiście miejsce, w którym uruchamiane byłyby procedury konfiguracyjne specyficzne dla środowiska dev, test, prod lub jakiegokolwiek innego.

Klasa ItemsController

Następny jest plik kontrolera Controllers / ItemsController.cs:

using System.Collections.Generic;
using System.Linq;
using Microsoft.AspNetCore.Mvc;

namespace ItemsAPI.Controllers
{
    [Route("api/[controller]")]
    [ApiController]
    public class ItemsController : ControllerBase
    {
        static private List<Item> items = new List<Item>();

        // GET api/values
        [HttpGet]
        public ActionResult<List<Item>> Get()
        {
            return items;
        }

        // GET api/values/5
        [HttpGet("{index}")]
        public ActionResult<Item> Get(int index)
        {
            return items[index];
        }

        // GET api/values/5
        [HttpGet("/range/{a}/to/{b}")]
        public ActionResult<List<Item>> Get(int a, int b)
        {
            return items.GetRange(a, b - a);
        }

        // POST api/values
        [HttpPost]
        public int Post([FromBody] Item item)
        {
            ItemsController.items.Add(item);
            int index = ItemsController.items.Count() - 1;
            return index;
        }

        // PUT api/values/5
        [HttpPut("{index}")]
        public void Put(int id, [FromBody] Item item)
        {
            ItemsController.items[id] = item;
        }

        // DELETE api/values/5
        [HttpDelete("{index}")]
        public void Delete(int index)
        {
            ItemsController.items.RemoveAt(index);
        }
    }
}

Klasa ItemsController ma atrybuty Route i ApiController, które konfigurują ten kontroler do użycia w interfejsie API na zdefiniowanej ścieżce.

Właściwość items to List<Item>, która zawiera listę elementów i służy jako magazyn danych dla tej aplikacji. W praktyce można zastosować dowolne odpowiednie rozwiązanie do przechowywania lub przesyłania wiadomości w dowolnym celu, ale jest to dobry przykład uproszczenia projektu. Zaimplementowanie takiego mocka zajmuje tylko kilka sekund i ma tę zaletę, że jest statyczne, wewnętrzne iłatwe do przywrócenia do stanu początkowego (po prostu restartując serwer). To wszystko pomaga zrobić szybki koncept, ponieważ jest mniej rzeczy, które mogą się nie udać.

W ramach tej klasy znajduje się także kilka metod Get() zdefiniowanych dodatkowo do Post(), Put() i Delete(), które stanowią podstawowy zestaw operacji CRUD. Każda z nich jest poprzedzona dekoratorem, takim jak [HttpGet] itd., co wskazuje frameworkowi, jaka metoda HTTP (opcjonalnie) ma zostać zaimplementowana oprócz ścieżki, gdzie będą obsługiwane żądania.

Następujące metody HTTP są implementowane przez te przykładowe API:

• [HttpGet] 
• [HttpGet("{index}")]
• [HttpGet("/range/{a}/to/{b}")]
• [HttpPost]
• [HttpPut("{index}")]
• [HttpDelete("{index}")]

Zastosowana tutaj klasa Item określa, których właściwości powinien oczekiwać każdy endpoint, zarówno z przychodzących danych w JSON-ie, jak i z tymczasowego zbioru danych (lista elementów). Pozwala to frameworkowi na odrzucanie niepoprawnie sformułowanych żądań, a także pomaga w developmencie poprzez zapewnienie kontroli błędów edycji i czasu kompilacji a dodatkowo pozwala na podpowiedzi uzupełniania kodu i daje kilka innych korzyści.

Teraz przyjrzyjmy się klasie Item.

Klasa Item

Oto klasa Item zdefiniowana w Models/Items.cs:

namespace ItemsAPI {

    public class Item
    {
        public string name { get; set; }
        public string description { get; set; }
    }
}

Ten plik jest dość zrozumiały. Definiuje nazwę i opis właściwości w celu utworzenia standardowej struktury danych dla elementu. W tym przypadku dla każdej właściwości zdefiniowane są domyślne metody dostępowe get i set. Można je zdefiniować bardziej szczegółowo, aby zapewnić większy stopień kontroli i sprawdzania poprawności danych.

Testowanie

Aby uruchomić serwer, wywołaj polecenie $ ./api-start.sh w terminalu (lub uruchom z poziomu kodu VS). Następnie otwórz nową sesję terminala i uruchom następujące polecenia, aby wykonać odpowiednie czynności:

$ ./api-add-item.sh "Item Name" "Some item description text"

Skrypt ./api-add-item.sh wysyła do API żądanie HTTP POST, przekazując dane w JSON-ie, w obiekcie żądania, pasującym do struktury obiektu Item. Ten dodaje nowy element do listy i zwraca indeks elementu.

$ ./api-list-items.sh

Ten skrypt wysyła HTTP GET do API, który po prostu zwraca listę wcześniej dodanych elementów w postaci serializowanego JSON-a.

Podsumowanie

W tym artykule wytłumaczyłem, jak łatwo jest przejść do programowania z .NET Core, które zapewnia  mnóstwo przydatnych funkcji zarówno w samym języku C#, jak również w ramach .NET i repozytorium pakietów NuGet, które umożliwiają programistom szybkie wykorzystanie i pozwalają na ich podstawie rozbudowywać swoją aplikację, na bazie wiedzy wielkiej społeczności programistów.

Ta przykładowa aplikacja API jest dostępna jako projekt open source na GitHub i może być wykorzystywana do tworzenia nowych projektów wystawiających API (powtórzenie, ale serwerów API brzmi lipnie), które będą służyły dowolnym celom.

Dziękuję za przeczytanie i powodzenia w kolejnym projekcie .NET Core!


Oryginał tekstu w języku angielskim przeczytasz tutaj.