Руководство. Создание веб-API на основе контроллера с помощью ASP.NET Core

В этом руководстве описаны основы создания веб-API на основе контроллера, использующего базу данных. Another approach to creating APIs in ASP.NET Core is to create minimal APIs. For help with choosing between minimal APIs and controller-based APIs, see APIs overview. См. Руководство: Создание минимального API с помощью ASP.NET Core для получения инструкции по созданию минимального API.

Overview

В этом руководстве создается следующий API-интерфейс:

На следующем рисунке показана структура приложения.

Prerequisites

Создание проекта веб-API

Запуск проекта

The project template creates a WeatherForecast API with support for OpenAPI.

...
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.
...

[
    {
        "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"
    }
]

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

[
    {
        "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"
    }
]

Тестирование проекта

var app = builder.Build();

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

Добавление класса модели

A model is a set of classes that represent the data that the app manages. Для этого приложения используется класс модели TodoItem.

namespace TodoApi.Models;

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

namespace TodoApi.Models;

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

Свойство Id выступает в качестве уникального ключа реляционной базы данных.

Классы моделей можно размещать в любом месте проекта, но обычно для этого используется папка Models.

Добавление контекста базы данных

The database context is the main class that coordinates Entity Framework functionality for a data model. Этот класс является производным от класса Microsoft.EntityFrameworkCore.DbContext.

Регистрация контекста базы данных

В ASP.NET Core службы (такие как контекст базы данных) должны быть зарегистрированы с помощью контейнера внедрения зависимостей. Контейнер предоставляет службу контроллерам.

Обновите Program.cs, используя выделенный код:

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

Предыдущий код:

• Добавляет using директивы.
• Добавляет контекст базы данных в контейнер внедрения зависимостей.
• Указывает, что контекст базы данных будет использовать базу данных в памяти.

Создание каркаса контроллера

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

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

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

Сформированный код:

• Пометьте этот класс атрибутом [ApiController]. Этот атрибут указывает, что контроллер отвечает на запросы веб-API. Дополнительные сведения о поведении, которое реализует этот атрибут, см. в статье Создание веб-API с помощью ASP.NET Core.
• Использует DI для инъекции контекста базы данных (TodoContext) в контроллер. The database context is used in each of the CRUD methods in the controller.

Шаблоны ASP.NET Core для:

• Контроллеры с представлениями включают [action] в шаблоне маршрута.
• Контроллеры API не включают [action] в шаблоне маршрута.

When the [action] token isn't in the route template, the action name (method name) isn't included in the endpoint. То есть имя связанного метода действия не используется в соответствующем маршруте.

Обновление метода создания PostTodoItem

Update the return statement in the PostTodoItem to use the nameof operator:

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

Предыдущий код является методом HTTP POST , как указано атрибутом [HttpPost] . Метод получает значение TodoItem из текста HTTP-запроса.

Дополнительные сведения см. в разделе Маршрутизация атрибутов с помощью атрибутов Http[Verb].

Метод CreatedAtAction:

• В случае успеха возвращает код состояния HTTP 201. HTTP 201 — это стандартный HTTP POST ответ для метода, создающего новый ресурс на сервере.
• Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item. Дополнительные сведения см. в разделе 10.2.2 201 «Создан ресурс».
• Указывает действие GetTodoItem для создания URI заголовка Location. Ключевое слово nameof C# используется для предотвращения жесткого программирования имени действия в вызове CreatedAtAction.

Test PostTodoItem

Тестирование URI заголовка поля 'Location'

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

Знакомство с методами GET

Реализуются две конечные точки GET:

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

В предыдущем разделе показан пример /api/todoitems/{id} маршрута.

Follow the POST instructions to add another todo item, and then test the /api/todoitems route using Swagger.

Это приложение использует базу данных в оперативной памяти. Если приложение остановлено и запущено, предыдущий запрос GET не возвращает никаких данных. If no data is returned, POST data to the app.

Маршрутизация и пути URL

Атрибут [HttpGet] обозначает метод, который отвечает на HTTP GET запрос. Путь URL для каждого метода формируется следующим образом:

• Начните с строки шаблона в атрибуте Route контроллера.

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

