ASP.NET Core 8 Web API a Docker: Začiatočnícky sprievodca vytvorením jednoduchej ToDo aplikácie

Predpoklady

Skôr než začneme, uistite sa, že máte v systéme nainštalovaný nasledujúci softvér. Tieto nástroje sú nevyhnutné na vývoj a spustenie aplikácie, ktorú si postavíme:

• .NET Core 8.0 SDK: Vývojársky balík, ktorý vám umožní vytvárať aplikácie v ASP.NET Core 8. Stiahnete ho z .NET oficiálnej stránky.
• Docker: Platforma na vývoj, distribúciu a spúšťanie aplikácií v kontajneroch. Docker stiahnete z oficiálnej stránky.
• Visual Studio Code: Ľahký, ale výkonný editor zdrojového kódu pre desktop. Stiahnete ho z oficiálnej stránky Visual Studio Code.
• Zdrojový kód: Zdrojový kód k tomuto návodu nájdete na GitHube. Verzia s databázou PostgreSQL z nadväzujúceho článku sa nachádza v samostatnom priečinku.

Vytvorenie nového ASP.NET projektu

Začneme vytvorením nového projektu ASP.NET Core Web API pomocou .NET CLI. Otvorte si terminál (alebo príkazový riadok) a spustite tento príkaz:

dotnet new webapi --use-controllers -o aspnet-core-8-todo-list-api

Tento príkaz vytvorí nový Web API projekt v priečinku aspnet-core-8-todo-list-api. Na spustenie projektu najprv prejdite do priečinka pomocou cd a potom spustite dotnet run:

cd aspnet-core-8-todo-list-api
dotnet run

Po spustení vyššie uvedených príkazov sa nové Web API naštartuje. Na začiatku projekt obsahuje ukážkový endpoint s predpoveďou počasia, ktorý neskôr upravíme na potreby našej ToDo aplikácie.

Kým aplikácia beží, môžete s API pracovať cez Swagger UI. Je to webové rozhranie, ktoré umožňuje prezerať a testovať API bez písania ďalšieho kódu. Otvorte si prehliadač a prejdite na https://localhost:5277/swagger/index.html.

Port 5277 sa môže líšiť podľa konfigurácie vášho projektu. Ak uvedená adresa nefunguje, pozrite si výstup v konzole pri štarte aplikácie – býva tam uvedený správny port. Overiť ho môžete aj v súbore launchSettings.json v priečinku Properties.

Vytvorenie modelovej triedy

Modely v ASP.NET Core aplikácii reprezentujú dáta, s ktorými aplikácia pracuje. Zvyčajne ide o triedy s vlastnosťami (properties), ktoré zodpovedajú dátam, ktoré aplikácia ukladá a načítava. Pre našu ToDo aplikáciu si vytvoríme model reprezentujúci jednu todo položku.

Najskôr si v projekte vytvorte nový priečinok s názvom Models. Ten nám pomôže udržať modelové triedy prehľadne pokope.

V priečinku Models vytvorte nový súbor ToDo.cs. Táto trieda bude definovať vlastnosti todo položky. Môže vyzerať napríklad takto:

public class ToDo
{
  public long Id { get; set; } = 1; // Unique identifier for the todo item
  public string Name { get; set; } = "Default ToDo Name"; // Descriptive name of the todo item
  public bool IsDone { get; set; } = false; // Status indicating whether the todo is completed
}

Predvolené hodnoty v triede sa hodia pri testovaní a prvých spusteniach aplikácie. Zabezpečia, že sa objekty modelu nevytvoria s null alebo neplatnými hodnotami, čo môže pomôcť predísť chybám počas vývoja.

Takéto rozdelenie modelov vám pomôže udržať architektúru čistú a udržiavateľnú a zároveň budete mať základné dátové štruktúry ľahko dostupné a jednoducho upraviteľné, keď sa projekt bude časom rozširovať.

Vytvorenie Data Transfer Objects (DTO)

DTO (Data Transfer Objects) zohrávajú dôležitú úlohu pri práci s dátami a návrhu API, pretože zapuzdrujú dáta prenášané medzi jednotlivými vrstvami aplikácie. Používanie DTO namiesto priamych doménových modelov v requestoch a responseoch pomáha zachovať separáciu zodpovedností a zabezpečí, že interné zmeny modelu neovplyvnia priamo klientov.

