Samouczek: tworzenie internetowego interfejsu API opartego na kontrolerze przy użyciu platformy ASP.NET Core

Autorzy: Tim Deschryver i Rick Anderson

Ten samouczek uczy podstaw tworzenia webowego interfejsu API opartego na kontrolerze, który korzysta z bazy danych. Innym podejściem do tworzenia interfejsów API w środowisku ASP.NET Core jest utworzenie minimalnych interfejsów API. Aby uzyskać pomoc dotyczącą wybierania między minimalnymi interfejsami API i interfejsami API opartymi na kontrolerach, zobacz Omówienie interfejsów API. Aby zapoznać się z samouczkiem dotyczącym tworzenia minimalnego interfejsu API, zobacz Samouczek: tworzenie minimalnego interfejsu API przy użyciu platformy ASP.NET Core.

Omówienie

Ten samouczek tworzy następujący interfejs API:

Interfejs API	opis	Treść żądania	Treść odpowiedzi
GET /api/todoitems	Pobierz wszystkie zadania do zrobienia	Brak	Tablica elementów do wykonania
GET /api/todoitems/{id}	Pobieranie elementu według identyfikatora	Brak	Element do wykonania
POST /api/todoitems	Dodawanie nowego elementu	Element do wykonania	Element do wykonania
PUT /api/todoitems/{id}	Aktualizowanie istniejącego elementu	Element do wykonania	Brak
DELETE /api/todoitems/{id}	Usuwanie elementu	Brak	Brak

Na poniższym diagramie przedstawiono projekt aplikacji.

Wymagania wstępne

Visual Studio

• Program Visual Studio 2022 z pakietem roboczym tworzenia aplikacji ASP.NET i aplikacji internetowych.

  

Visual Studio Code

• Visual Studio Code
• Zestaw deweloperski języka C# dla programu Visual Studio Code
• SDK .NET 9.0

Możesz postępować zgodnie z instrukcjami programu Visual Studio Code w systemach macOS, Linux lub Windows. Zmiany mogą być wymagane, jeśli używasz zintegrowanego środowiska projektowego (IDE) innego niż Visual Studio Code.

Tworzenie projektu Web API

Visual Studio

• W menu Plik wybierz pozycję Nowy>projekt.
• Wprowadź Web API w polu wyszukiwania.
• Wybierz szablon internetowego interfejsu API platformy ASP.NET Core i wybierz pozycję Dalej.
• W oknie dialogowym Konfigurowanie nowego projektu nadaj projektowi nazwę TodoApi i wybierz pozycję Dalej.
• W oknie dialogowym Dodatkowe informacje:
  • Upewnij się, że Framework jest .NET 9.0 (obsługa terminów standardowych).
  • Upewnij się, że zaznaczono pole wyboru Włącz obsługę interfejsu OpenAPI.
  • Potwierdź, że pole wyboru Użyj kontrolerów (usuń zaznaczenie, aby korzystać z minimalnych interfejsów API) jest zaznaczone.
  • Wybierz pozycję Utwórz.

Dodawanie pakietu NuGet

Aby dodać obsługę dla bazy danych używanej w tym samouczku, należy dodać pakiet NuGet.

• W menu Narzędzia wybierz pozycję NuGet Menedżer pakietów > Zarządzaj pakietami NuGet dla rozwiązania.
• Wybierz kartę Przeglądaj.
• Wprowadź ciąg Microsoft.EntityFrameworkCore.InMemory w polu wyszukiwania, a następnie wybierz pozycję Microsoft.EntityFrameworkCore.InMemory.
• Zaznacz pole wyboru Projekt w okienku po prawej stronie, a następnie wybierz pozycję Zainstaluj.

Visual Studio Code

• Otwórz zintegrowany terminal.

• Zmień katalogi (cd) na folder, który będzie zawierał folder projektu.

• Uruchom następujące polecenia:

  dotnet new webapi --use-controllers -o TodoApi
  cd TodoApi
  dotnet add package Microsoft.EntityFrameworkCore.InMemory
  code -r ../TodoApi
  

  Następujące polecenia:

  • Utwórz nowy projekt internetowego interfejsu API i otwórz go w programie Visual Studio Code.
  • Dodaj pakiet NuGet wymagany do następnej sekcji.
  • Otwórz folder TodoApi w bieżącym wystąpieniu programu Visual Studio Code.

Program Visual Studio Code może wyświetlić okno dialogowe z pytaniem: Czy ufasz autorom plików w tym folderze?

• Jeśli ufasz wszystkim plikom w folderze nadrzędnym, wybierz pozycję Ufaj autorom wszystkich plików w folderze nadrzędnym.
• Wybierz pozycję Tak. Ufam autorom , ponieważ folder projektu zawiera pliki wygenerowane przez platformę .NET.
• Gdy program Visual Studio Code zażąda dodania zasobów do kompilowania i debugowania projektu, wybierz pozycję Tak. Jeśli program Visual Studio Code nie oferuje dodawania zasobów kompilacji i debugowania, wybierz pozycję Widok>Paletę poleceń i wpisz ".NET" w polu wyszukiwania. Z listy poleceń wybierz .NET: Generate Assets for Build and Debug polecenie .

Program Visual Studio Code dodaje folder .vscode z plikami launch.json i tasks.json które są wygenerowane.