• Замените [controller] именем контроллера (по соглашению это имя класса контроллера без суффикса "Controller"). For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". ASP.NET Core routing is case insensitive.

• Если атрибут [HttpGet] имеет шаблон маршрута (например, [HttpGet("products")]), добавьте его к пути. В этом примере шаблон не используется. Дополнительные сведения см. в разделе Маршрутизация атрибутов с помощью атрибутов Http[Verb].

В следующем методе GetTodoItem"{id}" — это переменная-заполнитель для уникального идентификатора элемента задачи. При вызове GetTodoItem, значение "{id}" из URL-адреса передаётся методу через параметр 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;
}

Return values

Тип возвращаемого значения для методов GetTodoItems и GetTodoItem — ActionResult<T>. ASP.NET Core automatically serializes the object to JSON and writes the JSON into the body of the response message. The response code for this return type is 200 OK, assuming there are no unhandled exceptions. Необработанные исключения преобразуются в ошибки 5xx.

Типы возвращаемых значений ActionResult могут представлять широкий спектр кодов состояний HTTP. Например, метод GetTodoItem может возвращать два разных значения состояния:

• If no item matches the requested ID, the method returns a 404 statusNotFound error code.
• В противном случае метод возвращает код 200 с телом ответа JSON. Результаты item приводят к ответу HTTP 200.

Метод PutTodoItem

Изучите метод 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 аналогичен PostTodoItem, за исключением того, что он использует HTTP PUT. Ответ — 204 (Нет содержимого). Согласно спецификации HTTP, PUT запрос требует от клиента отправки всей обновленной сущности, а не только изменений. To support partial updates, use HTTP PATCH.

Тестирование метода PutTodoItem

В этом примере используется база данных в памяти, которая должна быть инициирована при каждом запуске приложения. При выполнении вызова PUT в базе данных уже должен существовать какой-либо элемент. Для этого перед вызовом PUT выполните вызов GET, чтобы убедиться в наличии такого элемента в базе данных.

Используйте метод PUT для обновления TodoItem с идентификатором = 1 и задайте для него значение "feed fish". Обратите внимание, что ответ равен HTTP 204 No Content.

Метод DeleteTodoItem

Изучите метод 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();
}

Тестирование метода DeleteTodoItem

Используйте метод DELETE для удаления TodoItem с идентификатором = 1. Обратите внимание, что ответ равен HTTP 204 No Content.

Тестирование с помощью других средств

Существует множество других средств, которые можно использовать для тестирования веб-API, например:

• http-repl
• curl. Swagger использует curl и показывает команды curl, которые он отправляет.
• Fiddler

Prevent over-posting

В настоящее время пример приложения предоставляет весь объект TodoItem. Рабочие приложения обычно ограничивают вводимые данные и возвращают их с помощью подмножества модели. Такое поведение реализовано по нескольким причинам, но в основном из соображений безопасности. Подмножество модели обычно называется объектом передачи данных (DTO), моделью ввода или моделью представления. DTO is used in this tutorial.

DTO можно использовать для следующего:

• Prevent over-posting.
• Скрытие свойств, которые не предназначены для просмотра клиентами.
• Пропуск некоторых свойств, чтобы уменьшить размер полезной нагрузки.
• Уплощение графов объектов, которые содержат вложенные объекты. Сведенные графы объектов могут быть удобнее для клиентов.

Чтобы продемонстрировать подход с применением DTO, обновите класс TodoItem, включив в него поле секрета:

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

Поле секрета должно быть скрыто в этом приложении, однако административное приложение может отобразить его.

Убедитесь, что вы можете отправить и получить секретное поле.

Create a DTO model in a Models/TodoItemsDTO.cs file:

namespace TodoApi.Models;

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

Обновите TodoItemsController, так чтобы использовать 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
       };
}

Убедитесь, что вы не можете отправить или получить секретное поле.

Вызов веб-API с помощью JavaScript

См. руководство: Вызов веб-API ASP.NET Core с помощью JavaScript.

Серия видеороликов по веб-API

Смотрите Видео: Серия для начинающих: Web API.

Шаблоны корпоративных веб-приложений

Рекомендации по созданию надежного, безопасного, производительного, тестового и масштабируемого приложения ASP.NET Core см. в шаблонах веб-приложений Enterprise. Полный пример веб-приложения с высоким качеством рабочей среды, реализующий шаблоны, доступен.

