Kurz: Vytvoření webového rozhraní API pomocí ASP.NET Core

Autor : Rick Anderson a Kirk Larkin

V tomto kurzu se naučíte základy vytváření webového rozhraní API pomocí ASP.NET Core.

V tomto kurzu se naučíte:

  • Vytvořte projekt webového rozhraní API.
  • Přidejte třídu modelu a kontext databáze.
  • Generování kontroleru pomocí metod CRUD
  • Nakonfigurujte směrování, cesty URL a návratové hodnoty.
  • Volání webového rozhraní API pomocí Nástroje Postman

Na konci máte webové rozhraní API, které může spravovat položky úkolů uložené v databázi.

Přehled

Tento kurz vytvoří následující rozhraní API:

Rozhraní API Popis Text požadavku Text odpovědi
GET /api/todoitems Získání všech položek úkolů Žádné Pole položek úkolů
GET /api/todoitems/{id} Získání položky podle ID Žádné Položka úkolu
POST /api/todoitems Přidání nové položky Položka úkolu Položka úkolu
PUT /api/todoitems/{id} Aktualizace existující položky Položka úkolu Žádné
DELETE /api/todoitems/{id}     Odstranění položky Žádné Žádné

Následující diagram znázorňuje návrh aplikace.

The client is represented by a box on the left. It submits a request and receives a response from the application, a box drawn on the right. Within the application box, three boxes represent the controller, the model, and the data access layer. The request comes into the application's controller, and read/write operations occur between the controller and the data access layer. The model is serialized and returned to the client in the response.

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový>Project.
  • Do vyhledávacího pole zadejte webové rozhraní API .
  • Vyberte šablonu webového rozhraní API ASP.NET Core a vyberte Další.
  • V dialogovém okně Konfigurovat nový projekt pojmenujte projekt TodoApi a vyberte Další.
  • V dialogovém okně Další informace :
    • Ověřte, že je rozhraní.NET 6.0 (dlouhodobá podpora).
    • Ověřte, že je zaškrtnuté políčko Použít kontrolery (zrušte zaškrtnutí políčka používat minimální rozhraní API ).
    • Vyberte Vytvořit.

Poznámka

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích o instalaci a správě balíčků v pracovním postupu používání balíčků (NuGet dokumentaci). Potvrďte správné verze balíčků na adrese NuGet.org.

Testování projektu

Šablona projektu vytvoří WeatherForecast rozhraní API s podporou Swaggeru.

Stisknutím kombinace kláves Ctrl+F5 spusťte ladicí program.

Visual Studio zobrazí následující dialogové okno, pokud projekt ještě není nakonfigurovaný tak, aby používal protokol SSL:

This project is configured to use SSL. To avoid SSL warnings in the browser you can choose to trust the self-signed certificate that IIS Express has generated. Would you like to trust the IIS Express SSL certificate?

Pokud důvěřujete certifikátu IIS Express SSL, vyberte Ano.

Zobrazí se následující dialogové okno:

Security warning dialog

Pokud souhlasíte s důvěryhodností vývojového certifikátu, vyberte Ano .

Informace o důvěryhodnosti prohlížeče Firefox najdete v článku o chybě certifikátu aplikace Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Visual Studio spustí výchozí prohlížeč a přejde na https://localhost:<port>/swagger/index.html, kde <port> je náhodně zvolené číslo portu.

Zobrazí se stránka /swagger/index.html Swagger. Vyberte GETTry>itoutExecute>. Zobrazí se stránka:

  • Příkaz Curl k otestování rozhraní API WeatherForecast.
  • Adresa URL pro testování rozhraní API WeatherForecast.
  • Kód odpovědi, text a hlavičky.
  • Rozevírací seznam s typy médií a ukázkovou hodnotou a schématem

Pokud se stránka Swagger nezobrazí, podívejte se na tento GitHub problém.

Swagger se používá ke generování užitečné dokumentace a stránek nápovědy pro webová rozhraní API. Tento kurz se zaměřuje na vytvoření webového rozhraní API. Další informace o Swaggeru najdete v ASP.NET Core dokumentaci k webovému rozhraní API pomocí Swaggeru / OpenAPI.

Zkopírujte a vložte adresu URL požadavku v prohlížeči: https://localhost:<port>/weatherforecast

Vrátí se JSON podobný následujícímu příkladu:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Aktualizace launchUrl

In Properties\launchSettings.json, update launchUrl from to "api/todoitems""swagger" :

"launchUrl": "api/todoitems",

Vzhledem k tomu, že Swagger se odebere, předchozí revize změní adresu URL, která je spuštěna na metodu GET kontroleru přidaného v následujících částech.

Přidání třídy modelu

Model je sada tříd, které představují data, která aplikace spravuje. Model pro tuto aplikaci je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem myši na projekt. Vyberte Přidat>novou složku. Pojmenujte složku Models.

  • Klikněte pravým tlačítkem na Models složku a vyberte AddClass>. Pojmenujte třídu TodoItem a vyberte Přidat.

  • Nahraďte kód šablony následujícím kódem:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

Vlastnost Id funguje jako jedinečný klíč v relační databázi.

Třídy modelů můžou přejít kdekoli v projektu, ale Models složka se používá konvencí.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je vytvořena odvozením z Microsoft.EntityFrameworkCore.DbContext třídy.

Přidání balíčků NuGet

  • V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat balíčky NuGet pro řešení.
  • Vyberte kartu Procházet a zadejte Microsoft.EntityFrameworkCore.InMemory do vyhledávacího pole.
  • Vyberte Microsoft.EntityFrameworkCore.InMemory v levém podokně.
  • Zaškrtněte políčko Project v pravém podokně a pak vyberte Nainstalovat.

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem na Models složku a vyberte AddClass>. Pojmenujte třídu TodoContext a klikněte na Přidat.
  • Zadejte následující kód:

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

Registrace kontextu databáze

V ASP.NET Core musí být služby, jako je kontext databáze, zaregistrované v kontejneru injektáže závislostí (DI). Kontejner poskytuje kontrolerům službu.

Aktualizujte Program.cs následujícím kódem:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;


var builder = WebApplication.CreateBuilder(args);

// Add services to the container.

builder.Services.AddControllers();
builder.Services.AddDbContext<TodoContext>(opt =>
    opt.UseInMemoryDatabase("TodoList"));
