C# / .NET Kompendium PLEN
.NET / C# / Web API, Blazor

Routing/Model Binding w Web API, SignalR w Blazor Server, PWA, Render Modes

Model Binding w Web API - skąd biorą się wartości parametrów

Model binding to mechanizm, który automatycznie wypełnia parametry akcji kontrolera danymi z requestu HTTP - z URL-a, query stringa, body, nagłówków. ASP.NET Core ma domyślne konwencje, ale atrybuty pozwalają to jawnie kontrolować.

[FromRoute] - z segmentu URL

[HttpGet("{id}")] // api/orders/5
public async Task<ActionResult<OrderDto>> GetOrder([FromRoute] int id)
{
    // id = 5, wzięte z segmentu URL
}

// [FromRoute] często pomijalny - EF automatycznie dopasuje {id} do parametru "id"
[HttpGet("{id}")]
public async Task<ActionResult<OrderDto>> GetOrder(int id) // działa identycznie

[FromQuery] - z query stringa

// GET api/orders/search?status=Pending&minAmount=100
[HttpGet("search")]
public async Task<ActionResult<List<OrderDto>>> Search(
    [FromQuery] string status,
    [FromQuery] decimal? minAmount)
{
    // status = "Pending", minAmount = 100
}

// Można też zbindować cały obiekt naraz
public class OrderSearchParams
{
    public string Status { get; set; }
    public decimal? MinAmount { get; set; }
    public int Page { get; set; } = 1;
}

[HttpGet("search")]
public async Task<ActionResult<List<OrderDto>>> Search([FromQuery] OrderSearchParams searchParams)
{
    // GET api/orders/search?status=Pending&minAmount=100&page=2
    // ASP.NET Core automatycznie mapuje query params na property obiektu
}

[FromBody] - z ciała requestu (JSON)

[HttpPost]
public async Task<ActionResult<OrderDto>> CreateOrder([FromBody] CreateOrderRequest request)
{
    // request zdeserializowany z JSON w body POST-a
}

// [FromBody] JEST wymagany dla złożonych typów w POST/PUT - bez niego
// framework domyślnie próbowałby czytać z query string dla prostych typów,
// ale dla złożonego obiektu i tak domyślnie szuka w body (w [ApiController])

Ważna zasada: w metodzie może być tylko jeden parametr [FromBody] - body requestu to jeden strumień, nie da się go "podzielić" na dwa osobne obiekty.

[FromHeader] - z nagłówka HTTP

[HttpGet]
public async Task<ActionResult> GetData([FromHeader(Name = "X-Correlation-Id")] string correlationId)
{
    // wartość nagłówka X-Correlation-Id
}

[FromServices] - wstrzyknięcie zależności bezpośrednio do metody (Method Injection z poprzedniej rozmowy!)

[HttpPost]
public async Task<ActionResult> CreateOrder(
    CreateOrderRequest request,
    [FromServices] IEmailService emailService) // wstrzyknięte TYLKO dla tej metody, nie w konstruktorze
{
    await emailService.SendAsync(...);
}

To jest dokładnie Method Injection, o którym mówiłem przy sposobach wdrażania DI - przydatne, gdy zależność jest potrzebna tylko w jednej konkretnej akcji kontrolera, a nie chcesz jej trzymać jako pole całej klasy.

Domyślne konwencje (gdy nie ma atrybutu) w [ApiController]

Typ parametru Domyślne źródło
Prosty typ (int, string, Guid) niebędący w route Query string
Złożony obiekt (klasa) Body (JSON)
Parametr pasujący nazwą do {segment} w route Route

To dlatego int id w GetOrder(int id) przy [HttpGet("{id}")] działa bez jawnego [FromRoute] - nazwa parametru dopasowuje się do placeholdera w route.

Walidacja modelu - automatyczna dzięki [ApiController]

public class CreateOrderRequest
{
    [Required]
    [StringLength(100)]
    public string CustomerName { get; set; }

    [Range(0.01, double.MaxValue)]
    public decimal TotalAmount { get; set; }
}

[HttpPost]
public async Task<ActionResult> CreateOrder(CreateOrderRequest request)
{
    // [ApiController] SAM sprawdza ModelState.IsValid PRZED wejściem do tej metody
    // jeśli walidacja nie przejdzie - automatyczny 400 Bad Request, ten kod się nawet nie wykona
    var order = await _orderService.CreateOrderAsync(request);
    return Ok(order);
}