Добавление поддержки аутентификации в веб-API

ASP.NET Core Identity позволяет использовать функцию входа в пользовательском интерфейсе для веб-приложений ASP.NET Core. Чтобы защитить веб-API и SPA, используйте один из следующих способов:

• Идентификатор Microsoft Entra
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Сервер

Duende Identity Server — это платформа OpenID Connect и OAuth 2.0 для ASP.NET Core. Duende Identity Server включает следующие функции безопасности:

• Проверка подлинности как услуга (AaaS)
• Единый вход и выход (SSO) для различных типов приложений
• Контроль доступа для API
• Federation Gateway

Дополнительные сведения см. в документации по Duende Identity Server (на веб-сайте ПО Duende).

Публикация в Azure

Сведения о развертывании в Azure см. в разделе Краткое руководство. Развертывание веб-приложения ASP.NET.

Additional resources

Просмотреть или скачать пример кода для этого учебника. См. раздел Практическое руководство. Скачивание файла.

Дополнительные сведения см. на следующих ресурсах:

• Создание веб-API с помощью ASP.NET Core
• Руководство. Создание минимального API с помощью ASP.NET Core
• Использование созданных документов OpenAPI
• документация по веб-API ASP.NET Core с помощью Swagger / OpenAPI
• Razor
• Маршрутизация на действия контроллера в ASP.NET Core
• Типы возвращаемых действий контроллера в веб-API ASP.NET Core
• Развертывание приложений ASP.NET Core в Службе приложений Azure
• Размещение и развертывание ASP.NET Core
• Создание веб-API с помощью ASP.NET Core

В этом руководстве описаны основы создания веб-API на основе контроллера, использующего базу данных. Another approach to creating APIs in ASP.NET Core is to create minimal APIs. For help with choosing between minimal APIs and controller-based APIs, see APIs overview. См. Руководство: Создание минимального API с помощью ASP.NET Core для получения инструкции по созданию минимального API.

Overview

В этом руководстве создается следующий API-интерфейс:

На следующем рисунке показана структура приложения.

Prerequisites

Создание веб-проекта

Тестирование проекта

The project template creates a WeatherForecast API with support for Swagger.

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

Откроется страница Swagger /swagger/index.html. Select GET>Try it out>Execute. На странице отобразятся:

• The Curl command to test the WeatherForecast API.
• URL-адрес для тестирования API WeatherForecast;
• код, текст и заголовки ответа;
• Раскрывающийся список с типами носителей, а также пример значений и схемы.

Если страница Swagger не отображается, см. эту проблему на сайте GitHub.

Swagger используется для создания полезной документации и страниц справки для веб-API. В этом руководстве используется Swagger для тестирования приложения. Дополнительные сведения о Swagger см. в статье Документация по веб-API ASP.NET Core с использованием Swagger (OpenAPI).

Copy and paste the Request URL in the browser: https://localhost:<port>/weatherforecast

Возвращаемые данные JSON будут примерно такими:

[
    {
        "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"
    }
]

Добавление класса модели

A model is a set of classes that represent the data that the app manages. Для этого приложения используется класс модели TodoItem.

namespace TodoApi.Models;

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

Свойство Id выступает в качестве уникального ключа реляционной базы данных.

Классы моделей можно размещать в любом месте проекта, но обычно для этого используется папка Models.

Добавление контекста базы данных

The database context is the main class that coordinates Entity Framework functionality for a data model. Этот класс является производным от класса Microsoft.EntityFrameworkCore.DbContext.

• Введите следующий код:

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

Регистрация контекста базы данных

В ASP.NET Core службы (такие как контекст базы данных) должны быть зарегистрированы с помощью контейнера внедрения зависимостей. Контейнер предоставляет службу контроллерам.

Обновите Program.cs, используя выделенный код:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Предыдущий код:

• Добавляет using директивы.
• Добавляет контекст базы данных в контейнер внедрения зависимостей.
• Указывает, что контекст базы данных будет использовать базу данных в памяти.

Создание каркаса контроллера

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

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

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

Сформированный код:

• Пометьте этот класс атрибутом [ApiController]. Этот атрибут указывает, что контроллер отвечает на запросы веб-API. Дополнительные сведения о поведении, которое реализует этот атрибут, см. в статье Создание веб-API с помощью ASP.NET Core.
• Использует DI для инъекции контекста базы данных (TodoContext) в контроллер. The database context is used in each of the CRUD methods in the controller.

Шаблоны ASP.NET Core для:

• Контроллеры с представлениями включают [action] в шаблоне маршрута.
• Контроллеры API не включают [action] в шаблоне маршрута.

When the [action] token isn't in the route template, the action name (method name) isn't included in the endpoint. То есть имя связанного метода действия не используется в соответствующем маршруте.

Обновление метода создания PostTodoItem

Update the return statement in the PostTodoItem to use the nameof operator:

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

Предыдущий код является методом HTTP POST , как указано атрибутом [HttpPost] . Метод получает значение TodoItem из текста HTTP-запроса.

Дополнительные сведения см. в разделе Маршрутизация атрибутов с помощью атрибутов Http[Verb].

Метод CreatedAtAction:

• В случае успеха возвращает код состояния HTTP 201. HTTP 201 — это стандартный HTTP POST ответ для метода, создающего новый ресурс на сервере.
• Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item. Дополнительные сведения см. в разделе 10.2.2 201 «Создан ресурс».
• Указывает действие GetTodoItem для создания URI заголовка Location. Ключевое слово nameof C# используется для предотвращения жесткого программирования имени действия в вызове CreatedAtAction.

Test PostTodoItem

• Нажмите клавиши CTRL+F5, чтобы запустить приложение.

• In the Swagger browser window, select POST /api/TodoItems, and then select Try it out.

• In the Request body input window, update the JSON. For example,

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

• Select Execute

  

Тестирование URI заголовка поля 'Location'

In the preceding POST, the Swagger UI shows the location header under Response headers. Например, location: https://localhost:7260/api/TodoItems/1. Заголовок расположения отображает универсальный код ресурса (URI) для созданного ресурса.

Чтобы проверить заголовок расположения, выполните следующие действия.

• In the Swagger browser window, select GET /api/TodoItems/{id}, and then select Try it out.

• Enter 1 in the id input box, and then select Execute.

  

Знакомство с методами GET

Реализуются две конечные точки GET:

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

В предыдущем разделе показан пример /api/todoitems/{id} маршрута.

Follow the POST instructions to add another todo item, and then test the /api/todoitems route using Swagger.

Это приложение использует базу данных в оперативной памяти. Если приложение остановлено и запущено, предыдущий запрос GET не возвращает никаких данных. If no data is returned, POST data to the app.

Маршрутизация и пути URL

Атрибут [HttpGet] обозначает метод, который отвечает на HTTP GET запрос. Путь URL для каждого метода формируется следующим образом:

• Начните с строки шаблона в атрибуте Route контроллера.

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

• Замените [controller] именем контроллера (по соглашению это имя класса контроллера без суффикса "Controller"). For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". ASP.NET Core routing is case insensitive.

• Если атрибут [HttpGet] имеет шаблон маршрута (например, [HttpGet("products")]), добавьте его к пути. В этом примере шаблон не используется. Дополнительные сведения см. в разделе Маршрутизация атрибутов с помощью атрибутов Http[Verb].

В следующем методе GetTodoItem"{id}" — это переменная-заполнитель для уникального идентификатора элемента задачи. При вызове GetTodoItem, значение "{id}" из URL-адреса передаётся методу через параметр 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;
}

Return values

Тип возвращаемого значения для методов GetTodoItems и GetTodoItem — ActionResult<T>. ASP.NET Core automatically serializes the object to JSON and writes the JSON into the body of the response message. The response code for this return type is 200 OK, assuming there are no unhandled exceptions. Необработанные исключения преобразуются в ошибки 5xx.

Типы возвращаемых значений ActionResult могут представлять широкий спектр кодов состояний HTTP. Например, метод GetTodoItem может возвращать два разных значения состояния:

• If no item matches the requested ID, the method returns a 404 statusNotFound error code.
• В противном случае метод возвращает код 200 с телом ответа JSON. Результаты item приводят к ответу HTTP 200.