V našej ToDo aplikácii použijeme DTO na definovanie dátovej štruktúry pre vytváranie a aktualizáciu todo položiek. Tento prístup nám umožní prispôsobiť dáta, ktoré posielame a prijímame, a prípadne vynechať alebo doplniť vlastnosti bez toho, aby sme menili databázovú schému.

Začnite vytvorením nového priečinka DTOs. V ňom budeme mať všetky DTO triedy, čo pomôže udržať projekt prehľadný.

V priečinku DTOs/ToDo vytvorte dve triedy: AddToDoDto.cs a UpdateToDoDto.cs, ktoré budú slúžiť na vytváranie a aktualizáciu todo položiek.

Trieda AddToDoDto sa používa pri pridávaní novej todo položky cez API. Obsahuje potrebné vlastnosti, ktoré môže klient nastaviť pri vytváraní novej položky.

public class AddToDoDto
{
  public string Name { get; set; } = "Default ToDo Name"; // Initial default name for a new todo item
}

Trieda UpdateToDoDto sa používa na aktualizáciu existujúcich todo položiek. Je podobná AddToDoDto, no v budúcnosti môže obsahovať ďalšie vlastnosti podľa toho, čo bude potrebné pri update.

public class UpdateToDoDto
{
  public string Name { get; set; } = "Default ToDo Name"; // Default name to be updated if necessary
  public bool IsDone { get; set; } = false; // Status to be updated
}

Používanie DTO týmto spôsobom pomáha nielen riadiť tok dát v aplikácii, ale aj chráni API pred možnými over-posting zraniteľnosťami, keď by klient mohol omylom alebo zámerne nastaviť vlastnosti, ktoré by sa meniť nemali. Vďaka tomu zostane aplikácia robustná, bezpečná a jednoduchšia na údržbu.

Vytvorenie služby

Služby (services) v ASP.NET Core aplikácii sú kľúčové pre implementáciu biznis logiky. Oddeľujú operácie od controllerov, vďaka čomu je aplikácia čistejšia a ľahšie sa udržiava. Pre našu ToDo aplikáciu vytvoríme službu, ktorá bude spravovať todo položky pomocou in-memory zoznamu. Je to jednoduché a vhodné na ukážku, no v produkcii sa zvyčajne nahrádza databázou.

Začneme definovaním rozhrania (interface) pre todo službu. Rozhranie deklaruje operácie, ktoré musí služba implementovať. Vytvorte súbor IToDoService.cs v priečinku Services/ToDoService:

public interface IToDoService
{
  ToDo AddToDo(AddToDoDto addToDo);
  ToDo? GetToDo(long id);
  List<ToDo> GetToDos();
  void DeleteToDo(long id);
  void UpdateToDo(long id, UpdateToDoDto updateToDo);
}

Následne rozhranie implementujte v triede ToDoService.cs v tom istom priečinku. Táto trieda bude obsahovať samotnú logiku správy todo položiek:

public class ToDoService : IToDoService
{
  private List<ToDo> _toDos; // Store ToDos in memory

  public ToDoService()
  {
    // Initialize the list with a dummy ToDo 
    _toDos = new List<ToDo>
    {
        new ToDo { Id = 1, Name = "Do the dishes", IsDone = false }
    };
  }

  public ToDo AddToDo(AddToDoDto addToDo)
  {
    long newId = 0;
    if (_toDos.Count > 0)
    {
      newId = _toDos.Max(toDo => toDo.Id) + 1;
    }

    var newToDo = new ToDo
    {
      Id = newId,
      Name = addToDo.Name,
      IsDone = false
    };

    _toDos.Add(newToDo);

    return newToDo;
  }

  public ToDo GetToDo(long id)
  {
    return _toDos.FirstOrDefault(toDo => toDo.Id == id);
  }

  public List<ToDo> GetToDos()
  {
    return _toDos;
  }

  public void DeleteToDo(long id)
  {
    var toDo = GetToDo(id);
    if (toDo != null)
    {
      _toDos.Remove(toDo);
    }
  }