Bez [ApiController] musiałbyś ręcznie sprawdzać if (!ModelState.IsValid) return BadRequest(ModelState); w każdej akcji.

Czy [FromBody] jest wymagane?

Krótka odpowiedź: Nie, jeśli kontroler ma atrybut [ApiController]

[ApiController] automatycznie wnioskuje [FromBody] dla złożonych typów, więc w praktyce w Web API prawie nigdy nie musisz go pisać jawnie.

Demonstracja - działa identycznie z i bez atrybutu

[ApiController] // ← to jest kluczowe
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    // Z jawnym [FromBody]
    [HttpPost]
    public async Task<ActionResult<OrderDto>> CreateOrder([FromBody] CreateOrderRequest request)
    {
        // ...
    }

    // BEZ [FromBody] - działa DOKŁADNIE tak samo dzięki [ApiController]
    [HttpPost]
    public async Task<ActionResult<OrderDto>> CreateOrder(CreateOrderRequest request)
    {
        // ...
    }
}

[ApiController] stosuje regułę: złożony typ (klasa/record), który nie pasuje do żadnego segmentu route → domyślnie bindowany z body.

Kiedy [ApiController] NIE ma i [FromBody] faktycznie jest wymagany

[Route("api/[controller]")]
public class OrdersController : Controller // ⚠️ zwykły Controller, BEZ [ApiController]
{
    [HttpPost]
    public async Task<ActionResult> CreateOrder(CreateOrderRequest request)
    {
        // ❌ BEZ [FromBody] - request będzie PUSTY (albo z domyślnymi wartościami)!
        // Framework bez [ApiController] domyślnie próbuje bindować złożone typy
        // z form-data, NIE z JSON body, chyba że jawnie powiesz inaczej
    }

    [HttpPost]
    public async Task<ActionResult> CreateOrder([FromBody] CreateOrderRequest request)
    {
        // ✅ Poprawnie - jawnie wymuszasz bindowanie z JSON body
    }
}

To dotyczy głównie starszych kontrolerów MVC (te renderujące widoki, dziedziczące po Controller, nie po ControllerBase z [ApiController]) - tam [FromBody] jest konieczny, bo bez niego framework nie wie, że masz na myśli JSON z body, a nie np. dane z formularza.

Dlaczego mimo to WARTO pisać [FromBody] jawnie

Mimo że technicznie zbędny w [ApiController], wielu zespołów (i wytyczne stylu) i tak zalecają jawne atrybuty:

1. Czytelność / samodokumentujący się kod

// Bez atrybutów - musisz PAMIĘTAĆ konwencje, żeby wiedzieć skąd co przychodzi
public async Task<ActionResult> Search(string status, int page, CreateOrderRequest request)

// Z atrybutami - widać OD RAZU, patrząc na sygnaturę
public async Task<ActionResult> Search(
    [FromQuery] string status,
    [FromQuery] int page,
    [FromBody] CreateOrderRequest request)

2. Bezpieczeństwo przy refaktoryzacji - jeśli ktoś kiedyś usunie [ApiController] z klasy (np. przy migracji/łączeniu kontrolerów), kod z jawnymi atrybutami dalej działa poprawnie; kod polegający na domyślnych konwencjach cicho się zepsuje.

3. Jednoznaczność przy wielu parametrach złożonych typów - jeśli metoda ma zarówno parametr z route, jak i z query, i coś złożonego - jawność eliminuje niejednoznaczność dla innych czytających kod.

Praktyczna rekomendacja

W nowym kodzie z [ApiController] - [FromBody] jest opcjonalny dla POST/PUT z pojedynczym złożonym parametrem, ale wielu programistów (i część zespołowych code style guide'ów) i tak go dopisuje dla czytelności.

Pytanie-pułapka, jakie mogą zadać na rozmowie

"Co się stanie, jeśli usuniesz [FromBody] z kontrolera BEZ [ApiController]?" - odpowiedź: request zostanie zbindowany błędnie (framework spróbuje czytać z form-data/query zamiast z JSON), co w praktyce oznacza, że wszystkie property obiektu będą miały wartości domyślne (null, 0, false) - to jeden z klasycznych, trudnych do zdiagnozowania bugów u osób migrujących ze starszego MVC albo pomijających [ApiController] "przez przypadek".

Postaw mi kawę