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.