  public void UpdateToDo(long id, UpdateToDoDto updatedToDo)
  {
    var existingToDo = GetToDo(id);
    if (existingToDo != )
    {
      existingToDo.Name = updatedToDo.Name;
      existingToDo.IsDone = updatedToDo.IsDone;
    }
  }
}

Takto štruktúrovaná služba udrží biznis logiku oddelenú od ostatných častí (napr. prezentácie dát a routovania API). Vďaka tomu sa služba ľahšie testuje a udržiava.

Vytvorenie controlleru

Controller v ASP.NET Core spracováva prichádzajúce HTTP requesty a vracia response. Je to kľúčová súčasť architektúry MVC (Model-View-Controller). V tomto návode vytvoríme controller, ktorý bude spravovať todo položky pomocou služby, ktorú sme si pripravili vyššie.

V projekte si vytvorte priečinok Controllers (ak ešte neexistuje). V ňom pridajte nový súbor TodoController.cs. Controller bude obsahovať všetky potrebné akcie na prácu s todo položkami.

Controller by mal použiť konštruktorovú injekciu (constructor injection), aby získal prístup k službe IToDoService, ktorá obsahuje logiku správy todo položiek. Definícia controlleru môže vyzerať takto:

[ApiController]
[Route("api/[controller]")]
public class ToDosController : ControllerBase
{
  private readonly IToDoService _toDoService;
  private readonly ILogger<ToDosController> _logger;

  public ToDosController(IToDoService toDoService, ILogger<ToDosController> logger)
  {
    _toDoService = toDoService; // Constructor injection to manage toDo
    _logger = logger; // Constructor injection to manage logging
  }

  // Get all ToDos
  [HttpGet]
  public ActionResult<IEnumerable<ToDo>> GetToDos()
  {
    _logger.LogInformation("API: GetToDos called");
    return _toDoService.GetToDos();
  }

  // Get a ToDo by id
  [HttpGet("{id}")]
  public ActionResult<ToDo> GetToDo(long id)
  {
    _logger.LogInformation($"API: GetToDo called with id {id}");

    var toDo = _toDoService.GetToDo(id);

    if (toDo == null)
    {
      return NotFound();
    }

    return toDo;
  }

  // Add a new ToDo
  [HttpPost]
  public ActionResult<ToDo> AddToDo(AddToDoDto addToDo)
  {
    _logger.LogInformation($"API: AddToDo called with ToDo Name {addToDo.Name}");

    var toDo = _toDoService.AddToDo(addToDo);

    return CreatedAtAction(nameof(GetToDo), new { id = toDo.Id }, toDo);
  }

  // Delete a ToDo by id
  []
  
  {
    _logger.LogInformation();

     toDo = _toDoService.GetToDo(id);

     (toDo == )
    {
       NotFound();
    }

    _toDoService.DeleteToDo(id);

     NoContent();
  }

  
  []
  
  {
    _logger.LogInformation();

     existingToDo = _toDoService.GetToDo(id);

     (existingToDo == )
    {
       NotFound();
    }

    _toDoService.UpdateToDo(id, updateToDo);

     NoContent();
  }
}

Pred spustením aplikácie sa uistite, že je todo služba zaregistrovaná v Startup.cs. Táto registrácia umožní dependency injection, ktoré ASP.NET Core používa na správu služieb:

builder.Services.AddSingleton<IToDoService, ToDoService>(); // Register our custom service with the lifetime of the application

Keďže budeme mať klientsku aplikáciu bežiacu na inej doméne, potrebujeme v Startup.cs povoliť CORS (Cross-Origin Resource Sharing). To umožní klientovi volať API z inej domény:

// Allow any origin, method, and header
app.UseCors(builder =>
{
  builder.AllowAnyOrigin()
         .AllowAnyMethod()
         .AllowAnyHeader();
});

Táto konfigurácia zabezpečí, že controller bude nielen funkčný, ale zároveň bude držať krok s best practices moderného vývoja API, takže riešenie bude škálovateľné a udržiavateľné.

Spustenie aplikácie