//builder.Services.AddSwaggerGen(c =>
//{
//    c.SwaggerDoc("v1", new() { Title = "TodoApi", Version = "v1" });
//});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (builder.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
    //app.UseSwagger();
    //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Předchozí kód:

  • Odebere volání Swaggeru.
  • Odebere nepoužívané using direktivy.
  • Přidá kontext databáze do kontejneru DI.
  • Určuje, že kontext databáze bude používat databázi v paměti.

Generování řídicího prvku

  • Klikněte pravým tlačítkem myši na složku Kontrolery .

  • Vyberte Přidat>novou vygenerovanou položku.

  • Vyberte kontroler rozhraní API s akcemi, pomocí Entity Frameworku a pak vyberte Přidat.

  • V dialogovém okně Přidat kontroler rozhraní API s akcemi pomocí entity Framework :

    • Vyberte TodoItem (TodoApi.Models) ve třídě Modelu.
    • Ve třídě kontextu dat vyberte TodoContext (TodoApi.Models).
    • Vyberte Přidat.

    Pokud operace generování uživatelského rozhraní selže, vyberte Přidat a zkuste znovu vygenerovat generování.

Vygenerovaný kód:

  • Označí třídu atributem [ApiController] . Tento atribut označuje, že kontroler reaguje na požadavky webového rozhraní API. Informace o konkrétním chování, které atribut povolí, najdete v tématu Vytváření webových rozhraní API s ASP.NET Core.
  • Používá di k vložení kontextu databáze (TodoContext) do kontroleru. Kontext databáze se používá v každé z metod CRUD v kontroleru.

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními patří [action] do šablony trasy.
  • Kontrolery rozhraní API nezahrnují [action] do šablony tras.

[action] Pokud token není v šabloně trasy, název akce je z trasy vyloučený. To znamená, že název přidružené metody akce se v odpovídající trase nepoužívá.

Aktualizace metody Vytvoření PostTodoItem

Aktualizujte příkaz return v operátoru PostTodoItemnameof :

[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);
}

Předchozí kód je metoda HTTP POST, jak je uvedeno atributem [HttpPost] . Metoda získá hodnotu položky úkolu z textu požadavku HTTP.

Další informace najdete v tématu Směrování atributů s atributy Http[Sloves].

Metoda CreatedAtAction :

  • Vrátí stavový kód HTTP 201 , pokud je úspěšný. HTTP 201 je standardní odpověď pro metodu HTTP POST, která na serveru vytvoří nový prostředek.
  • Přidá do odpovědi hlavičku Umístění . Hlavička Location určuje identifikátor URI nově vytvořené položky úkolů. Další informace najdete v tématu 10.2.2 201 Vytvořeno.
  • Odkazuje na GetTodoItem akci a vytvoří Location identifikátor URI záhlaví. Klíčové slovo jazyka C# nameof se používá k tomu, aby se zabránilo pevnému CreatedAtAction kódování názvu akce ve volání.

Instalace http-repl

V tomto kurzu se k otestování webového rozhraní API používá http-repl .

  • Na příkazovém řádku spusťte následující příkaz:

    dotnet tool install -g Microsoft.dotnet-httprepl
    
  • Pokud nemáte nainstalovanou sadu .NET 6.0 SDK nebo modul runtime, nainstalujte modul runtime .NET 6.0.

Test PostTodoItem

  • Aplikaci spustíte stisknutím kombinace kláves Ctrl+F5.

  • Otevřete nové okno terminálu a spusťte následující příkazy. Pokud vaše aplikace používá jiné číslo portu, nahraďte 5001 v příkazu httprepl číslem portu.

    httprepl https://localhost:5001/api/todoitems
    post -h Content-Type=application/json -c "{"name":"walk dog","isComplete":true}"
    

    Tady je příklad výstupu tohoto příkazu:

    HTTP/1.1 201 Created
    Content-Type: application/json; charset=utf-8
    Date: Tue, 07 Sep 2021 20:39:47 GMT
    Location: https://localhost:5001/api/TodoItems/1
    Server: Kestrel
    Transfer-Encoding: chunked
    
    {
      "id": 1,
      "name": "walk dog",
      "isComplete": true
    }
    

Otestování identifikátoru URI záhlaví umístění

Pokud chcete otestovat záhlaví umístění, zkopírujte ho a vložte ho do příkazu httprepl get .

Následující příklad předpokládá, že jste stále v relaci httprepl. Pokud jste ukončili předchozí relaci httprepl, nahraďte connecthttprepl ji následujícími příkazy:

connect https://localhost:5001/api/todoitems/1
get

Tady je příklad výstupu tohoto příkazu:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:48:10 GMT
Server: Kestrel
Transfer-Encoding: chunked

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

Prozkoumání metod GET

Implementují se dva koncové body GET:

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

Právě jste viděli příklad /api/todoitems/{id} trasy. Otestujte trasu /api/todoitems :

connect https://localhost:5001/api/todoitems
get

Tady je příklad výstupu tohoto příkazu:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: Tue, 07 Sep 2021 20:59:21 GMT
Server: Kestrel
Transfer-Encoding: chunked

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

Vrácený kód JSON je tentokrát pole jedné položky.

Tato aplikace používá databázi v paměti. Pokud je aplikace zastavená a spuštěná, předchozí požadavek GET nevrátí žádná data. Pokud se nevrátí žádná data, data POST do aplikace.

Směrování a cesty url

Atribut [HttpGet] označuje metodu, která reaguje na požadavek HTTP GET. Cesta URL pro každou metodu je vytvořena takto:

  • Začněte řetězcem šablony v atributu kontroleru Route :

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    
  • Nahraďte [controller] názvem kontroleru, který konvencí je název třídy kontroleru minus přípona Controller. Pro tuto ukázku je název třídy kontroleru TodoItemsController, takže název kontroleru je TodoItems. ASP.NET Core směrování je nerozlišující malá a velká písmena.

  • Pokud má [HttpGet] atribut šablonu trasy (například), [HttpGet("products")]připojte ji k cestě. Tato ukázka nepoužívá šablonu. Další informace najdete v tématu Směrování atributů s atributy Http[Sloves].