Метод PutTodoItem

Изучите метод 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 аналогичен PostTodoItem, за исключением того, что он использует HTTP PUT. Ответ — 204 (Нет содержимого). Согласно спецификации HTTP, PUT запрос требует от клиента отправки всей обновленной сущности, а не только изменений. To support partial updates, use HTTP PATCH.

Тестирование метода PutTodoItem

В этом примере используется база данных в памяти, которая должна быть инициирована при каждом запуске приложения. При выполнении вызова PUT в базе данных уже должен существовать какой-либо элемент. Для этого перед вызовом PUT выполните вызов GET, чтобы убедиться в наличии такого элемента в базе данных.

Используя Swagger UI, нажмите кнопку PUT, чтобы обновить TodoItem с идентификатором 1 и установить его имя как "feed fish". Обратите внимание, что ответ равен HTTP 204 No Content.

Метод DeleteTodoItem

Изучите метод 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();
}

Тестирование метода DeleteTodoItem

Используйте интерфейс Swagger для удаления TodoItem, у которого идентификатор = 1. Обратите внимание, что ответ равен HTTP 204 No Content.

Тестирование с помощью других средств

Существует множество других средств, которые можно использовать для тестирования веб-API, например:

• Обозреватель конечных точек Visual Studio и HTTP-файлы
• http-repl
• curl. Swagger использует curl и показывает команды curl, которые он отправляет.
• Fiddler

Дополнительные сведения см. в разделе:

• Минимальное руководство по API: тестирование с помощью HTTP-файлов и обозревателя конечных точек

Prevent over-posting

В настоящее время пример приложения предоставляет весь объект TodoItem. Рабочие приложения обычно ограничивают вводимые данные и возвращают их с помощью подмножества модели. Такое поведение реализовано по нескольким причинам, но в основном из соображений безопасности. Подмножество модели обычно называется объектом передачи данных (DTO), моделью ввода или моделью представления. DTO is used in this tutorial.

DTO можно использовать для следующего:

• Prevent over-posting.
• Скрытие свойств, которые не предназначены для просмотра клиентами.
• Пропуск некоторых свойств, чтобы уменьшить размер полезной нагрузки.
• Уплощение графов объектов, которые содержат вложенные объекты. Сведенные графы объектов могут быть удобнее для клиентов.

Чтобы продемонстрировать подход с применением DTO, обновите класс TodoItem, включив в него поле секрета:

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

Поле секрета должно быть скрыто в этом приложении, однако административное приложение может отобразить его.

Убедитесь, что вы можете отправить и получить секретное поле.

Создайте модель DTO:

namespace TodoApi.Models;

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

Обновите TodoItemsController, так чтобы использовать 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
       };
}

Убедитесь, что вы не можете отправить или получить секретное поле.

Вызов веб-API с помощью JavaScript

См. руководство: Вызов веб-API ASP.NET Core с помощью JavaScript.

Серия видеороликов по веб-API

Смотрите Видео: Серия для начинающих: Web API.

Шаблоны корпоративных веб-приложений

Рекомендации по созданию надежного, безопасного, производительного, тестового и масштабируемого приложения ASP.NET Core см. в шаблонах веб-приложений Enterprise. Полный пример веб-приложения с высоким качеством рабочей среды, реализующий шаблоны, доступен.

Добавление поддержки аутентификации в веб-API

ASP.NET Core Identity позволяет использовать функцию входа в пользовательском интерфейсе для веб-приложений ASP.NET Core. Чтобы защитить веб-API и SPA, используйте один из следующих способов:

• Идентификатор Microsoft Entra
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Сервер

Duende Identity Server — это платформа OpenID Connect и OAuth 2.0 для ASP.NET Core. Duende Identity Server включает следующие функции безопасности:

• Проверка подлинности как услуга (AaaS)
• Единый вход и выход (SSO) для различных типов приложений
• Контроль доступа для API
• Federation Gateway

Дополнительные сведения см. в документации по Duende Identity Server (на веб-сайте ПО Duende).

Публикация в Azure

Сведения о развертывании в Azure см. в разделе Краткое руководство. Развертывание веб-приложения ASP.NET.

Additional resources

