Bài hướng dẫn này sẽ dạy bạn những kiến thức cơ bản về xây dựng API web dựa trên controller sử dụng cơ sở dữ liệu. Một cách tiếp cận khác để tạo API trong ASP.NET Core là tạo API tối giản (Minimal API ). Để được trợ giúp trong việc lựa chọn giữa API tối giản và API dựa trên controller, hãy xem Tổng quan về API . Để xem hướng dẫn về cách tạo API tối giản, hãy xem Hướng dẫn: Tạo API tối giản với ASP.NET Core .
Hướng dẫn này tạo ra API sau:
| API | Sự miêu tả | Nội dung yêu cầu | Cơ quan phản hồi |
|---|---|---|---|
GET /api/todoitems | Nhận tất cả các mục cần làm | Không có | Mảng các mục cần làm |
GET /api/todoitems/{id} | Tìm kiếm mặt hàng theo ID | Không có | Mục cần làm |
POST /api/todoitems | Thêm mục mới | Mục cần làm | Mục cần làm |
PUT /api/todoitems/{id} | Cập nhật mục hiện có | Mục cần làm | Không có |
DELETE /api/todoitems/{id} | Xóa một mục | Không có | Không có |
Sơ đồ sau đây thể hiện thiết kế của ứng dụng.
Visual Studio 2022 với khối lượng công việc phát triển web và ASP.NET .
Cần phải thêm một gói NuGet để hỗ trợ cơ sở dữ liệu được sử dụng trong hướng dẫn này.
Microsoft.EntityFrameworkCore.InMemory.Ghi chú
Để được hướng dẫn về cách thêm gói vào ứng dụng .NET, hãy xem các bài viết trong phần Cài đặt và quản lý gói tại Quy trình sử dụng gói (tài liệu NuGet) . Xác nhận phiên bản gói chính xác tại NuGet.org .
Mẫu dự án này tạo ra một WeatherForecastAPI có hỗ trợ OpenAPI .
Nhấn Ctrl+F5 để chạy mà không cần trình gỡ lỗi.
Visual Studio sẽ hiển thị hộp thoại sau khi dự án chưa được cấu hình để sử dụng SSL:
Chọn Có nếu bạn tin tưởng chứng chỉ SSL của IIS Express.
Hộp thoại sau được hiển thị:
Chọn Có nếu bạn đồng ý tin tưởng chứng chỉ phát triển.
Để biết thông tin về việc tin tưởng trình duyệt Firefox, hãy xem lỗi chứng chỉ Firefox SEC_ERROR_INADEQUATE_KEY_USAGE .
Visual Studio mở một cửa sổ terminal và hiển thị URL của ứng dụng đang chạy. API được lưu trữ tại https://localhost:<port>, trong đó <port>là một số cổng được chọn ngẫu nhiên khi tạo dự án.
...
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.
...
Ctrl+ Nhấp vào URL HTTPS trong kết quả để kiểm tra ứng dụng web trong trình duyệt. Không có điểm cuối nào tại đó https://localhost:<port>, vì vậy trình duyệt trả về lỗi HTTP 404 Not Found .
Thêm đoạn mã này /weatherforecastvào URL để kiểm tra API WeatherForecast. Trình duyệt sẽ hiển thị dữ liệu JSON tương tự như ví dụ sau:
[
{
"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"
}
]
Hướng dẫn này sử dụng Endpoints Explorer và các tệp .http để kiểm tra API.
Mô hình là một tập hợp các lớp đại diện cho dữ liệu mà ứng dụng quản lý. Mô hình của ứng dụng này là TodoItemlớp .
Models.Modelsthư mục và chọn Thêm > Lớp . Đặt tên cho lớp là TodoItem và chọn Thêm .namespace TodoApi.Models;
public class TodoItem
{
public long Id { get; set; }
public string? Name { get; set; }
public bool IsComplete { get; set; }
}
Thuộc tính này Idđóng vai trò là khóa duy nhất trong cơ sở dữ liệu quan hệ.
Các lớp mô hình có thể được đặt ở bất kỳ đâu trong dự án, nhưng Modelsthư mục này được sử dụng theo quy ước.
Ngữ cảnh cơ sở dữ liệu là lớp chính điều phối các chức năng của Entity Framework cho một mô hình dữ liệu. Lớp này được tạo ra bằng cách kế thừa từ lớp Microsoft.EntityFrameworkCore.DbContext .
Nhấp chuột phải vào Modelsthư mục và chọn Thêm > Lớp . Đặt tên cho lớp là TodoContext và nhấp Thêm .
Nhập đoạn mã sau:
using Microsoft.EntityFrameworkCore;
namespace TodoApi.Models;
public class TodoContext : DbContext
{
public TodoContext(DbContextOptions<TodoContext> options)
: base(options)
{
}
public DbSet<TodoItem> TodoItems { get; set; } = null!;
}
Trong ASP.NET Core, các dịch vụ như ngữ cảnh cơ sở dữ liệu phải được đăng ký với bộ chứa tiêm phụ thuộc (DI) . Bộ chứa này cung cấp dịch vụ cho các bộ điều khiển.
Cập nhật Program.csvới đoạn mã được đánh dấu sau:
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();
Đoạn mã trước đó:
usingcác chỉ thị.Nhấp chuột phải vào Controllersthư mục.
Chọn Thêm > Mục được tạo mới .
Chọn API Controller with actions, using Entity Framework , rồi chọn Add .
Trong hộp thoại Thêm bộ điều khiển API với các hành động, sử dụng Entity Framework :
Nếu thao tác tạo giàn giáo thất bại, hãy chọn Thêm để thử tạo giàn giáo lần thứ hai.
Bước này thêm các gói Microsoft.VisualStudio.Web.CodeGeneration.DesignNuGet Microsoft.EntityFrameworkCore.Toolsvào dự án. Các gói này cần thiết cho việc tạo cấu trúc dự án (scaffolding).
Mã được tạo ra:
TodoContext) vào bộ điều khiển. Ngữ cảnh cơ sở dữ liệu được sử dụng trong mỗi phương thức CRUD trong bộ điều khiển.Các mẫu ASP.NET Core dành cho:
[action]trong mẫu định tuyến.[action]trong mẫu định tuyến.Khi [action]token không có trong mẫu định tuyến, tên hành động (tên phương thức) sẽ không được bao gồm trong điểm cuối. Tức là, tên phương thức liên kết với hành động đó sẽ không được sử dụng trong tuyến đường phù hợp.
Cập nhật câu lệnh return để PostTodoItemsử dụng toán tử nameof :
[HttpPost]
public async Task<ActionResult<TodoItem>> PostTodoItem(TodoItem todoItem)
{
_context.TodoItems.Add(todoItem);
await _context.SaveChangesAsync();
// return CreatedAtAction("GetTodoItem", new { id = todoItem.Id }, todoItem);
return CreatedAtAction(nameof(GetTodoItem), new { id = todoItem.Id }, todoItem);
}
Đoạn mã trên là một HTTP POSTphương thức, như được chỉ ra bởi [HttpPost]thuộc tính. Phương thức này lấy giá trị từ TodoItemphần thân của yêu cầu HTTP.
Để biết thêm thông tin, hãy xem Định tuyến thuộc tính với các thuộc tính Http[Verb] .
Phương thức CreatedAtAction :
HTTP 201Đây là phản hồi tiêu chuẩn cho một HTTP POSTphương thức tạo tài nguyên mới trên máy chủ.LocationTiêu đề này chỉ định URI của mục việc cần làm mới được tạo. Để biết thêm thông tin, hãy xem 10.2.2 201 Created .GetTodoItemhành động tạo LocationURI cho tiêu đề. Từ khóa C# nameofđược sử dụng để tránh mã hóa cứng tên hành động trong lời CreatedAtActiongọi hàm.Chọn Xem > Các cửa sổ khác > Trình khám phá điểm cuối .
Nhấp chuột phải vào điểm cuối POST và chọn Tạo yêu cầu .
Một tệp mới được tạo trong thư mục dự án có tên TodoApi.http, với nội dung tương tự như ví dụ sau:
@TodoApi_HostAddress = https://localhost:49738
POST {{TodoApi_HostAddress}}/api/todoitems
Content-Type: application/json
{
//TodoItem
}
###
###) là dấu phân định yêu cầu: những gì theo sau nó dành cho một yêu cầu khác.Yêu cầu POST mong đợi một TodoItem. Để định nghĩa việc cần làm, hãy thay thế phần //TodoItembình luận bằng JSON sau:
{
"name": "walk dog",
"isComplete": true
}
Tệp TodoApi.http giờ sẽ trông giống như ví dụ sau, nhưng với số cổng của bạn:
@TodoApi_HostAddress = https://localhost:7260
Post {{TodoApi_HostAddress}}/api/todoitems
Content-Type: application/json
{
"name": "walk dog",
"isComplete": true
}
###
Khởi chạy ứng dụng.
Chọn liên kết "Gửi yêu cầu" nằm phía trên POSTdòng yêu cầu.
Yêu cầu POST được gửi đến ứng dụng và phản hồi được hiển thị trong ngăn Phản hồi .
Kiểm tra ứng dụng bằng cách gọi các GETđiểm cuối (endpoints) từ trình duyệt hoặc sử dụng Endpoints Explorer . Các bước sau đây dành cho Endpoints Explorer .
Trong Endpoints Explorer , nhấp chuột phải vào điểm cuối GET đầu tiên và chọn Generate request .
Nội dung sau đây được thêm vào TodoApi.httptệp:
GET {{TodoApi_HostAddress}}/api/todoitems
###
Chọn liên kết "Gửi yêu cầu" nằm phía trên GETdòng "Yêu cầu mới".
Yêu cầu GET được gửi đến ứng dụng và phản hồi được hiển thị trong ngăn Phản hồi .
Nội dung phản hồi tương tự như JSON sau:
[
{
"id": 1,
"name": "walk dog",
"isComplete": true
}
]
Trong Endpoints Explorer , nhấp chuột phải vào endpoint /api/todoitems/{id} GET và chọn Generate request . Nội dung sau sẽ được thêm vào TodoApi.httptệp:
@id=0
GET {{TodoApi_HostAddress}}/api/todoitems/{{id}}
###
Gán {@id}cho 1(thay vì 0).
Chọn liên kết "Gửi yêu cầu" nằm phía trên dòng yêu cầu GET mới.
Yêu cầu GET được gửi đến ứng dụng và phản hồi được hiển thị trong ngăn Phản hồi .
Nội dung phản hồi tương tự như JSON sau:
{
"id": 1,
"name": "walk dog",
"isComplete": true
}
Hai điểm cuối GET được triển khai:
GET /api/todoitemsGET /api/todoitems/{id}Phần trước đã trình bày một ví dụ về /api/todoitems/{id}tuyến đường.
Hãy làm theo hướng dẫn POST để thêm một mục việc cần làm khác, sau đó kiểm tra /api/todoitemstuyến đường bằng Swagger.
Ứng dụng này sử dụng cơ sở dữ liệu trong bộ nhớ. Nếu ứng dụng bị dừng và khởi động lại, yêu cầu GET trước đó sẽ không trả về bất kỳ dữ liệu nào. Nếu không có dữ liệu nào được trả về, hãy gửi dữ liệu bằng phương thức POST đến ứng dụng.
Thuộc tính này [HttpGet]biểu thị phương thức phản hồi yêu HTTP GETcầu. Đường dẫn URL cho mỗi phương thức được xây dựng như sau:
Hãy bắt đầu với chuỗi mẫu trong Routethuộc tính của bộ điều khiển:
[Route("api/[controller]")]
[ApiController]
public class TodoItemsController : ControllerBase
Thay thế [controller]bằng tên của bộ điều khiển, theo quy ước là tên lớp bộ điều khiển bỏ đi hậu tố "Controller". Trong ví dụ này, tên lớp bộ điều khiển là TodoItems Controller, vì vậy tên bộ điều khiển là "TodoItems". Định tuyến trong ASP.NET Core không phân biệt chữ hoa chữ thường.
Nếu [HttpGet]thuộc tính có mẫu định tuyến (ví dụ: [HttpGet("products")]), hãy thêm mẫu đó vào đường dẫn. Ví dụ này không sử dụng mẫu. Để biết thêm thông tin, hãy xem Định tuyến thuộc tính với thuộc tính Http[Verb] .
Trong GetTodoItemphương thức sau, "{id}"là một biến giữ chỗ cho mã định danh duy nhất của mục việc cần làm. Khi GetTodoItemđược gọi, giá trị của "{id}"trong URL sẽ được cung cấp cho phương thức thông qua idtham số của nó.
[HttpGet("{id}")]
public async Task<ActionResult<TodoItem>> GetTodoItem(long id)
{
var todoItem = await _context.TodoItems.FindAsync(id);
if (todoItem == null)
{
return NotFound();
}
return todoItem;
}
Kiểu trả về của các phương thức ` GetTodoItemsand` GetTodoItemlà kiểu `ActionResult<T>` . ASP.NET Core tự động tuần tự hóa đối tượng thành JSON và ghi JSON vào phần thân của thông báo phản hồi. Mã phản hồi cho kiểu trả về này là 200 OK , giả sử không có ngoại lệ nào chưa được xử lý. Các ngoại lệ chưa được xử lý được dịch thành lỗi 5xx.
ActionResultCác kiểu trả về có thể đại diện cho nhiều mã trạng thái HTTP khác nhau. Ví dụ, GetTodoItemnó có thể trả về hai giá trị trạng thái khác nhau:
itemkết quả sẽ tạo ra một HTTP 200phản hồi.Hãy xem xét PutTodoItemphương pháp:
[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();
}
PutTodoItemTương tự như PostTodoItem, ngoại trừ việc nó sử dụng HTTP PUT. Phản hồi là 204 (Không có nội dung) . Theo đặc tả HTTP, PUTyêu cầu này đòi hỏi máy khách phải gửi toàn bộ thực thể đã cập nhật, chứ không chỉ những thay đổi. Để hỗ trợ cập nhật một phần, hãy sử dụng HTTP PATCH .
Ví dụ này sử dụng cơ sở dữ liệu trong bộ nhớ, cần được khởi tạo mỗi khi ứng dụng được khởi chạy. Phải có một mục trong cơ sở dữ liệu trước khi bạn thực hiện lệnh PUT. Hãy gọi lệnh GET để đảm bảo có mục trong cơ sở dữ liệu trước khi thực hiện lệnh PUT.
Sử dụng PUTphương thức này để cập nhật phần TodoItemtử có Id = 1 và đặt tên cho nó thành "feed fish". Lưu ý rằng phản hồi nhận được là HTTP 204 No Content.
Trong Endpoints Explorer , nhấp chuột phải vào endpoint PUT và chọn Generate request .
Nội dung sau đây được thêm vào TodoApi.httptệp:
PUT {{TodoApi_HostAddress}}/api/todoitems/{{id}}
Content-Type: application/json
{
//TodoItem
}
###
Trong dòng yêu cầu PUT, hãy thay thế {{id}}bằng 1.
Thay thế đoạn //TodoItemvăn bản giữ chỗ bằng các dòng sau:
PUT {{TodoApi_HostAddress}}/api/todoitems/1
Content-Type: application/json
{
"id": 1,
"name": "feed fish",
"isComplete": false
}
Chọn liên kết "Gửi yêu cầu" nằm phía trên dòng yêu cầu PUT mới.
Yêu cầu PUT được gửi đến ứng dụng và phản hồi được hiển thị trong ngăn Phản hồi . Phần thân phản hồi trống và mã trạng thái là 204.
Hãy xem xét DeleteTodoItemphương pháp:
[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();
}
Sử dụng DELETEphương thức này để xóa phần TodoItemtử có Id = 1. Lưu ý rằng phản hồi là HTTP 204 No Content.
Trong Endpoints Explorer , nhấp chuột phải vào endpoint DELETE và chọn Generate request .
Một yêu cầu XÓA được thêm vào TodoApi.http.
Thay thế {{id}}trong dòng yêu cầu DELETE bằng 1. Yêu cầu DELETE sẽ trông giống như ví dụ sau:
DELETE {{TodoApi_HostAddress}}/api/todoitems/{{id}}
###
Chọn liên kết "Gửi yêu cầu" cho yêu cầu XÓA.
Yêu cầu DELETE được gửi đến ứng dụng và phản hồi được hiển thị trong ngăn Phản hồi . Phần thân phản hồi trống và mã trạng thái là 204.
Có rất nhiều công cụ khác có thể được sử dụng để kiểm tra API web, ví dụ:
curlvà hiển thị curlcác lệnh mà nó gửi đi.Hiện tại, ứng dụng mẫu hiển thị toàn bộ TodoItemđối tượng. Các ứng dụng sản xuất thường giới hạn dữ liệu được nhập và trả về bằng cách sử dụng một tập hợp con của mô hình. Có nhiều lý do đằng sau điều này, và bảo mật là một lý do chính. Tập hợp con của một mô hình thường được gọi là Đối tượng Truyền dữ liệu (DTO), mô hình đầu vào hoặc mô hình hiển thị. DTO được sử dụng trong hướng dẫn này.
Một DTO có thể được sử dụng để:
Để minh họa cách tiếp cận DTO, hãy cập nhật TodoItemlớp để bao gồm một trường bí mật:
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; }
}
Trường thông tin bí mật cần được ẩn khỏi ứng dụng này, nhưng một ứng dụng quản trị có thể chọn hiển thị nó.
Xác minh xem bạn có thể đăng bài và lấy thông tin bí mật hay không.
Tạo mô hình DTO trong tệp Models/TodoItemDTO.cs :
namespace TodoApi.Models;
public class TodoItemDTO
{
public long Id { get; set; }
public string? Name { get; set; }
public bool IsComplete { get; set; }
}
Cập nhật TodoItemsControllerđể sử dụng 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
};
}
Hãy xác minh rằng bạn không thể đăng bài hoặc lấy thông tin bí mật.
Xem hướng dẫn: Gọi API web ASP.NET Core bằng JavaScript .
Xem video: Chuỗi bài giảng dành cho người mới bắt đầu về: API web .
Để được hướng dẫn về cách tạo ứng dụng ASP.NET Core đáng tin cậy, an toàn, hiệu quả, dễ kiểm thử và có khả năng mở rộng, hãy xem các mẫu ứng dụng web doanh nghiệp . Một ứng dụng web mẫu hoàn chỉnh chất lượng sản xuất triển khai các mẫu này cũng có sẵn.
ASP.NET Core Identity bổ sung chức năng đăng nhập giao diện người dùng (UI) cho các ứng dụng web ASP.NET Core. Để bảo mật các API web và SPA, hãy sử dụng một trong các phương pháp sau:
Duende Identity Server là một framework OpenID Connect và OAuth 2.0 dành cho ASP.NET Core. Duende Identity Server hỗ trợ các tính năng bảo mật sau:
Post a Comment
- Nếu bạn không có các tài khoản để nhắn tin/bình luận bạn có thể chọn trong "Nhận xét với tư cách" với tài khoản "Ẩn danh" (Anonymous).
Cám ơn bạn đã đọc blog! Chúc bạn tìm được nhiều bài viết hay và hữu ích cho mình!