V následující GetTodoItem metodě "{id}" je zástupná proměnná pro jedinečný identifikátor položky úkolu. Při GetTodoItem vyvolání se hodnota "{id}" v adrese URL poskytne metodě v jeho id parametru.

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

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

    return todoItem;
}

Vrácené hodnoty

Návratový GetTodoItems typ a GetTodoItem metody je Typ ActionResultT<>. ASP.NET Core objekt automaticky serializuje do formátu JSON a zapíše json do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OK, za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

ActionResult návratové typy můžou představovat širokou škálu stavových kódů HTTP. Může například GetTodoItem vrátit dvě různé hodnoty stavu:

  • Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby stavu NotFound404.
  • Jinak metoda vrátí hodnotu 200 s textem odpovědi JSON. item Vrácení výsledků v odpovědi HTTP 200

Metoda PutTodoItem

Prohlédněte si metodu 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 je podobná PostTodoItem, s výjimkou použití HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte http PATCH.

Pokud se v následující části zobrazí PutTodoItem chyba, zavolejte GET , abyste měli jistotu, že je v databázi položka.

Testování metody PutTodoItem

Tato ukázka používá databázi v paměti, která se musí inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Zavolejte GET, abyste se ujistili, že je v databázi položka před voláním PUT.

Aktualizujte položku úkolu s ID = 1 a nastavte jeho název na "feed fish":

connect https://localhost:5001/api/todoitems/1
put -h Content-Type=application/json -c "{"id":1,"name":"feed fish","isComplete":true}"

Tady je příklad výstupu tohoto příkazu:

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:20:47 GMT
Server: Kestrel

Metoda DeleteTodoItem

Prohlédněte si metodu 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();
}

Testování metody DeleteTodoItem

Odstraňte položku úkolu s ID = 1:

connect https://localhost:5001/api/todoitems/1
delete

Tady je příklad výstupu tohoto příkazu:

HTTP/1.1 204 No Content
Date: Tue, 07 Sep 2021 21:43:00 GMT
Server: Kestrel

Zabránit nadměrnému účtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní data a vrácená pomocí podmnožině modelu. Za tímto důvodem je několik důvodů a zabezpečení je hlavní. Podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto kurzu.

DTO lze použít k:

  • Zabránit nadměrnému účtování.
  • Skrýt vlastnosti, které klienti nemají zobrazit.
  • Pokud chcete zmenšit velikost datové části, vynecháte některé vlastnosti.
  • Zploštěné grafy objektů, které obsahují vnořené objekty. Grafy zploštěných objektů můžou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby obsahovala tajné pole:

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; }
    }
}

Tajné pole musí být skryté z této aplikace, ale aplikace pro správu by se mohla rozhodnout ji zpřístupnit.

Ověřte, že můžete publikovat a získat tajné pole.

Vytvoření modelu DTO:

namespace TodoApi.Models
{
    public class TodoItemDTO
    {
        public long Id { get; set; }
        public string? Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

Aktualizujte, aby se používalTodoItemDTO:TodoItemsController

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

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

            todoItem.Name = todoItemDTO.Name;
            todoItem.IsComplete = todoItemDTO.IsComplete;

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

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

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

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

        // 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
            };
    }
}

Ověřte, že nemůžete publikovat nebo získat tajné pole.

Volání webového rozhraní API pomocí JavaScriptu

Viz kurz: Volání webového rozhraní API ASP.NET Core pomocí JavaScriptu

V tomto kurzu se naučíte:

  • Vytvořte projekt webového rozhraní API.
  • Přidejte třídu modelu a kontext databáze.
  • Generování řídicího prvku pomocí metod CRUD
  • Nakonfigurujte směrování, cesty url a návratové hodnoty.
  • Volání webového rozhraní API pomocí nástroje Postman

Na konci máte webové rozhraní API, které může spravovat položky úkolů uložené v databázi.

Přehled

Tento kurz vytvoří následující rozhraní API:

Rozhraní API Popis Text požadavku Text odpovědi
GET /api/todoitems Získání všech položek úkolů Žádné Pole položek úkolů
GET /api/todoitems/{id} Získání položky podle ID Žádné Položka úkolu
POST /api/todoitems Přidání nové položky Položka úkolu Položka úkolu
PUT /api/todoitems/{id} Aktualizace existující položky Položka úkolu Žádné
DELETE /api/todoitems/{id}     Odstranění položky Žádné Žádné

Následující diagram znázorňuje návrh aplikace.

The client is represented by a box on the left. It submits a request and receives a response from the application, a box drawn on the right. Within the application box, three boxes represent the controller, the model, and the data access layer. The request comes into the application's controller, and read/write operations occur between the controller and the data access layer. The model is serialized and returned to the client in the response.

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový>Project.
  • Vyberte šablonu webového rozhraní API ASP.NET Core a klikněte na Tlačítko Další.
  • Pojmenujte projekt TodoApi a klikněte na Vytvořit.
  • V dialogovém okně Vytvořit novou ASP.NET Core webovou aplikaci potvrďte, že jsou vybrány .NET Core a ASP.NET Core 5.0. Vyberte šablonu rozhraní API a klikněte na Vytvořit.

VS new project dialog

Poznámka

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích o instalaci a správě balíčků v pracovním postupu používání balíčků (NuGet dokumentaci). Potvrďte správné verze balíčků na adrese NuGet.org.

Testování projektu

Šablona projektu vytvoří WeatherForecast rozhraní API s podporou Swaggeru.

Stisknutím kombinace kláves Ctrl+F5 spusťte ladicí program.

Visual Studio zobrazí následující dialogové okno, pokud projekt ještě není nakonfigurovaný tak, aby používal protokol SSL:

This project is configured to use SSL. To avoid SSL warnings in the browser you can choose to trust the self-signed certificate that IIS Express has generated. Would you like to trust the IIS Express SSL certificate?

Pokud důvěřujete certifikátu IIS Express SSL, vyberte Ano.

Zobrazí se následující dialogové okno:

Security warning dialog

Pokud souhlasíte s důvěryhodností vývojového certifikátu, vyberte Ano .

Informace o důvěryhodnosti prohlížeče Firefox najdete v článku o chybě certifikátu aplikace Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Visual Studio se spustí:

  • Webový server IIS Express.
  • Výchozí prohlížeč a přejde na https://localhost:<port>/swagger/index.html, kde <port> je náhodně zvolené číslo portu.

