Scaffolding w Visual Studio — szybkie API .NET

API z Visual Studio Scaffolding

Tworzenie interfejsu API od zera to nie lada wyzwanie. Mnogość elementów do zaprogramowania, możliwość popełnienia błędów składniowych czy literówek – to tylko niektóre z przeszkód, które mogą spowolnić pracę nad projektem.

Na szczęście z pomocą przychodzi funkcja Scaffolding w Visual Studio. Ten potężny mechanizm automatyzacji pozwala zaoszczędzić mnóstwo czasu, generując niezbędny kod i konfigurację, dzięki czemu możesz skupić się na najważniejszych aspektach aplikacji, takich jak logika biznesowa.

W tym wpisie pokażę Ci, jak krok po kroku, korzystając z rusztowania (scaffolding) Visual Studio, stworzyć w pełni funkcjonalny interfejs API do rejestracji kontaktów. Dowiesz się, jak szybko wygenerować kluczowe elementy projektu – od modeli, przez konfigurację bazy danych, aż po gotowe punkty końcowe CRUD (Create, Read, Update, Delete).

Gotowy, by zwiększyć efektywność swojej pracy i uniknąć żmudnej ręcznej roboty?
Zanurzmy się w świat Scaffolding!

Krok 1: Przygotowanie projektu w Visual Studio

Pierwszy krok do stworzenia interfejsu API za pomocą Scaffolding to przygotowanie projektu w Visual Studio. Jeśli zaczynasz od zera, wybierz opcję ASP.NET Core Web API podczas tworzenia nowego projektu. Visual Studio zadba o to, aby Twoja aplikacja była gotowa do działania z najnowszymi bibliotekami i najlepszymi praktykami. Daj swojemu projektowi nazwę, która od razu wskazuje na jego funkcjonalność, i upewnij się, że wybrałeś odpowiednią wersję platformy .NET. Kilka kliknięć, a fundamenty Twojego API są gotowe – bez frustracji, bez komplikacji. To jak ustawienie sceny przed wielkim spektaklem!

Postępuj zgodnie z poniższymi krokami:

1. Otwórz Visual Studio i kliknij Utwórz nowy projekt
2. Wybierz opcję ASP.NET Core Web API
3. Nadaj projektowi nazwę EasyContacts
4. Wybierz wersję .NET 8
5. W ustawieniach projektu zaznacz opcje:
   • Konfiguruj dla HTTPS
   • Włącz obsługę OpenAPI
6. Kliknij Utwórz

Krok 2: Definiowanie podstaw w folderze “Entities”

Każde API potrzebuje solidnych fundamentów, a w naszym przypadku zaczniemy od stworzenia folderu Entities, który będzie przechowywać kluczowe klasy reprezentujące dane. Aby uprościć, w tej fazie ręcznie stworzymy tylko jedną klasę – Contact. To tutaj określimy wszystkie właściwości, które będą definiować nasz model kontaktu, takie jak imię, nazwisko, e-mail, numer telefonu i adres. Dzięki temu wszystkie niezbędne dane zostaną przejrzyście zorganizowane, a Twoje API od samego początku będzie spójne i gotowe na zaawansowane funkcjonalności.

To jedyny moment, w którym ręczne kodowanie będzie konieczne – resztę pracy przejmie za nas Scaffolding. Prosta struktura klasy i nowoczesne rozwiązania, takie jak automatyczne dodawanie daty utworzenia, sprawią, że ten krok przebiegnie szybko i intuicyjnie.

Postępuj zgodnie z poniższymi krokami:

1. W utworzonym projekcie dodaj nowy folder o nazwie Entities
2. Wewnątrz folderu stwórz klasę reprezentującą kontakt:

Krok 3: Tworzenie rusztowań (Scaffolding)

Teraz czas na skorzystanie z funkcji Scaffolding dostępnej w Visual Studio, która automatycznie wygeneruje strukturę interfejsu API.

Aby rozpocząć, kliknij prawym przyciskiem myszy projekt, a następnie wybierz Add > New Scaffolded Item….

W wyświetlonym oknie wybierz w menu po lewej API, a następnie opcję API z punktami końcowymi odczytu/zapisu, używając Entity Framework. Kliknij przycisk Dodaj.

W kolejnym oknie skonfiguruj podstawowe klasy EF i punkty końcowe.

W polu Model Class wybierz klasę Contact.
W sekcjach Endpoint Class oraz DbContext Class kliknij ikonę „+”, aby automatycznie je dodać.
W polu Data Provider wybierz odpowiedni dostawcę, na przykład SQLight, lub inny, zgodny z Twoją bazą danych.
Pozostałe opcje możesz pozostawić bez zmian. Po skonfigurowaniu kliknij Dodaj, aby zakończyć proces.

Visual Studio wygeneruje dwie kluczowe klasy:

1. EasyContactsContext – znajdziesz ją w folderze Data. Jest to klasa DbContext, zawierająca konfiguracje dla EF Core. Dziedziczy ona po DbContext i pozwala na zarządzanie bazą danych poprzez operacje CRUD. Właściwość DbSet<Contact> reprezentuje kolekcję jednostek Contact i umożliwia łatwą manipulację danymi. Dzięki przekazaniu parametrów DbContextOptions do klasy bazowej konstruktor definiuje m.in. połączenie z bazą.
2. ContactEndpoints – organizuje punkty końcowe API, dzięki czemu kod jest bardziej przejrzysty i modularny. Ta klasa zawiera gotowe punkty końcowe dla operacji CRUD oraz wspiera grupowanie tras za pomocą MapGroup, co poprawia czytelność kodu. Dodatkowo metoda AsNoTracking() zwiększa wydajność, eliminując monitorowanie zmian w obiektach.

Dzięki Scaffolding, klasa Program zostaje automatycznie zaktualizowana. Zostaje w niej dodana konfiguracja dla AddDbContext (z dostawcą, np. UseSqlite, oraz ciągiem połączenia). W pliku appsettings.json znajdziesz wygenerowany ciąg połączenia.

Dzięki tym krokom Twój interfejs API jest gotowy do pracy i od razu funkcjonalny!

Krok 4: Tworzenie i uruchamianie migracji EF Core

Migracje EF Core to funkcjonalność, która automatycznie generuje i uruchamia skrypty bazy danych, tworząc niezbędne struktury (bazy danych i tabele) na podstawie encji aplikacji. Dzięki temu możesz zaoszczędzić czas i uniknąć błędów podczas ręcznej konfiguracji bazy danych. Oto, jak łatwo wykonać ten proces za pomocą funkcji Scaffolding w Visual Studio:

Po zakończeniu tego procesu baza danych oraz odpowiadające jej tabele zostaną utworzone zgodnie z Twoim modelem danych. Możesz łatwo sprawdzić strukturę bazy, potwierdzając, że została poprawnie zaktualizowana na podstawie migracji.

1. Dodawanie migracji
   • W Visual Studio i przejdź do zakładki Connected Services (Połączone usługi) i kliknij ją dwukrotnie
   • W prawym rogu okna przy wybranej bazie SQLight kliknij ikonę z trzema kropkami, a następnie wybierz opcję Dodaj migrację.
   • W nowym oknie wybierz klasę kontekstu (np. EasyContactsContext) i kliknij Zakończ.
   • Migracja została utworzona – możesz ją przejrzeć w odpowiednim folderze projektu, co pozwala zobaczyć wygenerowane skrypty SQL.
2. Aktualizacja bazy danych
   • W tej samej zakładce Connected Services kliknij ikonę z trzema kropkami i wybierz Zaktualizuj bazę danych.
   • W nowym oknie wybierz context i kliknij przycisk Zakończ, aby uruchomić skrypty migracji.

Po zakończeniu tego procesu baza danych oraz odpowiadające jej tabele zostaną utworzone zgodnie z Twoim modelem danych. Możesz łatwo sprawdzić strukturę bazy, potwierdzając, że została poprawnie zaktualizowana na podstawie migracji.

Dzięki automatyzacji przez Scaffolding cały proces jest szybki, intuicyjny i minimalizuje ryzyko pomyłek!

Krok 5: Testowanie aplikacji

Po zakończeniu konfiguracji bazy danych i punktów końcowych, czas na testowanie naszej aplikacji! Uruchom projekt w Visual Studio i przejdź do przeglądarki. Sprawdź, czy interfejs API działa poprawnie, wywołując odpowiednie punkty końcowe. Możesz przetestować operacje CRUD (tworzenie, odczytywanie, aktualizowanie, usuwanie) na danych, aby upewnić się, że aplikacja komunikuje się z bazą danych bez problemów. Jeśli wszystko działa zgodnie z planem, gratulacje — właśnie stworzyłeś działający interfejs API za pomocą rusztowania Visual Studio!

Zakończenie

Jak widać, po przeprowadzeniu wszystkich kroków nasza aplikacja działa zgodnie z oczekiwaniami. Funkcje rusztowania w Visual Studio znacznie uprościły proces tworzenia interfejsu API CRUD, zapewniając nam poprawnie skonfigurowane klasy, kontrolery i konfiguracje bazy danych. Dzięki tym narzędziom zaoszczędzimy czas na ręcznym pisaniu powtarzalnego kodu, co pozwoli skupić się na bardziej złożonych aspektach aplikacji.

Rusztowanie w ASP.NET Core to doskonałe narzędzie, które przyspiesza rozwój aplikacji, szczególnie w projektach opartych na wzorcu MVC, gdzie generowanie standardowych komponentów pozwala zaoszczędzić cenny czas i zredukować liczbę błędów. Funkcje CRUD generowane automatycznie umożliwiają szybkie wdrożenie podstawowej funkcjonalności, dając programistom większą swobodę w implementacji specyficznych funkcji i reguł biznesowych.