Uwaga

Aby uzyskać instrukcje dodawania pakietów do aplikacji .NET, zobacz artykuły w sekcji Instalowanie pakietów i zarządzanie nimi w temacie Przepływ pracy użycia pakietów (dokumentacja programu NuGet). Sprawdź prawidłowe wersje pakietów pod adresem NuGet.org.

Uruchamianie projektu

Szablon projektu tworzy interfejs API WeatherForecast, który wspiera OpenAPI.

Visual Studio

Naciśnij Ctrl+F5, aby uruchomić bez debugera.

Program Visual Studio wyświetla następujące okno dialogowe, gdy projekt nie jest jeszcze skonfigurowany do używania protokołu SSL:

Wybierz pozycję Tak , jeśli ufasz certyfikatowi SSL usług IIS Express.

Zostanie wyświetlone następujące okno dialogowe:

Wybierz pozycję Tak, jeśli wyrażasz zgodę na zaufanie certyfikatowi programistycznemu.

Aby uzyskać informacje na temat zaufania przeglądarce Firefox, zobacz Błąd certyfikatu przeglądarki Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Program Visual Studio uruchamia okno terminalu i wyświetla adres URL uruchomionej aplikacji. Interfejs API jest hostowany w https://localhost:<port>, gdzie <port> jest losowo wybranym numerem portu ustawionym podczas tworzenia projektu.

...
info: Microsoft.Hosting.Lifetime[14]
   Now listening on: https://localhost:7260
info: Microsoft.Hosting.Lifetime[14]
   Now listening on: http://localhost:7261
info: Microsoft.Hosting.Lifetime[0]
   Application started. Press Ctrl+C to shut down.
...

Naciśnij Ctrl+, aby przetestować aplikację internetową w przeglądarce, kliknij adres URL HTTPS w danych wyjściowych. Brak punktu końcowego w adresie https://localhost:<port>, więc przeglądarka zwraca błąd HTTP 404 Nie znaleziono.

Dołącz /weatherforecast do adresu URL, aby przetestować interfejs API WeatherForecast. W przeglądarce zostanie wyświetlony kod JSON podobny do następującego przykładu:

[
    {
        "date": "2025-07-16",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2025-07-17",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2025-07-18",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2025-07-19",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2025-07-20",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Visual Studio Code

• Ufaj certyfikatowi programistycznemu HTTPS, uruchamiając następujące polecenie:

  dotnet dev-certs https --trust
  

  Poprzednie polecenie wyświetla następujące okno dialogowe, pod warunkiem, że certyfikat nie był wcześniej zaufany:

  

• Wybierz pozycję Tak, jeśli wyrażasz zgodę na zaufanie certyfikatowi programistycznemu.

  Aby uzyskać więcej informacji, zobacz sekcję Trust the ASP.NET Core HTTPS development certificate (Ufaj certyfikatowi programistycznemu ASP.NET Core HTTPS) artykułu Wymuszanie protokołu SSL .

Aby uzyskać informacje dotyczące zaufania do przeglądarki Firefox, zobacz Błąd certyfikatu Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Uruchom aplikację:

• Uruchom następujące polecenie, aby uruchomić aplikację na profilu https.

  dotnet run --launch-profile https
  

Dane wyjściowe zawierają komunikaty podobne do następujących, co wskazuje, że aplikacja jest uruchomiona i oczekuje na żądania:

...
info: Microsoft.Hosting.Lifetime[14]
      Now listening on: https://localhost:{port}
...

• Naciśnij Ctrl+i kliknij adres URL HTTPS w danych wyjściowych, aby przetestować aplikację internetową w przeglądarce.

• Domyślna przeglądarka zostaje uruchomiona na https://localhost:<port>, gdzie <port> jest losowo wybranym numerem portu, wyświetlanym w danych wyjściowych. Brak punktu końcowego w adresie https://localhost:<port>, więc przeglądarka zwraca błąd HTTP 404 Nie znaleziono.

• Dołącz /weatherforecast do adresu URL, aby przetestować interfejs API WeatherForecast. W przeglądarce zostanie wyświetlony kod JSON podobny do następującego przykładu:

[
    {
        "date": "2025-07-16",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2025-07-17",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2025-07-18",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2025-07-19",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2025-07-20",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

• Po przetestowaniu aplikacji internetowej przy użyciu poniższej instrukcji naciśnij Ctrl+C w zintegrowanym terminalu, aby go zamknąć.

Testowanie projektu

Visual Studio

W tym samouczku używamy Endpoints Explorer i plików .http do testowania interfejsu API.

Visual Studio Code

Tworzenie interfejsu testowania API za pomocą Swaggera

Dostępnych jest wiele dostępnych internetowych narzędzi do testowania interfejsu API, które można wybrać, i możesz wykonać kroki testu wprowadzającego interfejsu API za pomocą preferowanego narzędzia.

W tym samouczku wykorzystano pakiet .NET NSwag.AspNetCore, który integruje narzędzia Swagger do generowania interfejsu użytkownika testowania zgodnego ze specyfikacją OpenAPI.

• NSwag: biblioteka platformy .NET, która integruje program Swagger bezpośrednio z aplikacjami ASP.NET Core, zapewniając oprogramowanie pośredniczące i konfigurację.
• Swagger: zestaw narzędzi typu open source, takich jak OpenAPIGenerator i SwaggerUI, które generują strony testowania interfejsu API zgodne ze specyfikacją interfejsu OpenAPI.
• Specyfikacja interfejsu OpenAPI: dokument opisujący możliwości interfejsu API na podstawie adnotacji XML i atrybutów w kontrolerach i modelach.

Aby uzyskać więcej informacji na temat korzystania z interfejsu OpenAPI i NSwag z ASP.NET, zobacz dokumentację internetowego interfejsu API platformy ASP.NET Core w programie Swagger/OpenAPI.

Zainstaluj narzędzia Swagger

• Uruchom następujące polecenie:

  dotnet add package NSwag.AspNetCore
  

Poprzednie polecenie dodaje pakiet NSwag.AspNetCore, który zawiera narzędzia do generowania dokumentów Swagger i interfejsu użytkownika. Ponieważ nasz projekt wykorzystuje OpenAPI, używamy tylko pakietu NSwag do generowania Swagger UI.

Konfigurowanie oprogramowania pośredniczącego Swagger

• W Program.csdodaj następujący wyróżniony kod:

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.UseSwaggerUi(options =>
    {
        options.DocumentPath = "/openapi/v1.json";
    });
}

Poprzedni kod umożliwia middleware Swagger do obsługi wygenerowanego dokumentu JSON przy użyciu interfejsu Swagger. Program Swagger jest włączony tylko w środowisku projektowym. Włączenie Swagger w środowisku produkcyjnym może ujawniać szczegóły, które mogą być poufne, dotyczące struktury i implementacji API.

Aplikacja używa dokumentu OpenAPI wygenerowanego przez OpenApi, znajdującego się w lokalizacji /openapi/v1.json, do generowania UI. Wyświetl wygenerowaną specyfikację interfejsu OpenAPI dla interfejsu API WeatherForecast, gdy projekt jest uruchomiony, przechodząc do https://localhost:<port>/openapi/v1.json w przeglądarce.

Specyfikacja interfejsu OpenAPI to dokument w formacie JSON, który opisuje strukturę i możliwości interfejsu API, w tym punkty końcowe, formaty żądań/odpowiedzi, parametry i inne. Zasadniczo jest to strategia interfejsu API, która może być używana przez różne narzędzia do zrozumienia interfejsu API i interakcji z nim.

Dodawanie klasy modelu

Model to zestaw klas reprezentujących dane, którymi zarządza aplikacja. Model dla tej aplikacji jest klasą TodoItem .

Visual Studio

• W Eksplorator rozwiązań kliknij prawym przyciskiem myszy projekt. Wybierz pozycję Dodaj>nowy folder. Nadaj folderowi Modelsnazwę .
• Kliknij prawym przyciskiem Models myszy folder i wybierz polecenie Dodaj>klasę. Nadaj klasie nazwę TodoItem i wybierz pozycję Dodaj.
• Zastąp kod szablonu następującym kodem:

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Visual Studio Code

• Dodaj folder o nazwie Models.
• TodoItem.cs Dodaj plik do Models folderu przy użyciu następującego kodu:

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Właściwość Id działa jako unikatowy klucz w relacyjnej bazie danych.

Klasy modeli mogą znajdować się w dowolnym miejscu w projekcie, ale Models folder jest używany zgodnie z konwencją.

Dodawanie kontekstu bazy danych

Kontekst bazy danych jest klasą główną, która koordynuje funkcje programu Entity Framework dla modelu danych. Ta klasa jest tworzona przez wyprowadzanie z Microsoft.EntityFrameworkCore.DbContext klasy .

Visual Studio

• Kliknij prawym przyciskiem Models myszy folder i wybierz polecenie Dodaj>klasę. Nadaj klasie nazwę TodoContext i kliknij przycisk Dodaj.

• Wprowadź następujące kod:

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models;
  
  public class TodoContext : DbContext
  {
      public TodoContext(DbContextOptions<TodoContext> options)
          : base(options)
      {
      }
  
      public DbSet<TodoItem> TodoItems { get; set; } = null!;
  }
  

Visual Studio Code

• TodoContext.cs Dodaj plik do Models folderu.

• Wprowadź następujące kod:

  using Microsoft.EntityFrameworkCore;
  
  namespace TodoApi.Models;
  
  public class TodoContext : DbContext
  {
      public TodoContext(DbContextOptions<TodoContext> options)
          : base(options)
      {
      }
  
      public DbSet<TodoItem> TodoItems { get; set; } = null!;
  }
  

Rejestrowanie kontekstu bazy danych

W ASP.NET Core usługi, takie jak kontekst bazy danych, muszą być zarejestrowane w kontenerze wstrzykiwania zależności (DI). Kontener udostępnia usługę kontrolerom.

Zaktualizuj Program.cs za pomocą następującego wyróżnionego kodu:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApi();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Poprzedni kod:

• Dodaje using dyrektywy.
• Dodaje kontekst bazy danych do kontenera DI.
• Określa, że kontekst bazy danych będzie używać bazy danych w pamięci.

Tworzenie szkieletu kontrolera

Visual Studio

• Kliknij prawym przyciskiem myszy folder Controllers.

• Wybierz Dodaj>New Scaffolded Item.

• Wybierz pozycję Kontroler interfejsu API z akcjami przy użyciu platformy Entity Framework, a następnie wybierz pozycję Dodaj.

• W oknie dialogowym Dodaj kontroler API z akcjami, za pomocą Entity Framework:

  • Wybierz pozycję TodoItem (TodoApi.Models) w klasie Model.
  • Wybierz pozycję TodoContext (TodoApi.Models) w klasie Kontekst danych.
  • Wybierz Dodaj.

  Jeśli operacja tworzenia szkieletu nie powiedzie się, wybierz pozycję Dodaj , aby spróbować utworzyć szkielet po raz drugi.

Ten krok dodaje do projektu pakiety Microsoft.VisualStudio.Web.CodeGeneration.Design i Microsoft.EntityFrameworkCore.Tools NuGet. Te pakiety są wymagane do tworzenia szkieletów.

Visual Studio Code

Upewnij się, że wszystkie zmiany do tej pory zostały zapisane.

• Kliknij prawym przyciskiem myszy (lub kliknij polecenie w systemie macOS) projekt TodoAPI i wybierz pozycję Otwórz wterminalu . Terminal zostanie otwarty w folderze TodoAPI projektu. Uruchom następujące polecenia:

dotnet add package Microsoft.VisualStudio.Web.CodeGeneration.Design
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.EntityFrameworkCore.SqlServer
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet tool uninstall -g dotnet-aspnet-codegenerator
dotnet tool install -g dotnet-aspnet-codegenerator
dotnet tool update -g dotnet-aspnet-codegenerator

Poprzednie polecenia:

• Dodaj pakiety NuGet wymagane do tworzenia szkieletów.
• Zainstaluj silnik rusztowania (dotnet-aspnet-codegenerator) po odinstalowaniu każdej możliwej poprzedniej wersji.

W przypadku systemu Linux dodaj katalog narzędzi .NET do ścieżki systemowej za pomocą następującego polecenia:

echo 'export PATH=$HOME/.dotnet/tools:$PATH' >> ~/.bashrc
source ~/.bashrc

Uwaga

Domyślnie architektura plików binarnych platformy .NET do zainstalowania reprezentuje obecnie uruchomioną architekturę systemu operacyjnego. Aby określić inną architekturę systemu operacyjnego, zobacz dotnet tool install, --arch option(Instalacja narzędzia dotnet). Aby uzyskać więcej informacji, zobacz kwestię na GitHubie dotnet/AspNetCore.Docs #29262.

Skompiluj projekt.

Uruchom następujące polecenie:

dotnet aspnet-codegenerator controller -name TodoItemsController -async -api -m TodoItem -dc TodoContext -outDir Controllers

Poprzednie polecenie tworzy szkielet TodoItemsController.

Wygenerowany kod:

• Oznacza klasę za pomocą atrybutu [ApiController] . Ten atrybut wskazuje, że kontroler odpowiada na żądania internetowego interfejsu API. Aby uzyskać informacje o konkretnych zachowaniach, które włącza atrybut, zobacz Tworzenie internetowych interfejsów API za pomocą ASP.NET Core.
• Używa DI do implementacji kontekstu bazy danych (TodoContext) do kontrolera. Kontekst bazy danych jest używany w każdej z metod CRUD w kontrolerze.

Szablony ASP.NET Core dla:

• Kontrolery z widokami zawierają [action] w szablonie trasy.
• Kontrolery interfejsów API nie zawierają [action] w szablonie trasy.

[action] Jeśli token nie znajduje się w szablonie trasy, nazwa akcji (nazwa metody) nie jest uwzględniona w punkcie końcowym. Oznacza to, że skojarzona nazwa metody akcji nie jest używana w pasującej ścieżce.

Aktualizowanie metody PostTodoItem create

Zaktualizuj instrukcję return PostTodoItem, aby użyć operatora nameof:

[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
    _context.TodoItems.Add(todoItem);
    await _context.SaveChangesAsync();

    //    return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
    return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}

Kod przedstawiony powyżej to metoda HTTP POST, co jest wskazane przez atrybut [HttpPost]. Metoda pobiera wartość TodoItem z treści żądania HTTP.

Aby uzyskać więcej informacji, zobacz Routing atrybutów z użyciem atrybutów Http[Verb].

Metoda CreatedAtAction:

• Zwraca kod stanu HTTP 201, jeśli się powiedzie. HTTP 201 to standardowa odpowiedź dla HTTP POST metody, która tworzy nowy zasób na serwerze.
• Dodaje nagłówek Location do odpowiedzi. Nagłówek Location określa identyfikator URI nowo utworzonego elementu do wykonania. Aby uzyskać więcej informacji, zobacz 10.2.2 201 Utworzono.
• Odwołuje się do akcji GetTodoItem w celu utworzenia identyfikatora URI nagłówka Location. Słowo kluczowe języka C# nameof służy do unikania kodowania na stałe nazwy akcji w wywołaniu CreatedAtAction .

Test PostTodoItem

Visual Studio

• Wybierz Widok>Inne okna>Eksplorator punktów końcowych.

• Kliknij prawym przyciskiem myszy punkt końcowy POST i wybierz polecenie Generuj żądanie.

  

  Nowy plik jest tworzony w folderze projektu o nazwie TodoApi.http, z zawartością podobną do następującego przykładu:

  @TodoApi_HostAddress = https://localhost:49738
  
  POST {{TodoApi_HostAddress}}/api/todoitems
  Content-Type: application/json
  
  {
    //TodoItem
  }
  
  ###
  

  • Pierwszy wiersz tworzy zmienną używaną dla wszystkich punktów końcowych.
  • Następny wiersz definiuje żądanie POST.
  • Wiersze po wierszu żądania POST definiują nagłówki i symbol zastępczy treści żądania.
  • Potrójny hasztag (###) jest ogranicznikiem żądania: to, co następuje po nim, jest przeznaczone dla innego żądania.

• Żądanie POST oczekuje TodoItem. Aby zdefiniować todo, zastąp komentarz //TodoItem następującym kodem JSON:

  {
    "name": "walk dog",
    "isComplete": true
  }
  

  Plik TodoApi.http powinien teraz wyglądać podobnie do poniższego przykładu, ale z numerem portu:

  @TodoApi_HostAddress = https://localhost:7260
  
  Post {{TodoApi_HostAddress}}/api/todoitems
  Content-Type: application/json
  
  {
    "name": "walk dog",
    "isComplete": true
  }
  
  ###
  

• Uruchom aplikację.

• Wybierz link Wyślij żądanie powyżej POST wiersza żądania.

  

  Żądanie POST jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedź .

  

Visual Studio Code

• Gdy aplikacja jest nadal uruchomiona, w przeglądarce przejdź do https://localhost:<port>/swagger strony testowania interfejsu API wygenerowanej przez program Swagger. Kliknij todoItems, aby rozwinąć operacje.

  

• Na stronie testowania API Swagger wybierz pozycję Post /api/todoitems>Wypróbuj to.

• Zwróć uwagę, że pole Treść żądania zawiera wygenerowany przykładowy format odzwierciedlający parametry interfejsu API.

• W treści żądania wprowadź kod JSON dla elementu do wykonania bez określania opcjonalnego elementu id:

  {
    "name": "walk dog",
    "isComplete": true
  }
  

• Wybierz i wykonaj.

  

• Program Swagger udostępnia okienko Odpowiedzi poniżej przycisku Wykonaj .

  

Zwróć uwagę na kilka przydatnych szczegółów:

• pl-PL: cURL: Program Swagger udostępnia przykładowe polecenie cURL w składni systemu Unix/Linux, które można uruchomić w wierszu polecenia z dowolną powłoką bash korzystającą ze składni systemu Unix/Linux, w tym powłoki Git Bash z Git dla Windows.
• Adres URL żądania: uproszczona reprezentacja żądania HTTP wykonanego przez Swagger UI działającego w oparciu o kod JavaScript dla wywołania interfejsu API. Rzeczywiste żądania mogą zawierać szczegóły, takie jak nagłówki i parametry zapytania oraz treść żądania.
• Odpowiedź serwera: zawiera treść odpowiedzi i nagłówki. Treść odpowiedzi pokazuje, że id został ustawiony na 1.
• Kod odpowiedzi: zwrócono kod stanu 201 HTTP , wskazujący, że żądanie zostało pomyślnie przetworzone i spowodowało utworzenie nowego zasobu.

Testowanie URI nagłówka Location

Visual Studio

Przetestuj GET aplikację, wywołując punkty końcowe z przeglądarki lub przy użyciu Eksploratora punktów końcowych. Poniższe kroki dotyczą Eksploratora punktów końcowych.

• W Eksploratorze punktów końcowych kliknij prawym przyciskiem myszy pierwszy punkt końcowy GET i wybierz polecenie Generuj żądanie.

  Do pliku zostanie dodana następująca TodoApi.http zawartość:

  GET {{TodoApi_HostAddress}}/api/todoitems
  
  ###
  

• Wybierz link Wyślij żądanie powyżej nowego GET wiersza żądania.

  Żądanie GET jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedź .

• Treść odpowiedzi jest podobna do następującego kodu JSON:

  [
    {
      "id": 1,
      "name": "walk dog",
      "isComplete": true
    }
  ]
  

• W Eksploratorze punktów końcowych kliknij prawym przyciskiem /api/todoitems/{id} myszy punkt końcowy GET i wybierz pozycję Generuj żądanie. Do pliku zostanie dodana następująca TodoApi.http zawartość:

  @id=0
  GET {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  
  ###
  

• Przypisz {@id} do 1 (zamiast 0).

• Wybierz link Wyślij żądanie powyżej nowego wiersza żądania GET.

  Żądanie GET jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedź .

• Treść odpowiedzi jest podobna do następującego kodu JSON:

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
  

Visual Studio Code

Przetestuj aplikację, wywołując punkty końcowe z przeglądarki lub programu Swagger.

• W Swaggerze wybierz GET /api/todoitems>Wypróbuj>Wykonaj.

• Alternatywnie wywołaj GET /api/todoitems z przeglądarki, wprowadzając adres URI https://localhost:<port>/api/todoitems. Na przykład https://localhost:7260/api/todoitems

Wywołanie GET /api/todoitems produkuje odpowiedź podobną do następującej:

[
  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
]

• Wywołaj GET /api/todoitems/{id} w programie Swagger, aby zwrócić dane z określonego identyfikatora:

  • Wybierz pozycję GET /api/todoitems>Wypróbuj.
  • Ustaw pole id na 1 i wybierz pozycję Wykonaj.

• Alternatywnie wywołaj GET /api/todoitems z przeglądarki, wpisując URI https://localhost:<port>/api/todoitems/1. Na przykład https://localhost:7260/api/todoitems/1

• Odpowiedź jest podobna do następującej:

  {
    "id": 1,
    "name": "walk dog",
    "isComplete": true
  }
  

Zbadanie metod GET

Zaimplementowano dwa punkty końcowe GET:

• GET /api/todoitems
• GET /api/todoitems/{id}

W poprzedniej sekcji przedstawiono przykład /api/todoitems/{id} trasy.

Postępuj zgodnie z instrukcjami POST, aby dodać kolejny element zadania do wykonania, a następnie przetestuj /api/todoitems trasę przy użyciu narzędzia Swagger.

Ta aplikacja używa bazy danych w pamięci. Jeśli aplikacja zostanie zatrzymana i uruchomiona, powyższe żądanie GET nie zwraca żadnych danych. Jeśli żadne dane nie są zwracane, prześlij dane metodą POST do aplikacji.

Routing i ścieżki adresów URL

Atrybut [HttpGet] określa metodę, która odpowiada na HTTP GET żądanie. Ścieżka adresu URL dla każdej metody jest skonstruowana w następujący sposób:

• Zacznij od ciągu szablonu w atrybucie kontrolera Route :

  [Route("api/[controller]")]
  [ApiController]
  public class TodoItemsController : ControllerBase
  

• Zastąp [controller] nazwę kontrolera, który zgodnie z konwencją jest nazwą klasy kontrolera minus końcówka "Kontroler". W tym przykładzie nazwa klasy kontrolera to TodoItemsController, więc nazwa kontrolera to "TodoItems". ASP.NET Core routing jest niewrażliwy na wielkość liter.

• [HttpGet] Jeśli atrybut ma szablon trasy (na przykład [HttpGet("products")]), dołącz go do ścieżki. Ten przykład nie używa szablonu. Aby uzyskać więcej informacji, zobacz Routing atrybutowy z użyciem atrybutów Http[Verb].

W poniższej metodzie GetTodoItem, zmienna "{id}" pełni rolę zastępczą dla unikatowego identyfikatora zadania do wykonania. Gdy GetTodoItem jest wywoływane, wartość "{id}" w adresie URL jest przekazywana do metody jako parametr id.

[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);

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

    return todoItem;
}

Wartości zwracane

Typ zwracany przez metody GetTodoItems i GetTodoItem to typ ActionResult<T>. ASP.NET Core automatycznie serializuje obiekt w formacie JSON i zapisuje kod JSON w treści komunikatu odpowiedzi. Kod odpowiedzi dla tego typu zwracanego to 200 OK, zakładając, że nie ma żadnych nieobsługiwanych wyjątków. Nieobsługiwane wyjątki są tłumaczone na błędy 5xx.

ActionResult typy zwracane mogą reprezentować szeroką gamę kodów stanu HTTP. Na przykład GetTodoItem może zwrócić dwie różne wartości stanu:

• Jeśli żaden element nie pasuje do żądanego identyfikatora, metoda zwraca kod błędu stanuNotFound 404.
• W przeciwnym razie, metoda zwraca wartość 200 z ciałem odpowiedzi w formacie JSON. Zwrócenie item wyników skutkuje HTTP 200 odpowiedzią.

Metoda PutTodoItem

Przeanalizuj metodę PutTodoItem:

[HttpPut("{id}")]
public async Task<IActionResult> PutTodoItem(long id, TodoItem todoItem)
{
    if (id != todoItem.Id)
    {
        return BadRequest();
    }

    _context.Entry(todoItem).State = EntityState.Modified;

    try
    {
        await _context.SaveChangesAsync();
    }
    catch (DbUpdateConcurrencyException)
    {
        if (!TodoItemExists(id))
        {
            return NotFound();
        }
        else
        {
            throw;
        }
    }

    return NoContent();
}

PutTodoItem jest podobny do PostTodoItem, z wyjątkiem tego, że używa HTTP PUT. Odpowiedź to 204 (brak zawartości). Zgodnie ze specyfikacją PUT PROTOKOŁU HTTP żądanie wymaga od klienta wysłania całej zaktualizowanej jednostki, a nie tylko zmian. Aby obsługiwać aktualizacje częściowe, użyj poprawki HTTP PATCH.

Testowanie metody PutTodoItem

W tym przykładzie użyto bazy danych w pamięci, która musi zostać zainicjowana przy każdym uruchomieniu aplikacji. Przed wykonaniem wywołania PUT musi istnieć element w bazie danych. Wywołaj metodę GET, aby upewnić się, że istnieje element w bazie danych przed wykonaniem wywołania PUT.

Użyj metody PUT, aby zaktualizować TodoItem o identyfikatorze = 1 i ustawić jej nazwę na "feed fish". Zwróć uwagę, że odpowiedź to HTTP 204 No Content.

Visual Studio

• W Eksploratorze punktów końcowych kliknij prawym przyciskiem myszy punkt końcowy PUT i wybierz pozycję Generuj żądanie.

  Do pliku zostanie dodana następująca TodoApi.http zawartość:

  PUT {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  Content-Type: application/json
  
  {
    //TodoItem
  }
  
  ###
  

• W wierszu żądania PUT zastąp ciąg {{id}} ciągiem 1.

• Zastąp symbol zastępczy //TodoItem następującymi wierszami:

  PUT {{TodoApi_HostAddress}}/api/todoitems/1
  Content-Type: application/json
  
  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }
  

• Wybierz link Wyślij żądanie powyżej nowego wiersza żądania PUT.

  Żądanie PUT jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedź . Treść odpowiedzi jest pusta, a kod stanu to 204.

Visual Studio Code

Użyj Swagger, aby wysłać żądanie PUT.

• Wybierz pozycję Umieść /api/todoitems/{id}>Wypróbuj.

• Ustaw pole id na 1.

• Ustaw treść żądania na następujący kod JSON:

  {
    "id": 1,
    "name": "feed fish",
    "isComplete": false
  }
  

• Wybierz i wykonaj.

Metoda DeleteTodoItem

Przeanalizuj metodę DeleteTodoItem:

[HttpDelete("{id}")]
public async Task<IActionResult> DeleteTodoItem(long id)
{
    var todoItem = await _context.TodoItems.FindAsync(id);
    if (todoItem == null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(todoItem);
    await _context.SaveChangesAsync();

    return NoContent();
}

Testowanie metody DeleteTodoItem

Użyj metody DELETE, aby usunąć TodoItem o identyfikatorze = 1. Zwróć uwagę, że odpowiedź to HTTP 204 No Content.

Visual Studio

• W Eksploratorze punktów końcowych kliknij prawym przyciskiem myszy punkt końcowy DELETE i wybierz pozycję Generuj żądanie.

  Żądanie DELETE jest dodawane do TodoApi.http.

• Zastąp {{id}} w wierszu żądania DELETE na 1. Żądanie DELETE powinno wyglądać podobnie do następującego przykładu:

  DELETE {{TodoApi_HostAddress}}/api/todoitems/{{id}}
  
  ###
  

• Wybierz link Wyślij żądanie dla żądania DELETE.

  Żądanie DELETE jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedź . Treść odpowiedzi jest pusta, a kod stanu to 204.

Visual Studio Code

Użyj narzędzia Swagger, aby wysłać żądanie DELETE:

• Wybierz pozycję DELETE /api/todoitems/{id}>Wypróbuj.

• Ustaw pole ID na 1 i wybierz pozycję Wykonaj.

  Żądanie DELETE jest wysyłane do aplikacji, a odpowiedź jest wyświetlana w okienku Odpowiedzi . Treść odpowiedzi jest pusta, a kod stanu odpowiedzi serwera to 204.

Testowanie za pomocą innych narzędzi

Istnieje wiele innych narzędzi, których można użyć do testowania internetowych interfejsów API, na przykład:

• http-repl
• curl. Narzędzie Swagger używa curl i pokazuje curl polecenia, które przesyła.
• Fiddler

Aby uzyskać więcej informacji, zobacz:

• Instalowanie i testowanie interfejsów API za pomocą polecenia http-repl

Zapobieganie nadmiernemu publikowaniu

Obecnie przykładowa aplikacja uwidacznia cały TodoItem obiekt. Aplikacje produkcyjne zwykle ograniczają dane wejściowe i zwracane przy użyciu podzestawu modelu. Istnieje wiele powodów, a bezpieczeństwo jest jednym z głównych. Podzbiór modelu jest zwykle nazywany obiektem transferu danych (DTO), modelem wejściowym lub modelem widoku. DTO jest używany w tym samouczku.

DTO może służyć do:

• Zapobiegaj nadmiernemu publikowaniu.
• Ukryj właściwości, których klienci nie powinni wyświetlać.
• Pomiń niektóre właściwości, aby zmniejszyć rozmiar ładunku.
• Spłaszczaj grafy obiektów zawierających zagnieżdżone obiekty. Spłaszczone grafy obiektów mogą być wygodniejsze dla klientów.

Aby zademonstrować podejście DTO, zaktualizuj klasę TodoItem tak, aby zawierała pole tajne.

namespace TodoApi.Models;

public class TodoItem
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
    public string? Secret { get; set; }
}

Pole tajne musi być ukryte w tej aplikacji, ale aplikacja administracyjna może je uwidocznić.

Sprawdź, czy możesz opublikować i uzyskać pole tajne.

Utwórz model DTO w pliku Models/TodoItemsDTO.cs:

namespace TodoApi.Models;

public class TodoItemDTO
{
    public long Id { get; set; }
    public string? Name { get; set; }
    public bool IsComplete { get; set; }
}

Zaktualizuj TodoItemsController tak, aby używał TodoItemDTO.

using Microsoft.AspNetCore.Mvc;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi.Controllers;

[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
{
    private readonly TodoContext _context;

    public TodoItemsController(TodoContext context)
    {
        _context = context;
    }

    // GET: api/TodoItems
    [HttpGet]
    public async Task<ActionResult<IEnumerable<TodoItemDTO>>> GetTodoItems()
    {
        return await _context.TodoItems
            .Select(x => ItemToDTO(x))
            .ToListAsync();
    }

    // GET: api/TodoItems/5
    // <snippet_GetByID>
    [HttpGet("{id}")]
    public async Task<ActionResult<TodoItemDTO>> GetTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);

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

        return ItemToDTO(todoItem);
    }
    // </snippet_GetByID>

    // PUT: api/TodoItems/5
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Update>
    [HttpPut("{id}")]
    public async Task<IActionResult> PutTodoItem(long id, TodoItemDTO todoDTO)
    {
        if (id != todoDTO.Id)
        {
            return BadRequest();
        }

        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        todoItem.Name = todoDTO.Name;
        todoItem.IsComplete = todoDTO.IsComplete;

        try
        {
            await _context.SaveChangesAsync();
        }
        catch (DbUpdateConcurrencyException) when (!TodoItemExists(id))
        {
            return NotFound();
        }

        return NoContent();
    }
    // </snippet_Update>

    // POST: api/TodoItems
    // To protect from overposting attacks, see https://go.microsoft.com/fwlink/?linkid=2123754
    // <snippet_Create>
    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> PostTodoItem(TodoItemDTO todoDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoDTO.IsComplete,
            Name = todoDTO.Name
        };

        _context.TodoItems.Add(todoItem);
        await _context.SaveChangesAsync();

        return CreatedAtAction(
            nameof(GetTodoItem),
            new { id = todoItem.Id },
            ItemToDTO(todoItem));
    }
    // </snippet_Create>

    // DELETE: api/TodoItems/5
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteTodoItem(long id)
    {
        var todoItem = await _context.TodoItems.FindAsync(id);
        if (todoItem == null)
        {
            return NotFound();
        }

        _context.TodoItems.Remove(todoItem);
        await _context.SaveChangesAsync();

        return NoContent();
    }

    private bool TodoItemExists(long id)
    {
        return _context.TodoItems.Any(e => e.Id == id);
    }

    private static TodoItemDTO ItemToDTO(TodoItem todoItem) =>
       new TodoItemDTO
       {
           Id = todoItem.Id,
           Name = todoItem.Name,
           IsComplete = todoItem.IsComplete
       };
}

Sprawdź, czy nie możesz publikować ani uzyskiwać dostępu do pola tajnego.

Wywoływanie internetowego interfejsu API za pomocą języka JavaScript

Zobacz Samouczek: wywoływanie internetowego interfejsu API platformy ASP.NET Core przy użyciu języka JavaScript.

Cykl filmów o webowym API

Zobacz Wideo: Seria dla początkujących dotycząca: Web APIs.

Wzorce aplikacji internetowej dla przedsiębiorstw

Aby uzyskać wskazówki dotyczące tworzenia niezawodnej, bezpiecznej, wydajnej, testowalnej i skalowalnej aplikacji ASP.NET Core, zobacz wzorce aplikacji internetowych Enterprise. Dostępna jest kompletna przykładowa aplikacja internetowa jakości produkcyjnej, która implementuje wzorce.

Dodawanie obsługi uwierzytelniania do internetowego interfejsu API

ASP.NET Core Identity dodaje funkcjonalność logowania w interfejsie użytkownika (UI) do aplikacji internetowych ASP.NET Core. Aby zabezpieczyć internetowe interfejsy API i SPA, użyj jednego z następujących elementów.

• Microsoft Entra ID
• Azure Active Directory B2C (Azure AD B2C )
• Serwer Duende Identity

Duende Identity Server to platforma OpenID Connect i OAuth 2.0 dla platformy ASP.NET Core. Serwer Duende Identity umożliwia korzystanie z następujących funkcji zabezpieczeń:

• Uwierzytelnianie jako usługa (AaaS)
• Logowanie jednokrotne/wyłączanie logowania jednokrotnego w wielu typach aplikacji
• Kontrola dostępu dla interfejsów API
• Brama federacyjna

Ważne

Oprogramowanie Duende może wymagać zapłacenia opłaty licencyjnej za korzystanie z serwera Duende Identity Server w środowisku produkcyjnym. Aby uzyskać więcej informacji, zobacz Migracja z platformy ASP.NET Core w wersji 5.0 do wersji 6.0.

Aby uzyskać więcej informacji, zobacz dokumentację serwera Duende (witryna internetowa Duende Identity Software).

Publikowanie na platformie Azure

Aby uzyskać informacje na temat wdrażania na platformie Azure, zobacz Szybki start: wdrażanie aplikacji internetowej ASP.NET.

Dodatkowe zasoby

Wyświetl lub pobierz przykładowy kod dla tego samouczka. Zobacz , jak pobrać.

Aby uzyskać więcej informacji, zobacz następujące zasoby:

• Tworzenie internetowych interfejsów API za pomocą platformy ASP.NET Core
• Samouczek: tworzenie minimalnego interfejsu API przy użyciu platformy ASP.NET Core
• Korzystanie z wygenerowanych dokumentów OpenAPI
• Dokumentacja webowego API ASP.NET Core z użyciem Swagger / OpenAPI
• Razor Strony przy użyciu Entity Framework Core w ASP.NET Core — samouczek 1 z 8
• Routing do akcji kontrolera na platformie ASP.NET Core
• Zwracane typy akcji kontrolera w internetowym interfejsie API platformy ASP.NET Core
• Wdrażanie aplikacji ASP.NET Core w usłudze Azure App Service
• Hostowanie i wdrażanie ASP.NET Core
• Tworzenie internetowego interfejsu API przy użyciu platformy ASP.NET Core