Zobrazí se stránka /swagger/index.html Swagger. Vyberte GETTry>itoutExecute>. Zobrazí se stránka:

  • Příkaz Curl k otestování rozhraní API WeatherForecast
  • Adresa URL pro otestování rozhraní API WeatherForecast
  • Kód odpovědi, text a hlavičky.
  • Rozevírací seznam s typy médií a ukázkovou hodnotou a schématem

Pokud se stránka Swagger nezobrazí, podívejte se na tento GitHub problém.

Swagger se používá ke generování užitečné dokumentace a stránek nápovědy pro webová rozhraní API. Tento kurz se zaměřuje na vytvoření webového rozhraní API. Další informace o Swaggeru najdete v ASP.NET Core dokumentaci k webovému rozhraní API pomocí Swaggeru / OpenAPI.

Zkopírujte a vložte adresu URL požadavku v prohlížeči: https://localhost:<port>/weatherforecast

Vrátí se json podobný následujícímu:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Aktualizace launchUrl

In Properties\launchSettings.json, update launchUrl from to "api/todoitems""swagger" :

"launchUrl": "api/todoitems",

Vzhledem k tomu, že Swagger se odebere, předchozí revize změní adresu URL, která je spuštěna na metodu GET kontroleru přidaného v následujících částech.

Přidání třídy modelu

Model je sada tříd, které představují data, která aplikace spravuje. Model pro tuto aplikaci je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem myši na projekt. Vyberte Přidat>novou složku. Pojmenujte složku Models.

  • Klikněte pravým tlačítkem na Models složku a vyberte AddClass>. Pojmenujte třídu TodoItem a vyberte Přidat.

  • Nahraďte kód šablony následujícím kódem:

namespace TodoApi.Models
{
    public class TodoItem
    {
        public long Id { get; set; }
        public string Name { get; set; }
        public bool IsComplete { get; set; }
    }
}

Vlastnost Id funguje jako jedinečný klíč v relační databázi.

Třídy modelů můžou přejít kdekoli v projektu, ale Models složka se používá konvencí.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je vytvořena odvozením z Microsoft.EntityFrameworkCore.DbContext třídy.

Přidání balíčků NuGet

  • V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat balíčky NuGet pro řešení.
  • Vyberte kartu Procházet a zadejte Microsoft.EntityFrameworkCore.InMemory do vyhledávacího pole.
  • Vyberte Microsoft.EntityFrameworkCore.InMemory v levém podokně.
  • Zaškrtněte políčko Project v pravém podokně a pak vyberte Nainstalovat.

NuGet Package Manager

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem na Models složku a vyberte AddClass>. Pojmenujte třídu TodoContext a klikněte na Přidat.
  • Zadejte následující kód:

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

Registrace kontextu databáze

V ASP.NET Core musí být služby, jako je kontext databáze, zaregistrované v kontejneru injektáže závislostí (DI). Kontejner poskytuje kontrolerům službu.

Aktualizujte Startup.cs následujícím kódem:

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();

            services.AddDbContext<TodoContext>(opt =>
                                               opt.UseInMemoryDatabase("TodoList"));
            //services.AddSwaggerGen(c =>
            //{
            //    c.SwaggerDoc("v1", new OpenApiInfo { Title = "TodoApi", Version = "v1" });
            //});
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
                //app.UseSwagger();
                //app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "TodoApi v1"));
            }

            app.UseHttpsRedirection();
            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Předchozí kód:

  • Odebere volání Swaggeru.
  • Odebere nepoužívané using deklarace.
  • Přidá kontext databáze do kontejneru DI.
  • Určuje, že kontext databáze bude používat databázi v paměti.

Generování řídicího prvku

  • Klikněte pravým tlačítkem myši na složku Kontrolery .

  • Vyberte Přidat>novou vygenerovanou položku.

  • Vyberte kontroler rozhraní API s akcemi, pomocí Entity Frameworku a pak vyberte Přidat.

  • V dialogovém okně Přidat kontroler rozhraní API s akcemi pomocí entity Framework :

    • Vyberte TodoItem (TodoApi.Models) ve třídě Modelu.
    • Ve třídě kontextu dat vyberte TodoContext (TodoApi.Models).
    • Vyberte Přidat.

Vygenerovaný kód:

  • Označí třídu atributem [ApiController] . Tento atribut označuje, že kontroler reaguje na požadavky webového rozhraní API. Informace o konkrétním chování, které atribut povolí, najdete v tématu Vytváření webových rozhraní API s ASP.NET Core.
  • Používá di k vložení kontextu databáze (TodoContext) do kontroleru. Kontext databáze se používá v každé z metod CRUD v kontroleru.

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními patří [action] do šablony trasy.
  • Kontrolery rozhraní API nezahrnují [action] do šablony tras.

[action] Pokud token není v šabloně trasy, název akce je z trasy vyloučený. To znamená, že název přidružené metody akce se v odpovídající trase nepoužívá.

Aktualizace metody Vytvoření PostTodoItem

Aktualizujte příkaz return v operátoru PostTodoItemnameof :

// POST: api/TodoItems
[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);
}

Předchozí kód je metoda HTTP POST, jak je uvedeno atributem [HttpPost] . Metoda získá hodnotu položky úkolu z textu požadavku HTTP.

Další informace najdete v tématu Směrování atributů s atributy Http[Sloves].

Metoda CreatedAtAction :

  • Vrátí stavový kód HTTP 201 , pokud je úspěšný. HTTP 201 je standardní odpověď pro metodu HTTP POST, která na serveru vytvoří nový prostředek.
  • Přidá do odpovědi hlavičku Umístění . Hlavička Location určuje identifikátor URI nově vytvořené položky úkolů. Další informace najdete v tématu 10.2.2 201 Vytvořeno.
  • Odkazuje na GetTodoItem akci a vytvoří Location identifikátor URI záhlaví. Klíčové slovo jazyka C# nameof se používá k tomu, aby se zabránilo pevnému CreatedAtAction kódování názvu akce ve volání.

Instalace nástroje Postman