Просмотреть или скачать пример кода для этого учебника. См. раздел Практическое руководство. Скачивание файла.

Дополнительные сведения см. на следующих ресурсах:

• Создание веб-API с помощью ASP.NET Core
• Руководство. Создание минимального API с помощью ASP.NET Core
• документация по веб-API ASP.NET Core с помощью Swagger / OpenAPI
• Razor
• Маршрутизация на действия контроллера в ASP.NET Core
• Типы возвращаемых действий контроллера в веб-API ASP.NET Core
• Развертывание приложений ASP.NET Core в Службе приложений Azure
• Размещение и развертывание ASP.NET Core
• Создание веб-API с помощью ASP.NET Core

В этом руководстве описаны основы создания веб-API на основе контроллера, использующего базу данных. Another approach to creating APIs in ASP.NET Core is to create minimal APIs. For help with choosing between minimal APIs and controller-based APIs, see APIs overview. См. Руководство: Создание минимального API с помощью ASP.NET Core для получения инструкции по созданию минимального API.

Overview

В этом руководстве создается следующий API-интерфейс:

На следующем рисунке показана структура приложения.

Prerequisites

Создание веб-проекта

Тестирование проекта

The project template creates a WeatherForecast API with support for Swagger.

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

Откроется страница Swagger /swagger/index.html. Select GET>Try it out>Execute. На странице отобразятся:

• The Curl command to test the WeatherForecast API.
• URL-адрес для тестирования API WeatherForecast;
• код, текст и заголовки ответа;
• Раскрывающийся список с типами носителей, а также пример значений и схемы.

Если страница Swagger не отображается, см. эту проблему на сайте GitHub.

Swagger используется для создания полезной документации и страниц справки для веб-API. В этом руководстве используется Swagger для тестирования приложения. Дополнительные сведения о Swagger см. в статье Документация по веб-API ASP.NET Core с использованием Swagger (OpenAPI).

Copy and paste the Request URL in the browser: https://localhost:<port>/weatherforecast

Возвращаемые данные JSON будут примерно такими:

[
    {
        "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"
    }
]

Добавление класса модели

A model is a set of classes that represent the data that the app manages. Для этого приложения используется класс модели TodoItem.

namespace TodoApi.Models;

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

Свойство Id выступает в качестве уникального ключа реляционной базы данных.

Классы моделей можно размещать в любом месте проекта, но обычно для этого используется папка Models.

Добавление контекста базы данных

The database context is the main class that coordinates Entity Framework functionality for a data model. Этот класс является производным от класса Microsoft.EntityFrameworkCore.DbContext.

• Введите следующий код:

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

Регистрация контекста базы данных

В ASP.NET Core службы (такие как контекст базы данных) должны быть зарегистрированы с помощью контейнера внедрения зависимостей. Контейнер предоставляет службу контроллерам.

Обновите Program.cs, используя выделенный код:

using Microsoft.EntityFrameworkCore;
using TodoApi.Models;

var builder = WebApplication.CreateBuilder(args);

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

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.UseAuthorization();

app.MapControllers();

app.Run();

Предыдущий код:

• Добавляет using директивы.
• Добавляет контекст базы данных в контейнер внедрения зависимостей.
• Указывает, что контекст базы данных будет использовать базу данных в памяти.

Создание каркаса контроллера

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

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

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

Сформированный код:

• Пометьте этот класс атрибутом [ApiController]. Этот атрибут указывает, что контроллер отвечает на запросы веб-API. Дополнительные сведения о поведении, которое реализует этот атрибут, см. в статье Создание веб-API с помощью ASP.NET Core.
• Использует DI для инъекции контекста базы данных (TodoContext) в контроллер. The database context is used in each of the CRUD methods in the controller.

Шаблоны ASP.NET Core для:

• Контроллеры с представлениями включают [action] в шаблоне маршрута.
• Контроллеры API не включают [action] в шаблоне маршрута.

When the [action] token isn't in the route template, the action name (method name) isn't included in the endpoint. То есть имя связанного метода действия не используется в соответствующем маршруте.

Обновление метода создания PostTodoItem

Update the return statement in the PostTodoItem to use the nameof operator:

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