Podsumowując, użycie rusztowania to efektywny sposób na szybkie rozpoczęcie pracy nad projektem, przy zachowaniu wysokiej jakości kodu zgodnej z najlepszymi praktykami ASP.NET Core. Jest to szczególnie cenne w przypadku rozwoju aplikacji z wykorzystaniem architektury API, gdzie czas i precyzyjność mają kluczowe znaczenie.

Kod, który faktycznie generuje Scaffolding

Powyższe kroki to kliknięcia w kreatorze — zobaczmy teraz dokładnie, jaki kod te kliknięcia faktycznie tworzą.

Encja Contact (Krok 2 — ta jedyna klasa pisana ręcznie)

namespace EasyContacts.Entities;

public class Contact
{
    public int Id { get; set; }
    public string Imie { get; set; } = string.Empty;
    public string Nazwisko { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public string Telefon { get; set; } = string.Empty;
    public DateTime DataUtworzenia { get; set; } = DateTime.UtcNow;
}

EasyContactsContext (wygenerowany DbContext)

public class EasyContactsContext : DbContext
{
    public EasyContactsContext(DbContextOptions<EasyContactsContext> options) : base(options) { }
    public DbSet<Contact> Contact { get; set; } = default!;
}

ContactEndpoints (wygenerowane punkty końcowe CRUD)

public static class ContactEndpoints
{
    public static void MapContactEndpoints(this IEndpointRouteBuilder routes)
    {
        var group = routes.MapGroup("/api/Contact");

        group.MapGet("/", async (EasyContactsContext db) =>
            await db.Contact.AsNoTracking().ToListAsync());

        group.MapGet("/{id}", async (int id, EasyContactsContext db) =>
            await db.Contact.AsNoTracking().FirstOrDefaultAsync(c => c.Id == id)
                is Contact model ? Results.Ok(model) : Results.NotFound());

        group.MapPost("/", async (Contact contact, EasyContactsContext db) =>
        {
            db.Contact.Add(contact);
            await db.SaveChangesAsync();
            return Results.Created($"/api/Contact/{contact.Id}", contact);
        });

        group.MapPut("/{id}", async (int id, Contact input, EasyContactsContext db) =>
        {
            var contact = await db.Contact.FindAsync(id);
            if (contact is null) return Results.NotFound();
            contact.Imie = input.Imie;
            contact.Email = input.Email;
            await db.SaveChangesAsync();
            return Results.NoContent();
        });

        group.MapDelete("/{id}", async (int id, EasyContactsContext db) =>
        {
            if (await db.Contact.FindAsync(id) is Contact contact)
            {
                db.Contact.Remove(contact);
                await db.SaveChangesAsync();
                return Results.NoContent();
            }
            return Results.NotFound();
        });
    }
}

MapGroup grupuje wszystkie trasy pod wspólnym prefiksem /api/Contact, a AsNoTracking() na zapytaniach tylko-do-odczytu (GET) pomija niepotrzebne śledzenie zmian przez EF Core, poprawiając wydajność.

Program.cs — automatycznie dopisana konfiguracja

builder.Services.AddDbContext<EasyContactsContext>(options =>
    options.UseSqlite(builder.Configuration.GetConnectionString("EasyContactsContext")));

app.MapContactEndpoints();

Migracja EF Core (Krok 4 — odpowiednik CLI dla tych samych kliknięć)

dotnet ef migrations add InitialCreate
dotnet ef database update

protected override void Up(MigrationBuilder migrationBuilder)
{
    migrationBuilder.CreateTable(
        name: "Contact",
        columns: table => new
        {
            Id = table.Column<int>(nullable: false).Annotation("Sqlite:Autoincrement", true),
            Imie = table.Column<string>(nullable: false),
            Nazwisko = table.Column<string>(nullable: false),
            Email = table.Column<string>(nullable: false),
            Telefon = table.Column<string>(nullable: false),
            DataUtworzenia = table.Column<DateTime>(nullable: false)
        },
        constraints: table => table.PrimaryKey("PK_Contact", x => x.Id));
}

Test wygenerowanego API (Krok 5)

curl -X POST https://localhost:7042/api/Contact -H "Content-Type: application/json" -d "{"imie":"Jan","nazwisko":"Kowalski","email":"jan@example.com","telefon":"123456789"}"

curl https://localhost:7042/api/Contact

Pierwsze polecenie tworzy nowy kontakt (odpowiada punktowi końcowemu MapPost), drugie pobiera listę wszystkich kontaktów (MapGet) — dokładnie ten sam kod, który kreator Scaffolding wygenerował za Ciebie w kroku 3.

Powiązane: scaffolding generuje kod dostępu do danych na bazie EF Core; alternatywa ręczna to API z Dapperem. Nie zapomnij o connection stringu.