Tento kurz používá Postman k otestování webového rozhraní API.

  • Instalace nástroje Postman
  • Spusťte webovou aplikaci.
  • Spusťte Postman.
  • Zakázání ověření certifikátu SSL:
    • Postman pro Windows: Vyberte soubor>Nastavení (karta Obecné), zakažte ověření certifikátu SSL.
    • Postman pro macOS: Vyberte Postman>Nastavení (karta Obecné), zakažte ověření certifikátu SSL.

      Upozornění

      Po otestování kontroleru znovu povolte ověření certifikátu SSL.

Testování PostTodoItem pomocí Nástroje Postman

  • Vytvořte novou žádost.

  • Nastavte metodu HTTP na POST.

  • Nastavte identifikátor URI na https://localhost:<port>/api/todoitems. Například, https://localhost:5001/api/todoitems.

  • Vyberte kartu Text .

  • Vyberte nezpracované přepínač.

  • Nastavte typ na JSON (application/json).

  • Do textu požadavku zadejte JSON pro položku úkolů:

    {
      "name":"walk dog",
      "isComplete":true
    }
    
  • Vyberte Odeslat.

    Postman with create request

Otestování identifikátoru URI záhlaví umístění

Identifikátor URI záhlaví umístění je možné otestovat v prohlížeči. Zkopírujte a vložte identifikátor URI záhlaví umístění do prohlížeče.

Testování v Nástroji Postman:

  • V podokně Odpovědi vyberte kartu Záhlaví.

  • Zkopírujte hodnotu záhlaví umístění :

    Headers tab of the Postman console

  • Nastavte metodu HTTP na GET.

  • Nastavte identifikátor URI na https://localhost:<port>/api/todoitems/1. Například, https://localhost:5001/api/todoitems/1.

  • Vyberte Odeslat.

Prozkoumání metod GET

Implementují se dva koncové body GET:

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

Otestujte aplikaci voláním dvou koncových bodů z prohlížeče nebo Postmanu. Příklad:

  • https://localhost:5001/api/todoitems
  • https://localhost:5001/api/todoitems/1

Voláním se vytvoří GetTodoItemsodpověď podobná následující:

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

Test Get with Postman

  • Vytvořte novou žádost.
  • Nastavte metodu HTTP na GET.
  • Nastavte identifikátor URI požadavku na https://localhost:<port>/api/todoitems. Například, https://localhost:5001/api/todoitems.
  • Nastavení dvou zobrazení podokna v Nástroji Postman
  • Vyberte Odeslat.

Tato aplikace používá databázi v paměti. Pokud je aplikace zastavená a spuštěná, předchozí požadavek GET nevrátí žádná data. Pokud se nevrátí žádná data, data POST do aplikace.

Směrování a cesty url

Atribut [HttpGet] označuje metodu, která reaguje na požadavek HTTP GET. Cesta URL pro každou metodu je vytvořena takto:

  • Začněte řetězcem šablony v atributu kontroleru Route :

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;
    
        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }
    
  • Nahraďte [controller] názvem kontroleru, který konvencí je název třídy kontroleru minus přípona Controller. Pro tuto ukázku je název třídy kontroleru TodoItemsController, takže název kontroleru je TodoItems. ASP.NET Core směrování je nerozlišující malá a velká písmena.

  • Pokud má [HttpGet] atribut šablonu trasy (například), [HttpGet("products")]připojte ji k cestě. Tato ukázka nepoužívá šablonu. Další informace najdete v tématu Směrování atributů s atributy Http[Sloves].

V následující GetTodoItem metodě "{id}" je zástupná proměnná pro jedinečný identifikátor položky úkolu. Při GetTodoItem vyvolání se hodnota "{id}" v adrese URL poskytne metodě v jeho id parametru.

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

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

    return todoItem;
}

Vrácené hodnoty

Návratový GetTodoItems typ a GetTodoItem metody je Typ ActionResultT<>. ASP.NET Core objekt automaticky serializuje do formátu JSON a zapíše json do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 OK, za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

ActionResult návratové typy můžou představovat širokou škálu stavových kódů HTTP. Může například GetTodoItem vrátit dvě různé hodnoty stavu:

  • Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby stavu NotFound404.
  • Jinak metoda vrátí hodnotu 200 s textem odpovědi JSON. item Vrácení výsledků v odpovědi HTTP 200

Metoda PutTodoItem

Prohlédněte si metodu PutTodoItem:

// PUT: api/TodoItems/5
[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 je podobná PostTodoItem, s výjimkou použití HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP požadavek PUT vyžaduje, aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte http PATCH.

Pokud se zobrazí chybová volání PutTodoItem, zavolejte GET , abyste měli jistotu, že je v databázi položka.

Testování metody PutTodoItem

Tato ukázka používá databázi v paměti, která se musí inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Zavolejte GET, abyste se ujistili, že je v databázi položka před voláním PUT.

Aktualizujte položku úkolu s ID = 1 a nastavte jeho název na "feed fish":

  {
    "Id":1,
    "name":"feed fish",
    "isComplete":true
  }

Následující obrázek znázorňuje aktualizaci Postman:

Postman console showing 204 (No Content) response

Metoda DeleteTodoItem

Prohlédněte si metodu DeleteTodoItem:

// 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();
}

Testování metody DeleteTodoItem

Pomocí nástroje Postman odstraňte položku úkolu:

  • Nastavte metodu na DELETE.
  • Nastavte identifikátor URI objektu k odstranění (například https://localhost:5001/api/todoitems/1).
  • Vyberte Odeslat.

Zabránit nadměrnému účtování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní data a vrácená pomocí podmnožině modelu. Za tímto důvodem je několik důvodů a zabezpečení je hlavní. Podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto článku.

DTO lze použít k:

  • Zabránit nadměrnému účtování.
  • Skrýt vlastnosti, které klienti nemají zobrazit.
  • Pokud chcete zmenšit velikost datové části, vynecháte některé vlastnosti.
  • Zploštěné grafy objektů, které obsahují vnořené objekty. Grafy zploštěných objektů můžou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby obsahovala tajné pole:

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; }
    }
}

Tajné pole musí být skryté z této aplikace, ale aplikace pro správu by se mohla rozhodnout ji zpřístupnit.

Ověřte, že můžete publikovat a získat tajné pole.

Vytvoření modelu DTO:

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

Aktualizujte, aby se používalTodoItemDTO:TodoItemsController

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