Предыдущий код является методом HTTP POST , как указано атрибутом [HttpPost] . Метод получает значение TodoItem из текста HTTP-запроса.

Дополнительные сведения см. в разделе Маршрутизация атрибутов с помощью атрибутов Http[Verb].

Метод CreatedAtAction:

• В случае успеха возвращает код состояния HTTP 201. HTTP 201 — это стандартный HTTP POST ответ для метода, создающего новый ресурс на сервере.
• Adds a Location header to the response. The Location header specifies the URI of the newly created to-do item. Дополнительные сведения см. в разделе 10.2.2 201 «Создан ресурс».
• Указывает действие GetTodoItem для создания URI заголовка Location. Ключевое слово nameof C# используется для предотвращения жесткого программирования имени действия в вызове CreatedAtAction.

Test PostTodoItem

• Нажмите клавиши CTRL+F5, чтобы запустить приложение.

• In the Swagger browser window, select POST /api/TodoItems, and then select Try it out.

• In the Request body input window, update the JSON. For example,

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

• Select Execute

  

Тестирование URI заголовка поля 'Location'

In the preceding POST, the Swagger UI shows the location header under Response headers. Например, location: https://localhost:7260/api/TodoItems/1. Заголовок расположения отображает универсальный код ресурса (URI) для созданного ресурса.

Чтобы проверить заголовок расположения, выполните следующие действия.

• In the Swagger browser window, select GET /api/TodoItems/{id}, and then select Try it out.

• Enter 1 in the id input box, and then select Execute.

  

Знакомство с методами GET

Реализуются две конечные точки GET:

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

В предыдущем разделе показан пример /api/todoitems/{id} маршрута.

Follow the POST instructions to add another todo item, and then test the /api/todoitems route using Swagger.

Это приложение использует базу данных в оперативной памяти. Если приложение остановлено и запущено, предыдущий запрос GET не возвращает никаких данных. If no data is returned, POST data to the app.

Маршрутизация и пути URL

Атрибут [HttpGet] обозначает метод, который отвечает на HTTP GET запрос. Путь URL для каждого метода формируется следующим образом:

• Начните с строки шаблона в атрибуте Route контроллера.

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

• Замените [controller] именем контроллера (по соглашению это имя класса контроллера без суффикса "Controller"). For this sample, the controller class name is TodoItemsController, so the controller name is "TodoItems". ASP.NET Core routing is case insensitive.

• Если атрибут [HttpGet] имеет шаблон маршрута (например, [HttpGet("products")]), добавьте его к пути. В этом примере шаблон не используется. Дополнительные сведения см. в разделе Маршрутизация атрибутов с помощью атрибутов Http[Verb].

В следующем методе GetTodoItem"{id}" — это переменная-заполнитель для уникального идентификатора элемента задачи. При вызове GetTodoItem, значение "{id}" из URL-адреса передаётся методу через параметр 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;
}

Return values

Тип возвращаемого значения для методов GetTodoItems и GetTodoItem — ActionResult<T>. ASP.NET Core automatically serializes the object to JSON and writes the JSON into the body of the response message. The response code for this return type is 200 OK, assuming there are no unhandled exceptions. Необработанные исключения преобразуются в ошибки 5xx.

Типы возвращаемых значений ActionResult могут представлять широкий спектр кодов состояний HTTP. Например, метод GetTodoItem может возвращать два разных значения состояния:

• If no item matches the requested ID, the method returns a 404 statusNotFound error code.
• В противном случае метод возвращает код 200 с телом ответа JSON. Результаты item приводят к ответу HTTP 200.

Метод PutTodoItem

Изучите метод 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 аналогичен PostTodoItem, за исключением того, что он использует HTTP PUT. Ответ — 204 (Нет содержимого). Согласно спецификации HTTP, PUT запрос требует от клиента отправки всей обновленной сущности, а не только изменений. To support partial updates, use HTTP PATCH.

Тестирование метода PutTodoItem

В этом примере используется база данных в памяти, которая должна быть инициирована при каждом запуске приложения. При выполнении вызова PUT в базе данных уже должен существовать какой-либо элемент. Для этого перед вызовом PUT выполните вызов GET, чтобы убедиться в наличии такого элемента в базе данных.