Teraz, keď máme ASP.NET Core Web API nastavené, je čas vyskúšať ho v praxi. Spustenie aplikácie je jednoduché a je to rýchly spôsob, ako overiť, že všetko funguje podľa očakávania.

Otvorte si terminál, prejdite do koreňového priečinka projektu (kde sa nachádza .csproj súbor) a spustite tento príkaz:

dotnet run

Keď aplikácia beží, môžete s ňou pracovať cez Swagger UI. Swagger poskytuje webové rozhranie na testovanie API endpointov bez potreby ďalších nástrojov (napr. Postman). Otvorte si prehliadač a prejdite na http://localhost:5277/swagger/index.html.

V Swagger UI uvidíte zoznam všetkých API endpointov definovaných v controllery. Každý endpoint si môžete rozbaliť a zobraziť parametre requestu. Funkcia „Try it out“ vám umožní posielať requesty priamo z prehliadača. Otestujte jednotlivé endpointy, zadajte potrebné parametre a skontrolujte odpovede. Tento krok je dôležitý, aby ste mali istotu, že API sa správa správne.

Zabalenie aplikácie do Dockeru

Docker je výkonný nástroj na balenie aplikácií a ich závislostí do kontajnerov, ktoré sa dajú spustiť na ľubovoľnom systéme s nainštalovaným Dockerom. Kontajnerizáciou zabezpečíte konzistentné správanie naprieč prostrediami, čo zjednodušuje nasadzovanie aj správu.

Keď aplikáciu dôkladne otestujete a potvrdíte, že funguje, ďalším krokom je pripraviť ju na nasadenie pomocou Dockeru. Tento proces zahŕňa vytvorenie Docker image, ktorý obsahuje aplikáciu aj jej runtime prostredie.

Začnite vytvorením súboru Dockerfile v koreňovom priečinku projektu. Dockerfile obsahuje inštrukcie na zostavenie Docker image. Pridajte doň tento obsah:

# Use SDK image for the build stage
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build-env
WORKDIR /App

# Copy everything
COPY . ./
# Restore as distinct layers
RUN dotnet restore
# Build and publish a release
RUN dotnet publish -c Release -o out

# Build runtime image
FROM mcr.microsoft.com/dotnet/aspnet:8.0
# ENV ASPNETCORE_HTTP_PORTS=5277
# ENV ASPNETCORE_URLS=http://*:5277
WORKDIR /App
COPY --from=build-env /App/out .

# Expose the port the app runs on
EXPOSE 5277
ENV ASPNETCORE_URLS=http://*:5277

ENTRYPOINT ["dotnet", "aspnet-core-8-todo-list-api.dll"]

Otvorte terminál, prejdite do priečinka so súborom Dockerfile a vytvorte image týmto príkazom:

docker build -t aspnet-core-8-todo-list-api .

Tento príkaz priradí image názov (tag), aby sa naň dalo neskôr jednoducho odkazovať.

Po zostavení image ho môžete spustiť ako kontajner. Kontajner naštartujete týmto príkazom:

docker run --rm -it -p 5277:5277 -e ASPNETCORE_ENVIRONMENT=Development aspnet-core-8-todo-list-api

Tento príkaz zabezpečí, že sa kontajner po zastavení odstráni (--rm) a namapuje port 5277 z vášho lokálneho počítača do kontajnera, takže sa k aplikácii dostanete rovnako, ako keby bežala lokálne.

Vaša aplikácia teraz beží v Docker kontajneri a v prehliadači je dostupná na http://localhost:5277/swagger/index.html.

Záver

V tomto návode ste si prešli kroky potrebné na vytvorenie plne funkčného Web API postaveného na controlleroch v ASP.NET Core 8. Nastavili ste si vývojové prostredie, definovali dátový model a DTO, implementovali biznis logiku pomocou služieb a riadili tok dát cez controllery. Okrem toho ste si vyskúšali spustenie aplikácie lokálne a zabalenie do Docker kontajnera pre jednoduchšie nasadenie.

Ak vám tento návod pomohol, pokojne ho zdieľajte s ďalšími, ktorým by sa mohol hodiť. A ako vždy – ak máte otázky, pripomienky alebo návrhy na zlepšenie, dajte vedieť!