[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);
}

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

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

    todoItem.Name = todoItemDTO.Name;
    todoItem.IsComplete = todoItemDTO.IsComplete;

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

    return NoContent();
}

[HttpPost]
public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
{
    var todoItem = new TodoItem
    {
        IsComplete = todoItemDTO.IsComplete,
        Name = todoItemDTO.Name
    };

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

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

[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) =>
     _context.TodoItems.Any(e => e.Id == id);

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

Ověřte, že nemůžete publikovat nebo získat tajné pole.

Volání webového rozhraní API pomocí JavaScriptu

Viz kurz: Volání webového rozhraní API ASP.NET Core pomocí JavaScriptu

V tomto kurzu se naučíte:

  • Vytvořte projekt webového rozhraní API.
  • Přidejte třídu modelu a kontext databáze.
  • Generování řídicího prvku pomocí metod CRUD
  • Nakonfigurujte směrování, cesty url a návratové hodnoty.
  • Volání webového rozhraní API pomocí nástroje Postman

Na konci máte webové rozhraní API, které může spravovat položky úkolů uložené v databázi.

Přehled

Tento kurz vytvoří následující rozhraní API:

Rozhraní API Popis Text požadavku Text odpovědi
GET /api/todoitems Získání všech položek úkolů Žádné Pole položek úkolů
GET /api/todoitems/{id} Získání položky podle ID Žádné Položka úkolů
POST /api/todoitems Přidání nové položky Položka úkolů Položka úkolů
PUT /api/todoitems/{id} Aktualizace existující položky Položka úkolů Žádné
DELETE /api/todoitems/{id}     Odstranění položky Žádné Žádné

Následující diagram znázorňuje návrh aplikace.

The client is represented by a box on the left. It submits a request and receives a response from the application, a box drawn on the right. Within the application box, three boxes represent the controller, the model, and the data access layer. The request comes into the application's controller, and read/write operations occur between the controller and the data access layer. The model is serialized and returned to the client in the response.

Požadavky

Vytvoření webového projektu

  • V nabídce Soubor vyberte Nový>Project.
  • Vyberte šablonu ASP.NET Core webové aplikace a klikněte na Tlačítko Další.
  • Pojmenujte projekt TodoApi a klikněte na Vytvořit.
  • V dialogovém okně Vytvořit novou ASP.NET Core webovou aplikaci potvrďte, že jsou vybrány .NET Core a ASP.NET Core 3.1. Vyberte šablonu rozhraní API a klikněte na Vytvořit.

VS new project dialog

Poznámka

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků v pracovním postupu využívání balíčků (NuGet dokumentaci). Potvrďte správné verze balíčků na adrese NuGet.org.

Testování rozhraní API

Šablona projektu vytvoří WeatherForecast rozhraní API. Get Volání metody z prohlížeče k otestování aplikace

Aplikaci spustíte stisknutím kombinace kláves Ctrl+F5. Visual Studio spustí prohlížeč a přejde na https://localhost:<port>/weatherforecast, kde <port> je náhodně zvolené číslo portu.

Pokud se zobrazí dialogové okno s dotazem, jestli byste měli důvěřovat certifikátu IIS Express, vyberte Ano. V dialogovém okně Upozornění zabezpečení , které se zobrazí dál, vyberte Ano.

Vrátí se json podobný následujícímu:

[
    {
        "date": "2019-07-16T19:04:05.7257911-06:00",
        "temperatureC": 52,
        "temperatureF": 125,
        "summary": "Mild"
    },
    {
        "date": "2019-07-17T19:04:05.7258461-06:00",
        "temperatureC": 36,
        "temperatureF": 96,
        "summary": "Warm"
    },
    {
        "date": "2019-07-18T19:04:05.7258467-06:00",
        "temperatureC": 39,
        "temperatureF": 102,
        "summary": "Cool"
    },
    {
        "date": "2019-07-19T19:04:05.7258471-06:00",
        "temperatureC": 10,
        "temperatureF": 49,
        "summary": "Bracing"
    },
    {
        "date": "2019-07-20T19:04:05.7258474-06:00",
        "temperatureC": -1,
        "temperatureF": 31,
        "summary": "Chilly"
    }
]

Přidání třídy modelu

Model je sada tříd, které představují data, která aplikace spravuje. Model pro tuto aplikaci je jedna TodoItem třída.

  • V Průzkumník řešení klikněte pravým tlačítkem myši na projekt. Vyberte přidat>novou složku. Pojmenujte složku Models.

  • Klikněte pravým tlačítkem myši na Models složku a vyberte AddClass>. Pojmenujte třídu TodoItem a vyberte Přidat.

  • Nahraďte kód šablony následujícím kódem:

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

Vlastnost Id funguje jako jedinečný klíč v relační databázi.

Třídy modelu můžou v projektu přejít kamkoli, ale Models složka se používá podle konvence.

Přidání kontextu databáze

Kontext databáze je hlavní třída, která koordinuje funkce Entity Framework pro datový model. Tato třída je vytvořena odvozením z Microsoft.EntityFrameworkCore.DbContext třídy.

Přidání balíčků NuGet

  • V nabídce Nástroje vyberte NuGet Správce balíčků > Spravovat NuGet balíčky pro řešení.
  • Vyberte kartu Procházet a do vyhledávacího pole zadejte Microsoft.EntityFrameworkCore.InMemory .
  • V levém podokně vyberte Microsoft.EntityFrameworkCore.InMemory .
  • V pravém podokně zaškrtněte políčko Project a pak vyberte Instalovat.

NuGet Package Manager

Přidání kontextu databáze TodoContext

  • Klikněte pravým tlačítkem myši na Models složku a vyberte AddClass>. Pojmenujte třídu TodoContext a klikněte na Přidat.
  • Zadejte následující kód:

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

Registrace kontextu databáze

V ASP.NET Core musí být služby, jako je kontext databáze, zaregistrované pomocí kontejneru injektáže závislostí (DI). Kontejner poskytuje službě kontrolery.

Aktualizujte Startup.cs následujícím zvýrazněným kódem:

// Unused usings removed
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

namespace TodoApi
{
    public class Startup
    {
        public Startup(IConfiguration configuration)
        {
            Configuration = configuration;
        }

        public IConfiguration Configuration { get; }

        public void ConfigureServices(IServiceCollection services)
        {
            services.AddDbContext<TodoContext>(opt =>
               opt.UseInMemoryDatabase("TodoList"));
            services.AddControllers();
        }

        public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }

            app.UseHttpsRedirection();

            app.UseRouting();

            app.UseAuthorization();

            app.UseEndpoints(endpoints =>
            {
                endpoints.MapControllers();
            });
        }
    }
}