Используя Swagger UI, нажмите кнопку PUT, чтобы обновить TodoItem с идентификатором 1 и установить его имя как "feed fish". Обратите внимание, что ответ равен HTTP 204 No Content.

Метод DeleteTodoItem

Изучите метод 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();
}

Тестирование метода DeleteTodoItem

Используйте интерфейс Swagger для удаления TodoItem, у которого идентификатор = 1. Обратите внимание, что ответ равен HTTP 204 No Content.

Тестирование с помощью других средств

Существует множество других средств, которые можно использовать для тестирования веб-API, например:

• Обозреватель конечных точек Visual Studio и HTTP-файлы
• http-repl
• curl. Swagger использует curl и показывает команды curl, которые он отправляет.
• Fiddler

Дополнительные сведения см. в разделе:

• Минимальное руководство по API: тестирование с помощью HTTP-файлов и обозревателя конечных точек

Prevent over-posting

В настоящее время пример приложения предоставляет весь объект TodoItem. Рабочие приложения обычно ограничивают вводимые данные и возвращают их с помощью подмножества модели. Такое поведение реализовано по нескольким причинам, но в основном из соображений безопасности. Подмножество модели обычно называется объектом передачи данных (DTO), моделью ввода или моделью представления. DTO is used in this tutorial.

DTO можно использовать для следующего:

• Prevent over-posting.
• Скрытие свойств, которые не предназначены для просмотра клиентами.
• Пропуск некоторых свойств, чтобы уменьшить размер полезной нагрузки.
• Уплощение графов объектов, которые содержат вложенные объекты. Сведенные графы объектов могут быть удобнее для клиентов.

Чтобы продемонстрировать подход с применением DTO, обновите класс TodoItem, включив в него поле секрета:

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

Поле секрета должно быть скрыто в этом приложении, однако административное приложение может отобразить его.

Убедитесь, что вы можете отправить и получить секретное поле.

Создайте модель DTO:

namespace TodoApi.Models;

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

Обновите TodoItemsController, так чтобы использовать 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
       };
}

Убедитесь, что вы не можете отправить или получить секретное поле.

Вызов веб-API с помощью JavaScript

См. руководство: Вызов веб-API ASP.NET Core с помощью JavaScript.

Серия видеороликов по веб-API

Смотрите Видео: Серия для начинающих: Web API.

Шаблоны корпоративных веб-приложений

Рекомендации по созданию надежного, безопасного, производительного, тестового и масштабируемого приложения ASP.NET Core см. в шаблонах веб-приложений Enterprise. Полный пример веб-приложения с высоким качеством рабочей среды, реализующий шаблоны, доступен.

Добавление поддержки аутентификации в веб-API

ASP.NET Core Identity позволяет использовать функцию входа в пользовательском интерфейсе для веб-приложений ASP.NET Core. Чтобы защитить веб-API и SPA, используйте один из следующих способов:

• Идентификатор Microsoft Entra
• Azure Active Directory B2C (Azure AD B2C)
• Duende Identity Сервер

Duende Identity Server — это платформа OpenID Connect и OAuth 2.0 для ASP.NET Core. Duende Identity Server включает следующие функции безопасности:

• Проверка подлинности как услуга (AaaS)
• Единый вход и выход (SSO) для различных типов приложений
• Контроль доступа для API
• Federation Gateway

Дополнительные сведения см. в документации по Duende Identity Server (на веб-сайте ПО Duende).

Публикация в Azure

Сведения о развертывании в Azure см. в разделе Краткое руководство. Развертывание веб-приложения ASP.NET.

Additional resources

Просмотреть или скачать пример кода для этого учебника. См. раздел Практическое руководство. Скачивание файла.

Дополнительные сведения см. на следующих ресурсах:

• Создание веб-API с помощью ASP.NET Core
• Руководство. Создание минимального API с помощью ASP.NET Core
• документация по веб-API ASP.NET Core с помощью Swagger / OpenAPI
• Razor
• Маршрутизация на действия контроллера в ASP.NET Core
• Типы возвращаемых действий контроллера в веб-API ASP.NET Core
• Развертывание приложений ASP.NET Core в Службе приложений Azure
• Размещение и развертывание ASP.NET Core
• Создание веб-API с помощью ASP.NET Core