Předchozí kód:

  • Odebere nepoužívané using deklarace.
  • Přidá kontext databáze do kontejneru DI.
  • Určuje, že kontext databáze bude používat databázi v paměti.

Generování řídicího prvku

  • Klikněte pravým tlačítkem myši na složku Kontrolery .

  • Vyberte přidat>novou vygenerovanou položku.

  • Vyberte kontroler rozhraní API s akcemi, pomocí Entity Frameworku a pak vyberte Přidat.

  • V dialogovém okně Přidat kontroler rozhraní API s akcemi pomocí entity Frameworku :

    • Ve třídě Model vyberte TodoItem (TodoApi.Models)
    • Ve třídě kontextu dat vyberte TodoContext (TodoApi.Models).
    • Vyberte Přidat.

Vygenerovaný kód:

  • Označí třídu atributem [ApiController] . Tento atribut označuje, že kontroler reaguje na požadavky webového rozhraní API. Informace o konkrétních chováních, které atribut povolí, najdete v tématu Vytvoření webových rozhraní API s ASP.NET Core.
  • Používá di k vložení kontextu databáze (TodoContext) do kontroleru. Kontext databáze se používá v každé z metod CRUD v kontroleru.

Šablony ASP.NET Core pro:

  • Kontrolery se zobrazeními patří [action] do šablony trasy.
  • Kontrolery rozhraní API nezahrnují [action] do šablony trasy.

[action] Pokud token není v šabloně trasy, název akce je z trasy vyloučený. To znamená, že název přidružené metody akce se v odpovídající trase nepoužívá.

Prozkoumání metody vytvoření PostTodoItem

Nahraďte příkaz return v operátoru PostTodoItemnameof :

// POST: api/TodoItems
[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);
}

Předchozí kód je metoda HTTP POST, jak je uvedeno atributem [HttpPost] . Metoda získá hodnotu položky úkolu z textu požadavku HTTP.

Další informace najdete v tématu Směrování atributů s atributy Http[Slovesa].

Metoda CreatedAtAction :

  • V případě úspěchu vrátí stavový kód HTTP 201. HTTP 201 je standardní odpověď metody HTTP POST, která na serveru vytvoří nový prostředek.
  • Přidá do odpovědi hlavičku Umístění . Hlavička Location určuje identifikátor URI nově vytvořené položky úkolu. Další informace naleznete v tématu 10.2.2 201 Vytvořeno.
  • Odkazuje na GetTodoItem akci a vytvoří Location identifikátor URI hlavičky. Klíčové slovo jazyka C# nameof slouží k tomu, aby se zabránilo pevnému CreatedAtAction kódování názvu akce ve volání.

Instalace nástroje Postman

Tento kurz používá Nástroj Postman k otestování webového rozhraní API.

  • Instalace nástroje Postman
  • Spusťte webovou aplikaci.
  • Spusťte Postman.
  • Zakažte ověření certifikátu SSL:
    • Postman pro Windows: Postman pro Windows Soubor>Nastavení (karta Obecné) zakažte ověření certifikátu SSL.
    • Postman pro macOS: Postman pro Windows Postman>Nastavení (karta Obecné), zakažte ověření certifikátu SSL.

      Upozornění

      Po otestování kontroleru znovu povolte ověření certifikátu SSL.

Testování PostTodoItem pomocí Nástroje Postman

  • Vytvořte novou žádost.

  • Nastavte metodu HTTP na POST.

  • Nastavte identifikátor URI na https://localhost:<port>/api/todoitems. Například, https://localhost:5001/api/todoitems.

  • Vyberte kartu Text .

  • Vyberte nezpracované přepínač.

  • Nastavte typ na JSON (application/json).

  • Do textu požadavku zadejte JSON pro položku úkolu:

    {
      "name":"walk dog",
      "isComplete":true
    }
    
  • Vyberte Odeslat.

    Postman with create request

Otestování identifikátoru URI hlavičky umístění pomocí nástroje Postman

  • V podokně Odpovědi vyberte kartu Záhlaví.

  • Zkopírujte hodnotu hlavičky Umístění :

    Headers tab of the Postman console

  • Nastavte metodu HTTP na GET.

  • Nastavte identifikátor URI na https://localhost:<port>/api/todoitems/1. Například, https://localhost:5001/api/todoitems/1.

  • Vyberte Odeslat.

Prozkoumání metod GET

Tyto metody implementují dva koncové body GET:

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

Otestujte aplikaci voláním dvou koncových bodů z prohlížeče nebo Nástroje Postman. Příklad:

  • https://localhost:5001/api/todoitems
  • https://localhost:5001/api/todoitems/1

Voláním :GetTodoItems

[
  {
    "id": 1,
    "name": "Item1",
    "isComplete": false
  }
]

Test Get with Postman

  • Vytvořte novou žádost.
  • Nastavte metodu HTTP na GET.
  • Nastavte identifikátor URI požadavku na https://localhost:<port>/api/todoitems. Například, https://localhost:5001/api/todoitems.
  • Nastavení dvou zobrazení podokna v nástroji Postman
  • Vyberte Odeslat.

Tato aplikace používá databázi v paměti. Pokud je aplikace zastavená a spuštěná, předchozí požadavek GET nevrátí žádná data. Pokud se žádná data nevrátí, post data do aplikace.

Směrování a cesty url

Atribut [HttpGet] označuje metodu, která reaguje na požadavek HTTP GET. Cesta URL pro každou metodu se konstruuje takto:

  • Začněte řetězcem šablony v atributu kontroleru Route :

    [Route("api/[controller]")]
    [ApiController]
    public class TodoItemsController : ControllerBase
    {
        private readonly TodoContext _context;
    
        public TodoItemsController(TodoContext context)
        {
            _context = context;
        }
    
  • Nahraďte [controller] názvem kontroleru, který konvencí je název třídy kontroleru minus přípona Controller. Pro tuto ukázku je název třídy kontroleru TodoItemsController, takže název kontroleru je TodoItems. ASP.NET Core směrování nerozlišuje malá a velká písmena.

  • [HttpGet] Pokud má atribut šablonu trasy (například[HttpGet("products")]), připojte ji k cestě. Tato ukázka nepoužívá šablonu. Další informace najdete v tématu Směrování atributů s atributy Http[Slovesa].

V následující GetTodoItem metodě "{id}" je zástupná proměnná pro jedinečný identifikátor položky úkolu. Při GetTodoItem vyvolání je hodnota "{id}" v adrese URL k dispozici metodě v jeho id parametru.

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

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

    return todoItem;
}

Vrácené hodnoty

Návratový GetTodoItems typ a GetTodoItem metody je ActionResultT<> typ. ASP.NET Core objekt automaticky serializuje do formátu JSON a zapíše json do textu zprávy odpovědi. Kód odpovědi pro tento návratový typ je 200 za předpokladu, že neexistují žádné neošetřené výjimky. Neošetřené výjimky se překládají do chyb 5xx.

ActionResult návratové typy můžou představovat širokou škálu stavových kódů HTTP. Může například GetTodoItem vrátit dvě různé hodnoty stavu:

  • Pokud žádná položka neodpovídá požadovanému ID, vrátí metoda kód chyby 404 NotFound .
  • V opačném případě metoda vrátí hodnotu 200 s textem odpovědi JSON. item Vrácení výsledků v odpovědi HTTP 200

Metoda PutTodoItem

Prohlédněte si metodu PutTodoItem:

// PUT: api/TodoItems/5
[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 je podobný PostTodoItem, s výjimkou použití HTTP PUT. Odpověď je 204 (bez obsahu). Podle specifikace HTTP vyžaduje požadavek PUT, aby klient odeslal celou aktualizovanou entitu, nejen změny. Pokud chcete podporovat částečné aktualizace, použijte funkci HTTP PATCH.

Pokud se zobrazí chybová volání PutTodoItem, zavolejte GET , abyste měli jistotu, že je v databázi položka.

Testování metody PutTodoItem

Tato ukázka používá databázi v paměti, která se musí inicializovat při každém spuštění aplikace. Před voláním PUT musí být v databázi položka. Před voláním metody PUT zavolejte get, abyste měli jistotu, že v databázi je položka.

Aktualizujte položku úkolu, která má ID = 1, a nastavte jeho název na "krmení ryb":

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

Následující obrázek znázorňuje aktualizaci Postman:

Postman console showing 204 (No Content) response

Metoda DeleteTodoItem

Prohlédněte si metodu DeleteTodoItem:

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

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

    return todoItem;
}

Testování metody DeleteTodoItem

Pomocí nástroje Postman odstraňte položku úkolu:

  • Nastavte metodu na DELETE.
  • Nastavte identifikátor URI objektu k odstranění (například https://localhost:5001/api/todoitems/1).
  • Vyberte Odeslat.

Zabránění nadměrnému publikování

V současné době ukázková aplikace zveřejňuje celý TodoItem objekt. Produkční aplikace obvykle omezují vstupní data a vrácená pomocí podmnožiny modelu. Za tímto důvodem je několik důvodů a zabezpečení je hlavním důvodem. Podmnožina modelu se obvykle označuje jako objekt pro přenos dat (DTO), vstupní model nebo model zobrazení. DTO se používá v tomto článku.

DTO lze použít k:

  • Zabránit nadměrnému publikování.
  • Skryjte vlastnosti, které klienti nemají zobrazit.
  • Vynecháte některé vlastnosti, aby se snížila velikost datové části.
  • Zploštěné grafy objektů, které obsahují vnořené objekty. Grafy plochých objektů mohou být pro klienty pohodlnější.

Pokud chcete předvést přístup DTO, aktualizujte TodoItem třídu tak, aby zahrnovala pole tajného kódu:

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

Tajné pole musí být v této aplikaci skryté, ale aplikace pro správu se může rozhodnout, že ho zveřejní.

Ověřte, že můžete publikovat a získat tajné pole.

Vytvoření modelu DTO:

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

Aktualizujte, TodoItemsController aby se používal TodoItemDTO:

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

    [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);
    }

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

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

        todoItem.Name = todoItemDTO.Name;
        todoItem.IsComplete = todoItemDTO.IsComplete;

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

        return NoContent();
    }

    [HttpPost]
    public async Task<ActionResult<TodoItemDTO>> CreateTodoItem(TodoItemDTO todoItemDTO)
    {
        var todoItem = new TodoItem
        {
            IsComplete = todoItemDTO.IsComplete,
            Name = todoItemDTO.Name
        };

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

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

    [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) =>
         _context.TodoItems.Any(e => e.Id == id);

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

Ověřte, že nemůžete publikovat nebo získat pole tajného kódu.

Volání webového rozhraní API pomocí JavaScriptu

Viz kurz: Volání webového rozhraní API ASP.NET Core pomocí JavaScriptu.

Přidání podpory ověřování do webového rozhraní API

ASP.NET Core Identitypřidá funkce přihlášení uživatelského rozhraní do ASP.NET Core webových aplikací. K zabezpečení webových rozhraní API a spA použijte jednu z následujících možností:

Duende Identity Server je rozhraní OpenID Připojení a OAuth 2.0 pro ASP.NET Core. Duende Identity Server umožňuje následující funkce zabezpečení:

  • Ověřování jako služba (AaaS)
  • Jednotné přihlašování nebo vypnutí (SSO) u více typů aplikací
  • Řízení přístupu pro rozhraní API
  • Federační brána

Důležité

Duende Software může vyžadovat, abyste zaplatili licenční poplatek za produkční použití Duende Identity Serveru. Další informace najdete v tématu Migrace z ASP.NET Core 5.0 na verzi 6.0.

Další informace najdete v dokumentaci k Duende Serveru (web Duende Identity Software).

Publikování do Azure

Informace o nasazení do Azure najdete v tématu Rychlý start: Nasazení webové aplikace ASP.NET.

Další materiály

Zobrazení nebo stažení ukázkového kódu pro tento kurz Podívejte se, jak si stáhnout.

Další informace naleznete v následujících zdrojích: