Tutorial: Membuat API web dengan ASP.NET Core

  • Artikel
  • 43 menit untuk membaca

Oleh Rick Anderson dan Kirk Larkin

Tutorial ini mengajarkan dasar-dasar membangun API web dengan ASP.NET Core.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Membuat proyek API web.
  • Tambahkan kelas model dan konteks database.
  • Perancah pengontrol dengan metode CRUD.
  • Mengonfigurasi perutean, jalur URL, dan mengembalikan nilai.
  • Panggil API web dengan http-repl.

Pada akhirnya, Anda memiliki API web yang dapat mengelola item "harus dilakukan" yang disimpan dalam database.

Gambaran Umum

Tutorial ini membuat API berikut:

API Deskripsi Isi permintaan Isi Respons
GET /api/todoitems Dapatkan semua item yang harus dilakukan Tidak ada Array item yang harus dilakukan
GET /api/todoitems/{id} Mendapatkan item menurut ID Tidak ada Item tugas
POST /api/todoitems Menambahkan item baru Item tugas Item tugas
PUT /api/todoitems/{id} Memperbarui item yang sudah ada Item tugas Tidak ada
DELETE /api/todoitems/{id}     Hapus item Tidak ada Tidak ada

Diagram berikut menunjukkan desain aplikasi.

Klien diwakili oleh kotak di sebelah kiri. Ini mengirimkan permintaan dan menerima respons dari aplikasi, kotak yang digambar di sebelah kanan. Dalam kotak aplikasi, tiga kotak mewakili pengontrol, model, dan lapisan akses data. Permintaan masuk ke pengontrol aplikasi, dan operasi baca/tulis terjadi antara pengontrol dan lapisan akses data. Model diserialisasikan dan dikembalikan ke klien dalam respons.

Prasyarat

Membuat proyek web

  • Pada menu File, pilih Proyek>Baru.
  • Masukkan Web API di kotak pencarian.
  • Pilih templat ASP.NET Core Web API dan pilih Berikutnya.
  • Dalam dialog Konfigurasikan proyek baru Anda, beri nama proyek TodoApi dan pilih Berikutnya.
  • Dalam dialog Informasi tambahan:
    • Konfirmasi bahwa Kerangka Kerja adalah .NET 6.0 (Dukungan jangka panjang).
    • Konfirmasi bahwa kotak centang untuk Gunakan pengontrol (hapus centang untuk menggunakan API minimal) dicentang.
    • Pilih Buat.

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bawah Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Menguji proyek

Templat proyek membuat WeatherForecast API dengan dukungan untuk Swagger.

Tekan Ctrl+F5 untuk menjalankan tanpa debugger.

Visual Studio menampilkan dialog berikut saat proyek belum dikonfigurasi untuk menggunakan SSL:

Proyek ini dikonfigurasi untuk menggunakan SSL. Untuk menghindari peringatan SSL di browser, Anda dapat memilih untuk mempercayai sertifikat yang ditandatangani sendiri yang telah dibuat IIS Express. Apakah Anda ingin mempercayai sertifikat IIS Express SSL?

Pilih Ya jika Anda mempercayai sertifikat IIS Express SSL.

Dialog berikut ditampilkan:

Dialog peringatan keamanan

Pilih Ya jika Anda setuju untuk mempercayai sertifikat pengembangan.

Untuk informasi tentang mempercayai browser Firefox, lihat Kesalahan sertifikat Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Visual Studio meluncurkan browser default dan menavigasi ke https://localhost:<port>/swagger/index.html, di mana <port> adalah nomor port yang dipilih secara acak.

Halaman Swagger /swagger/index.html ditampilkan. Pilih GET>Try it out>Execute. Halaman menampilkan:

  • Perintah Curl untuk menguji WEATHERForecast API.
  • URL untuk menguji WEATHERForecast API.
  • Kode respons, isi, dan header.
  • Kotak daftar drop-down dengan jenis media dan nilai contoh dan skema.

Jika halaman Swagger tidak muncul, lihat masalah GitHub ini.

Swagger digunakan untuk menghasilkan halaman dokumentasi dan bantuan yang berguna untuk API web. Tutorial ini berfokus pada pembuatan API web. Untuk informasi selengkapnya tentang Swagger, lihat dokumentasi API web ASP.NET Core dengan Swagger / OpenAPI.

Salin dan tempel URL Permintaan di browser: https://localhost:<port>/weatherforecast

JSON yang mirip dengan contoh berikut dikembalikan:

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

Memperbarui launchUrl

Di Properties\launchSettings.json, perbarui launchUrl dari "swagger" ke "api/todoitems":

"launchUrl": "api/todoitems",

Karena Swagger akan dihapus, markup sebelumnya mengubah URL yang diluncurkan ke metode GET pengontrol yang ditambahkan di bagian berikut.

Menambahkan kelas model

Model adalah sekumpulan kelas yang mewakili data yang dikelola aplikasi. Model untuk aplikasi ini adalah satu TodoItem kelas.

  • Di Penjelajah Solusi, klik kanan proyek. Pilih Tambahkan>Folder Baru. Beri nama folder Models.

  • Models Klik kanan folder dan pilih Tambahkan>Kelas. Beri nama kelas TodoItem dan pilih Tambahkan.

  • Ganti kode templat dengan yang berikut ini:

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

Properti Id berfungsi sebagai kunci unik dalam database relasional.

Kelas model dapat pergi ke mana saja dalam proyek, tetapi Models folder digunakan oleh konvensi.

Menambahkan konteks database

Konteks database adalah kelas utama yang mengoordinasikan fungsionalitas Kerangka Kerja Entitas untuk model data. Kelas ini dibuat dengan berasal dari Microsoft.EntityFrameworkCore.DbContext kelas .

Menambahkan paket NuGet

  • Dari menu Alat , pilih Manajer > Paket NuGet Kelola Paket NuGet untuk Solusi.
  • Pilih tab Telusuri , lalu masukkan Microsoft.EntityFrameworkCore.InMemory di kotak pencarian.
  • Pilih Microsoft.EntityFrameworkCore.InMemory di panel kiri.
  • Pilih kotak centang Proyek di panel kanan lalu pilih Instal.

Menambahkan konteks database TodoContext

  • Models Klik kanan folder dan pilih Tambahkan>Kelas. Beri nama kelas TodoContext dan klik Tambahkan.

  • Masukkan kode berikut:

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

Mendaftarkan konteks database

Dalam ASP.NET Core, layanan seperti konteks DB harus terdaftar dengan kontainer injeksi dependensi (DI ). Kontainer menyediakan layanan untuk pengontrol.

Perbarui Program.cs dengan kode berikut:

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

Kode sebelumnya:

  • Menghapus panggilan Swagger.
  • Menghapus arahan yang tidak digunakan using .
  • Menambahkan konteks database ke kontainer DI.
  • Menentukan bahwa konteks database akan menggunakan database dalam memori.

Perancah pengontrol

  • Klik kanan folder Pengontrol .

  • Pilih Tambahkan>Item Perancah Baru.

  • Pilih Pengontrol API dengan tindakan, menggunakan Kerangka Kerja Entitas, lalu pilih Tambahkan.

  • Dalam dialog Tambahkan Pengontrol API dengan tindakan, menggunakan Kerangka Kerja Entitas :

    • Pilih TodoItem (TodoApi.Models) di kelas Model.
    • Pilih TodoContext (TodoApi.Models) di kelas Konteks data.
    • Pilih Tambahkan.

    Jika operasi perancah gagal, pilih Tambahkan untuk mencoba perancah untuk kedua kalinya.

Kode yang dihasilkan:

  • Menandai kelas dengan [ApiController] atribut . Atribut ini menunjukkan bahwa pengontrol merespons permintaan API web. Untuk informasi tentang perilaku tertentu yang diaktifkan atribut, lihat Membuat API web dengan ASP.NET Core.
  • Menggunakan DI untuk menyuntikkan konteks database (TodoContext) ke dalam pengontrol. Konteks database digunakan dalam setiap metode CRUD di pengontrol.

Templat ASP.NET Core untuk:

  • Pengontrol dengan tampilan disertakan [action] dalam templat rute.
  • Pengontrol API tidak disertakan [action] dalam templat rute.

[action] Saat token tidak berada dalam templat rute, nama tindakan dikecualikan dari rute. Artinya, nama metode terkait tindakan tidak digunakan dalam rute yang cocok.

Memperbarui metode pembuatan PostTodoItem

Perbarui pernyataan pengembalian dalam PostTodoItem untuk menggunakan operator 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);
}

Kode sebelumnya adalah metode HTTP POST, seperti yang ditunjukkan [HttpPost] oleh atribut . Metode ini mendapatkan nilai item yang harus dilakukan dari isi permintaan HTTP.

Untuk informasi selengkapnya, lihat Perutean atribut dengan atribut Http[Verb].

Metode CreatedAtAction:

  • Mengembalikan kode status HTTP 201 jika berhasil. HTTP 201 adalah respons standar untuk metode HTTP POST yang membuat sumber daya baru di server.
  • Menambahkan header Lokasi ke respons. Header Location menentukan URI item tugas yang baru dibuat. Untuk informasi selengkapnya, lihat 10.2.2 201 Dibuat.
  • Mereferensikan GetTodoItem tindakan untuk membuat Location URI header. Kata kunci C# nameof digunakan untuk menghindari hard-coding nama tindakan dalam CreatedAtAction panggilan.

Menginstal http-repl

Tutorial ini menggunakan http-repl untuk menguji API web.

  • Jalankan perintah berikut ini pada prompt perintah:

    dotnet tool install -g Microsoft.dotnet-httprepl

  • Jika Anda tidak menginstal .NET 6.0 SDK atau runtime, instal runtime .NET 6.0.

Uji PostTodoItem

  • Tekan Ctrl+F5 untuk menjalankan aplikasi.

  • Buka jendela terminal baru, dan jalankan perintah berikut. Jika aplikasi Anda menggunakan nomor port yang berbeda, ganti 5001 di perintah httprepl dengan nomor port Anda.

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

    Berikut contoh output dari perintah:

    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
}

Menguji URI header lokasi

Untuk menguji header lokasi, salin dan tempelkan ke perintah httprepl get .

Contoh berikut mengasumsikan bahwa Anda masih berada dalam sesi httprepl. Jika Anda mengakhiri sesi httprepl sebelumnya, ganti connect dengan httprepl dalam perintah berikut:

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

Berikut contoh output dari perintah:

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
}

Memeriksa metode GET

Dua titik akhir GET diimplementasikan:

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

Anda hanya melihat contoh /api/todoitems/{id} rute. /api/todoitems Uji rute:

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

Berikut contoh output dari perintah:

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

Kali ini, ON yang JSdikembalikan adalah array dari satu item.

Aplikasi ini menggunakan database dalam memori. Jika aplikasi dihentikan dan dimulai, permintaan GET sebelumnya tidak akan mengembalikan data apa pun. Jika tidak ada data yang dikembalikan, KIRIM data ke aplikasi.

Perutean dan jalur URL

Atribut [HttpGet] menunjukkan metode yang merespons permintaan HTTP GET. Jalur URL untuk setiap metode dibangun sebagai berikut:

  • Mulailah dengan string templat di atribut pengontrol Route :

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

  • Ganti [controller] dengan nama pengontrol, yang menurut konvensi adalah nama kelas pengontrol dikurangi akhiran "Pengontrol". Untuk sampel ini, nama kelas pengontrol adalah TodoItemsController, sehingga nama pengontrol adalah "TodoItems". perutean ASP.NET Core tidak peka huruf besar/kecil.

  • [HttpGet] Jika atribut memiliki templat rute (misalnya, [HttpGet("products")]), tambahkan ke jalur. Sampel ini tidak menggunakan templat. Untuk informasi selengkapnya, lihat Perutean atribut dengan atribut Http[Verb].

Dalam metode berikut GetTodoItem , "{id}" adalah variabel tempat penampung untuk pengidentifikasi unik item yang harus dilakukan. Ketika GetTodoItem dipanggil, nilai "{id}" dalam URL disediakan untuk metode dalam parameternya 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;
}

Nilai yang dikembalikan

Jenis pengembalian metode GetTodoItems dan GetTodoItem adalah jenis ActionResult<T>. ASP.NET Core secara otomatis menserialisasikan objek ke JSAKTIF dan menulis JSON ke dalam isi pesan respons. Kode respons untuk jenis pengembalian ini adalah 200 OK, dengan asumsi tidak ada pengecualian yang tidak tertangani. Pengecualian yang tidak tertangani diterjemahkan ke dalam kesalahan 5xx.

ActionResult jenis pengembalian dapat mewakili berbagai kode status HTTP. Misalnya, GetTodoItem dapat mengembalikan dua nilai status yang berbeda:

  • Jika tidak ada item yang cocok dengan ID yang diminta, metode mengembalikan kode kesalahan status NotFound404.
  • Jika tidak, metode mengembalikan 200 dengan isi JSrespons ON. Mengembalikan item hasil dalam respons HTTP 200.

Metode PutTodoItem

PutTodoItem Periksa metode :

[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 mirip PostTodoItemdengan , kecuali menggunakan HTTP PUT. Responsnya adalah 204 (Tanpa Konten). Menurut spesifikasi HTTP, permintaan PUT mengharuskan klien untuk mengirim seluruh entitas yang diperbarui, bukan hanya perubahan. Untuk mendukung pembaruan parsial, gunakan HTTP PATCH.

Jika Anda mendapatkan kesalahan saat memanggil PutTodoItem di bagian berikut, panggil GET untuk memastikan ada item dalam database.

Menguji metode PutTodoItem

Sampel ini menggunakan database dalam memori yang harus diinisialisasi setiap kali aplikasi dimulai. Harus ada item dalam database sebelum Anda melakukan panggilan PUT. Panggil GET untuk memastikan ada item dalam database sebelum melakukan panggilan PUT.

Perbarui item yang harus dilakukan yang memiliki Id = 1 dan atur namanya ke "feed fish":

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

Berikut contoh output dari perintah:

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

Metode DeleteTodoItem

DeleteTodoItem Periksa metode :

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

Menguji metode DeleteTodoItem

Hapus item yang harus dilakukan yang memiliki Id = 1:

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

Berikut contoh output dari perintah:

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

Mencegah pengiriman berlebihan

Saat ini aplikasi sampel mengekspos seluruh TodoItem objek. Aplikasi produksi biasanya membatasi data yang diinput dan dikembalikan menggunakan subset model. Ada beberapa alasan di balik ini, dan keamanan adalah yang utama. Subset model biasanya disebut sebagai Objek Transfer Data (DTO), model input, atau model tampilan. DTO digunakan dalam tutorial ini.

DTO dapat digunakan untuk:

  • Cegah pengiriman berlebihan.
  • Sembunyikan properti yang tidak seharusnya dilihat klien.
  • Hilangkan beberapa properti untuk mengurangi ukuran payload.
  • Meratakan grafik objek yang berisi objek berlapis. Grafik objek yang diratakan bisa lebih nyaman untuk klien.

Untuk menunjukkan pendekatan DTO, perbarui TodoItem kelas untuk menyertakan bidang rahasia:

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

Bidang rahasia perlu disembunyikan dari aplikasi ini, tetapi aplikasi administratif dapat memilih untuk mengeksposnya.

Verifikasi bahwa Anda dapat memposting dan mendapatkan bidang rahasia.

Buat model DTO:

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

TodoItemsController Perbarui untuk menggunakan 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
        [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
            };
    }
}

Verifikasi bahwa Anda tidak dapat memposting atau mendapatkan bidang rahasia.

Memanggil API web dengan JavaScript

Lihat Tutorial: Memanggil API web ASP.NET Core dengan JavaScript.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Membuat proyek API web.
  • Tambahkan kelas model dan konteks database.
  • Perancah pengontrol dengan metode CRUD.
  • Mengonfigurasi perutean, jalur URL, dan mengembalikan nilai.
  • Panggil API web dengan Postman.

Pada akhirnya, Anda memiliki API web yang dapat mengelola item "harus dilakukan" yang disimpan dalam database.

Gambaran Umum

Tutorial ini membuat API berikut:

API Deskripsi Isi permintaan Isi Respons
GET /api/todoitems Dapatkan semua item yang harus dilakukan Tidak ada Array item yang harus dilakukan
GET /api/todoitems/{id} Mendapatkan item menurut ID Tidak ada Item tugas
POST /api/todoitems Menambahkan item baru Item tugas Item tugas
PUT /api/todoitems/{id} Memperbarui item yang sudah ada Item tugas Tidak ada
DELETE /api/todoitems/{id}     Hapus item Tidak ada Tidak ada

Diagram berikut menunjukkan desain aplikasi.

Klien diwakili oleh kotak di sebelah kiri. Ini mengirimkan permintaan dan menerima respons dari aplikasi, kotak yang digambar di sebelah kanan. Dalam kotak aplikasi, tiga kotak mewakili pengontrol, model, dan lapisan akses data. Permintaan masuk ke pengontrol aplikasi, dan operasi baca/tulis terjadi antara pengontrol dan lapisan akses data. Model diserialisasikan dan dikembalikan ke klien dalam respons.

Prasyarat

Membuat proyek web

  • Pada menu File, pilih Proyek>Baru.
  • Pilih templat ASP.NET Core Web API dan klik Berikutnya.
  • Beri nama proyek TodoApi dan klik Buat.
  • Dalam dialog Buat Aplikasi Web ASP.NET Core baru , konfirmasikan bahwa .NET Core dan ASP.NET Core 5.0 dipilih. Pilih templat API dan klik Buat.

Dialog proyek baru VS

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bawah Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Menguji proyek

Templat proyek membuat WeatherForecast API dengan dukungan untuk Swagger.

Tekan Ctrl+F5 untuk menjalankan tanpa debugger.

Visual Studio menampilkan dialog berikut saat proyek belum dikonfigurasi untuk menggunakan SSL:

Proyek ini dikonfigurasi untuk menggunakan SSL. Untuk menghindari peringatan SSL di browser, Anda dapat memilih untuk mempercayai sertifikat yang ditandatangani sendiri yang telah dihasilkan IIS Express. Apakah Anda ingin mempercayai sertifikat SSL IIS Express?

Pilih Ya jika Anda mempercayai sertifikat IIS Express SSL.

Dialog berikut ditampilkan:

Dialog peringatan keamanan

Pilih Ya jika Anda setuju untuk mempercayai sertifikat pengembangan.

Untuk informasi tentang mempercayai browser Firefox, lihat Kesalahan sertifikat Firefox SEC_ERROR_INADEQUATE_KEY_USAGE.

Visual Studio meluncurkan:

  • Server web IIS Express.
  • Browser default dan menavigasi ke https://localhost:<port>/swagger/index.html, di mana <port> adalah nomor port yang dipilih secara acak.

Halaman Swagger /swagger/index.html ditampilkan. Pilih GET>Try it out>Execute. Halaman menampilkan:

  • Perintah Curl untuk menguji WEATHERForecast API.
  • URL untuk menguji WEATHERForecast API.
  • Kode respons, isi, dan header.
  • Kotak daftar drop-down dengan jenis media dan nilai contoh dan skema.

Jika halaman Swagger tidak muncul, lihat masalah GitHub ini.

Swagger digunakan untuk menghasilkan halaman dokumentasi dan bantuan yang berguna untuk API web. Tutorial ini berfokus pada pembuatan API web. Untuk informasi selengkapnya tentang Swagger, lihat dokumentasi API web ASP.NET Core dengan Swagger / OpenAPI.

Salin dan tempel URL Permintaan di browser: https://localhost:<port>/weatherforecast

JSON yang mirip dengan berikut ini dikembalikan:

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

Memperbarui launchUrl

Di Properties\launchSettings.json, perbarui launchUrl dari "swagger" ke "api/todoitems":

"launchUrl": "api/todoitems",

Karena Swagger akan dihapus, markup sebelumnya mengubah URL yang diluncurkan ke metode GET pengontrol yang ditambahkan di bagian berikut.

Menambahkan kelas model

Model adalah sekumpulan kelas yang mewakili data yang dikelola aplikasi. Model untuk aplikasi ini adalah satu TodoItem kelas.

  • Di Penjelajah Solusi, klik kanan proyek. Pilih Tambahkan>Folder Baru. Beri nama folder Models.

  • Models Klik kanan folder dan pilih Tambahkan>Kelas. Beri nama kelas TodoItem dan pilih Tambahkan.

  • Ganti kode templat dengan yang berikut ini:

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

Properti Id berfungsi sebagai kunci unik dalam database relasional.

Kelas model dapat pergi ke mana saja dalam proyek, tetapi Models folder digunakan oleh konvensi.

Menambahkan konteks database

Konteks database adalah kelas utama yang mengoordinasikan fungsionalitas Kerangka Kerja Entitas untuk model data. Kelas ini dibuat dengan berasal dari Microsoft.EntityFrameworkCore.DbContext kelas .

Menambahkan paket NuGet

  • Dari menu Alat , pilih Manajer > Paket NuGet Kelola Paket NuGet untuk Solusi.
  • Pilih tab Telusuri , lalu masukkan Microsoft.EntityFrameworkCore.InMemory di kotak pencarian.
  • Pilih Microsoft.EntityFrameworkCore.InMemory di panel kiri.
  • Pilih kotak centang Proyek di panel kanan lalu pilih Instal.

Pengelola Paket NuGet

Menambahkan konteks database TodoContext

  • Models Klik kanan folder dan pilih Tambahkan>Kelas. Beri nama kelas TodoContext dan klik Tambahkan.

  • Masukkan kode berikut:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; }
    }
}

Mendaftarkan konteks database

Dalam ASP.NET Core, layanan seperti konteks DB harus terdaftar dengan kontainer injeksi dependensi (DI ). Kontainer menyediakan layanan untuk pengontrol.

Perbarui Startup.cs dengan kode berikut:

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

Kode sebelumnya:

  • Menghapus panggilan Swagger.
  • Menghapus deklarasi yang tidak digunakan using .
  • Menambahkan konteks database ke kontainer DI.
  • Menentukan bahwa konteks database akan menggunakan database dalam memori.

Perancah pengontrol

  • Klik kanan folder Pengontrol .

  • Pilih Tambahkan>Item Perancah Baru.

  • Pilih Pengontrol API dengan tindakan, menggunakan Kerangka Kerja Entitas, lalu pilih Tambahkan.

  • Dalam dialog Tambahkan Pengontrol API dengan tindakan, menggunakan Kerangka Kerja Entitas :

    • Pilih TodoItem (TodoApi.Models) di kelas Model.
    • Pilih TodoContext (TodoApi.Models) di kelas Konteks data.
    • Pilih Tambahkan.

Kode yang dihasilkan:

  • Menandai kelas dengan [ApiController] atribut . Atribut ini menunjukkan bahwa pengontrol merespons permintaan API web. Untuk informasi tentang perilaku tertentu yang diaktifkan atribut, lihat Membuat API web dengan ASP.NET Core.
  • Menggunakan DI untuk menyuntikkan konteks database (TodoContext) ke dalam pengontrol. Konteks database digunakan dalam setiap metode CRUD di pengontrol.

Templat ASP.NET Core untuk:

  • Pengontrol dengan tampilan disertakan [action] dalam templat rute.
  • Pengontrol API tidak disertakan [action] dalam templat rute.

[action] Saat token tidak berada dalam templat rute, nama tindakan dikecualikan dari rute. Artinya, nama metode terkait tindakan tidak digunakan dalam rute yang cocok.

Memperbarui metode pembuatan PostTodoItem

Perbarui pernyataan pengembalian dalam PostTodoItem untuk menggunakan operator nameof :

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

Kode sebelumnya adalah metode HTTP POST, seperti yang ditunjukkan [HttpPost] oleh atribut . Metode ini mendapatkan nilai item yang harus dilakukan dari isi permintaan HTTP.

Untuk informasi selengkapnya, lihat Perutean atribut dengan atribut Http[Verb].

Metode CreatedAtAction:

  • Mengembalikan kode status HTTP 201 jika berhasil. HTTP 201 adalah respons standar untuk metode HTTP POST yang membuat sumber daya baru di server.
  • Menambahkan header Lokasi ke respons. Header Location menentukan URI item yang baru dibuat untuk dilakukan. Untuk informasi selengkapnya, lihat 10.2.2 201 Dibuat.
  • Mereferensikan GetTodoItem tindakan untuk membuat Location URI header. Kata kunci C# nameof digunakan untuk menghindari hard-coding nama tindakan dalam CreatedAtAction panggilan.

Pasang Postman

Tutorial ini menggunakan Postman untuk menguji API web.

  • Pasang Postman
  • Mulai aplikasi web.
  • Mulai Postman.
  • Nonaktifkan verifikasi sertifikat SSL:
    • Postman untuk Windows: PilihPengaturanFile> (tab Umum), nonaktifkan verifikasi sertifikat SSL.
    • Postman untuk macOS: PilihPengaturanPostman> (tab Umum), nonaktifkan verifikasi sertifikat SSL.

      Peringatan

      Aktifkan kembali verifikasi sertifikat SSL setelah menguji pengontrol.

Uji PostTodoItem dengan Postman

  • Buat permintaan baru.

  • Atur metode HTTP ke POST.

  • Atur URI ke https://localhost:<port>/api/todoitems. Contohnya:https://localhost:5001/api/todoitems

  • Pilih tab Isi.

  • Pilih tombol radio mentah .

  • Atur jenis ke JSAKTIF (aplikasi/json).

  • Di isi permintaan masukkan JSAKTIF untuk item yang harus dilakukan:

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

  • Pilih Kirim.

    Postman dengan permintaan buat

Menguji URI header lokasi

URI header lokasi dapat diuji di browser. Salin dan tempel URI header lokasi ke browser.

Untuk menguji di Postman:

  • Pilih tab Header di panel Respons .

  • Salin nilai header Lokasi :

    Tab Header konsol Postman

  • Atur metode HTTP ke GET.

  • Atur URI ke https://localhost:<port>/api/todoitems/1. Contohnya:https://localhost:5001/api/todoitems/1

  • Pilih Kirim.

Memeriksa metode GET

Dua titik akhir GET diimplementasikan:

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

Uji aplikasi dengan memanggil dua titik akhir dari browser atau Postman. Contohnya:

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

Respons yang mirip dengan berikut ini diproduksi oleh panggilan ke GetTodoItems:

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

Uji Dapatkan dengan Postman

  • Buat permintaan baru.
  • Atur metode HTTP ke GET.
  • Atur URI permintaan ke https://localhost:<port>/api/todoitems. Contohnya:https://localhost:5001/api/todoitems
  • Atur Tampilan dua panel di Postman.
  • Pilih Kirim.

Aplikasi ini menggunakan database dalam memori. Jika aplikasi dihentikan dan dimulai, permintaan GET sebelumnya tidak akan mengembalikan data apa pun. Jika tidak ada data yang dikembalikan, POST data ke aplikasi.

Perutean dan jalur URL

Atribut [HttpGet] menunjukkan metode yang merespons permintaan HTTP GET. Jalur URL untuk setiap metode dibangun sebagai berikut:

  • Mulailah dengan string templat di atribut pengontrol Route :

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

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

  • Ganti [controller] dengan nama pengontrol, yang menurut konvensi adalah nama kelas pengontrol dikurangi akhiran "Pengontrol". Untuk sampel ini, nama kelas pengontrol adalah TodoItemsController, sehingga nama pengontrolnya adalah "TodoItems". perutean ASP.NET Core tidak peka huruf besar/kecil.

  • [HttpGet] Jika atribut memiliki templat rute (misalnya, [HttpGet("products")]), tambahkan ke jalur. Sampel ini tidak menggunakan templat. Untuk informasi selengkapnya, lihat Perutean atribut dengan atribut Http[Verb].

Dalam metode berikut GetTodoItem , "{id}" adalah variabel tempat penampung untuk pengidentifikasi unik item yang harus dilakukan. Ketika GetTodoItem dipanggil, nilai "{id}" dalam URL diberikan ke metode dalam parameternya id .

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

Nilai yang dikembalikan

Jenis pengembalian metode GetTodoItems dan GetTodoItem adalah jenis ActionResult<T>. ASP.NET Core secara otomatis menserialisasikan objek ke JSAKTIF dan menulis JSON ke dalam isi pesan respons. Kode respons untuk jenis pengembalian ini adalah 200 OK, dengan asumsi tidak ada pengecualian yang tidak tertangani. Pengecualian yang tidak tertangani diterjemahkan ke dalam kesalahan 5xx.

ActionResult jenis pengembalian dapat mewakili berbagai kode status HTTP. Misalnya, GetTodoItem dapat mengembalikan dua nilai status yang berbeda:

  • Jika tidak ada item yang cocok dengan ID yang diminta, metode mengembalikan kode kesalahan status NotFound404.
  • Jika tidak, metode mengembalikan 200 dengan JSisi respons ON. Mengembalikan item hasil dalam respons HTTP 200.

Metode PutTodoItem

Periksa metode :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 mirip PostTodoItemdengan , kecuali menggunakan HTTP PUT. Responsnya adalah 204 (Tanpa Konten). Menurut spesifikasi HTTP, permintaan PUT mengharuskan klien untuk mengirim seluruh entitas yang diperbarui, bukan hanya perubahan. Untuk mendukung pembaruan parsial, gunakan HTTP PATCH.

Jika Anda mendapatkan kesalahan saat memanggil PutTodoItem, panggil GET untuk memastikan ada item dalam database.

Menguji metode PutTodoItem

Sampel ini menggunakan database dalam memori yang harus diinisialisasi setiap kali aplikasi dimulai. Harus ada item dalam database sebelum Anda melakukan panggilan PUT. Panggil GET untuk memastikan ada item dalam database sebelum melakukan panggilan PUT.

Perbarui item yang harus dilakukan yang memiliki Id = 1 dan atur namanya ke "feed fish":

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

Gambar berikut menunjukkan pembaruan Postman:

Konsol Postman memperlihatkan respons 204 (Tanpa Konten)

Metode DeleteTodoItem

Periksa metode :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();
}

Menguji metode DeleteTodoItem

Gunakan Postman untuk menghapus item yang harus dilakukan:

  • Atur metode ke DELETE.
  • Atur URI objek yang akan dihapus (misalnya https://localhost:5001/api/todoitems/1).
  • Pilih Kirim.

Mencegah pengiriman berlebih

Saat ini aplikasi sampel mengekspos seluruh TodoItem objek. Aplikasi produksi biasanya membatasi data yang diinput dan dikembalikan menggunakan subset model. Ada beberapa alasan di balik ini dan keamanan adalah yang utama. Subset model biasanya disebut sebagai Objek Transfer Data (DTO), model input, atau model tampilan. DTO digunakan dalam artikel ini.

DTO dapat digunakan untuk:

  • Mencegah pengiriman berlebih.
  • Sembunyikan properti yang tidak seharusnya dilihat klien.
  • Hilangkan beberapa properti untuk mengurangi ukuran payload.
  • Meratakan grafik objek yang berisi objek berlapis. Grafik objek yang diratakan bisa lebih nyaman untuk klien.

Untuk menunjukkan pendekatan DTO, perbarui TodoItem kelas untuk menyertakan bidang rahasia:

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

Bidang rahasia perlu disembunyikan dari aplikasi ini, tetapi aplikasi administratif dapat memilih untuk mengeksposnya.

Verifikasi bahwa Anda dapat memposting dan mendapatkan bidang rahasia.

Buat model DTO:

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

TodoItemsController Perbarui untuk menggunakan TodoItemDTO:

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

Verifikasi bahwa Anda tidak dapat memposting atau mendapatkan bidang rahasia.

Memanggil API web dengan JavaScript

Lihat Tutorial: Memanggil API web ASP.NET Core dengan JavaScript.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Membuat proyek API web.
  • Tambahkan kelas model dan konteks database.
  • Perancah pengontrol dengan metode CRUD.
  • Mengonfigurasi perutean, jalur URL, dan mengembalikan nilai.
  • Panggil API web dengan Postman.

Pada akhirnya, Anda memiliki API web yang dapat mengelola item "harus dilakukan" yang disimpan dalam database.

Gambaran Umum

Tutorial ini membuat API berikut:

API Deskripsi Isi permintaan Isi Respons
GET /api/todoitems Dapatkan semua item yang harus dilakukan Tidak ada Array item yang harus dilakukan
GET /api/todoitems/{id} Mendapatkan item menurut ID Tidak ada Item tugas
POST /api/todoitems Menambahkan item baru Item tugas Item tugas
PUT /api/todoitems/{id} Memperbarui item yang sudah ada Item tugas Tidak ada
DELETE /api/todoitems/{id}     Hapus item Tidak ada Tidak ada

Diagram berikut menunjukkan desain aplikasi.

Klien diwakili oleh kotak di sebelah kiri. Ini mengirimkan permintaan dan menerima respons dari aplikasi, kotak yang digambar di sebelah kanan. Dalam kotak aplikasi, tiga kotak mewakili pengontrol, model, dan lapisan akses data. Permintaan masuk ke pengontrol aplikasi, dan operasi baca/tulis terjadi antara pengontrol dan lapisan akses data. Model diserialisasikan dan dikembalikan ke klien dalam respons.

Prasyarat

Membuat proyek web

  • Pada menu File, pilih Proyek>Baru.
  • Pilih templat ASP.NET Core Web Application dan klik Berikutnya.
  • Beri nama proyek TodoApi dan klik Buat.
  • Dalam dialog Buat Aplikasi Web ASP.NET Core baru , konfirmasikan bahwa .NET Core dan ASP.NET Core 3.1 dipilih. Pilih templat API dan klik Buat.

Dialog proyek baru VS

Catatan

Untuk panduan tentang menambahkan paket ke aplikasi .NET, lihat artikel di bawah Menginstal dan mengelola paket di Alur kerja konsumsi paket (dokumentasi NuGet). Konfirmasikan versi paket yang benar di NuGet.org.

Menguji API

Templat proyek membuat WeatherForecast API. Get Panggil metode dari browser untuk menguji aplikasi.

Tekan Ctrl+F5 untuk menjalankan aplikasi. Visual Studio meluncurkan browser dan menavigasi ke https://localhost:<port>/weatherforecast, di mana <port> adalah nomor port yang dipilih secara acak.

Jika Anda mendapatkan kotak dialog yang menanyakan apakah Anda harus mempercayai sertifikat IIS Express, pilih Ya. Dalam dialog Peringatan Keamanan yang muncul berikutnya, pilih Ya.

JSON yang mirip dengan berikut ini dikembalikan:

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

Menambahkan kelas model

Model adalah sekumpulan kelas yang mewakili data yang dikelola aplikasi. Model untuk aplikasi ini adalah satu TodoItem kelas.

  • Di Penjelajah Solusi, klik kanan proyek. Pilih Tambahkan>Folder Baru. Beri nama folder Models.

  • Models Klik kanan folder dan pilih Tambahkan>Kelas. Beri nama kelas TodoItem dan pilih Tambahkan.

  • Ganti kode templat dengan kode berikut:

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

Properti Id berfungsi sebagai kunci unik dalam database relasional.

Kelas model dapat pergi ke mana saja dalam proyek, tetapi Models folder digunakan oleh konvensi.

Menambahkan konteks database

Konteks database adalah kelas utama yang mengoordinasikan fungsionalitas Kerangka Kerja Entitas untuk model data. Kelas ini dibuat dengan berasal dari Microsoft.EntityFrameworkCore.DbContext kelas .

Menambahkan paket NuGet

  • Dari menu Alat , pilih Manajer > Paket NuGet Kelola Paket NuGet untuk Solusi.
  • Pilih tab Telusuri , lalu masukkan Microsoft.EntityFrameworkCore.InMemory di kotak pencarian.
  • Pilih Microsoft.EntityFrameworkCore.InMemory di panel kiri.
  • Pilih kotak centang Proyek di panel kanan lalu pilih Instal.

Pengelola Paket NuGet

Menambahkan konteks database TodoContext

  • Models Klik kanan folder dan pilih Tambahkan>Kelas. Beri nama kelas TodoContext dan klik Tambahkan.

  • Masukkan kode berikut:

    using Microsoft.EntityFrameworkCore;

namespace TodoApi.Models
{
    public class TodoContext : DbContext
    {
        public TodoContext(DbContextOptions<TodoContext> options)
            : base(options)
        {
        }

        public DbSet<TodoItem> TodoItems { get; set; }
    }
}

Mendaftarkan konteks database

Dalam ASP.NET Core, layanan seperti konteks DB harus terdaftar dengan kontainer injeksi dependensi (DI ). Kontainer menyediakan layanan untuk pengontrol.

Perbarui Startup.cs dengan kode yang disorot berikut:

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

Kode sebelumnya:

  • Menghapus deklarasi yang tidak digunakan using .
  • Menambahkan konteks database ke kontainer DI.
  • Menentukan bahwa konteks database akan menggunakan database dalam memori.

Perancah pengontrol

  • Klik kanan folder Pengontrol .

  • Pilih Tambahkan>Item Perancah Baru.

  • Pilih Pengontrol API dengan tindakan, menggunakan Kerangka Kerja Entitas, lalu pilih Tambahkan.

  • Dalam dialog Tambahkan Pengontrol API dengan tindakan, menggunakan Kerangka Kerja Entitas :

    • Pilih TodoItem (TodoApi.Models) di kelas Model.
    • Pilih TodoContext (TodoApi.Models) di kelas Konteks data.
    • Pilih Tambahkan.

Kode yang dihasilkan:

  • Menandai kelas dengan [ApiController] atribut . Atribut ini menunjukkan bahwa pengontrol merespons permintaan API web. Untuk informasi tentang perilaku tertentu yang diaktifkan atribut, lihat Membuat API web dengan ASP.NET Core.
  • Menggunakan DI untuk menyuntikkan konteks database (TodoContext) ke dalam pengontrol. Konteks database digunakan dalam setiap metode CRUD di pengontrol.

Templat ASP.NET Core untuk:

  • Pengontrol dengan tampilan disertakan [action] dalam templat rute.
  • Pengontrol API tidak disertakan [action] dalam templat rute.

[action] Saat token tidak berada dalam templat rute, nama tindakan dikecualikan dari rute. Artinya, nama metode terkait tindakan tidak digunakan dalam rute yang cocok.

Memeriksa metode pembuatan PostTodoItem

Ganti pernyataan pengembalian dalam PostTodoItem untuk menggunakan operator nameof :

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

Kode sebelumnya adalah metode HTTP POST, seperti yang ditunjukkan [HttpPost] oleh atribut . Metode ini mendapatkan nilai item yang harus dilakukan dari isi permintaan HTTP.

Untuk informasi selengkapnya, lihat Perutean atribut dengan atribut Http[Verb].

Metode CreatedAtAction:

  • Mengembalikan kode status HTTP 201 jika berhasil. HTTP 201 adalah respons standar untuk metode HTTP POST yang membuat sumber daya baru di server.
  • Menambahkan header Lokasi ke respons. Header Location menentukan URI item yang baru dibuat untuk dilakukan. Untuk informasi selengkapnya, lihat 10.2.2 201 Dibuat.
  • Mereferensikan GetTodoItem tindakan untuk membuat Location URI header. Kata kunci C# nameof digunakan untuk menghindari hard-coding nama tindakan dalam CreatedAtAction panggilan.

Pasang Postman

Tutorial ini menggunakan Postman untuk menguji API web.

  • Pasang Postman
  • Mulai aplikasi web.
  • Mulai Postman.
  • Nonaktifkan verifikasi sertifikat SSL:
    • Postman untuk Windows: Postman untukPengaturanFile> Windows (tab Umum), nonaktifkan verifikasi sertifikat SSL.
    • Postman untuk macOS: Postman untukPengaturan Windows Postman> (tab Umum), nonaktifkan verifikasi sertifikat SSL.

      Peringatan

      Aktifkan kembali verifikasi sertifikat SSL setelah menguji pengontrol.

Uji PostTodoItem dengan Postman

  • Buat permintaan baru.

  • Atur metode HTTP ke POST.

  • Atur URI ke https://localhost:<port>/api/todoitems. Contohnya:https://localhost:5001/api/todoitems

  • Pilih tab Isi.

  • Pilih tombol radio mentah .

  • Atur jenis ke JSAKTIF (aplikasi/json).

  • Di isi permintaan masukkan JSAKTIF untuk item yang harus dilakukan:

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

  • Pilih Kirim.

    Postman dengan permintaan buat

Menguji URI header lokasi dengan Postman

  • Pilih tab Header di panel Respons .

  • Salin nilai header Lokasi :

    Tab Header konsol Postman

  • Atur metode HTTP ke GET.

  • Atur URI ke https://localhost:<port>/api/todoitems/1. Contohnya:https://localhost:5001/api/todoitems/1

  • Pilih Kirim.

Memeriksa metode GET

Metode ini mengimplementasikan dua titik akhir GET:

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

Uji aplikasi dengan memanggil dua titik akhir dari browser atau Postman. Contohnya:

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

Respons yang mirip dengan berikut ini diproduksi oleh panggilan ke GetTodoItems:

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

Uji Dapatkan dengan Postman

  • Buat permintaan baru.
  • Atur metode HTTP ke GET.
  • Atur URI permintaan ke https://localhost:<port>/api/todoitems. Contohnya:https://localhost:5001/api/todoitems
  • Atur Tampilan dua panel di Postman.
  • Pilih Kirim.

Aplikasi ini menggunakan database dalam memori. Jika aplikasi dihentikan dan dimulai, permintaan GET sebelumnya tidak akan mengembalikan data apa pun. Jika tidak ada data yang dikembalikan, POST data ke aplikasi.

Perutean dan jalur URL

Atribut [HttpGet] menunjukkan metode yang merespons permintaan HTTP GET. Jalur URL untuk setiap metode dibangun sebagai berikut:

  • Mulailah dengan string templat di atribut pengontrol Route :

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

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

  • Ganti [controller] dengan nama pengontrol, yang menurut konvensi adalah nama kelas pengontrol dikurangi akhiran "Pengontrol". Untuk sampel ini, nama kelas pengontrol adalah TodoItemsController, sehingga nama pengontrolnya adalah "TodoItems". perutean ASP.NET Core tidak peka huruf besar/kecil.

  • [HttpGet] Jika atribut memiliki templat rute (misalnya, [HttpGet("products")]), tambahkan ke jalur. Sampel ini tidak menggunakan templat. Untuk informasi selengkapnya, lihat Perutean atribut dengan atribut Http[Verb].

Dalam metode berikut GetTodoItem , "{id}" adalah variabel tempat penampung untuk pengidentifikasi unik item yang harus dilakukan. Ketika GetTodoItem dipanggil, nilai "{id}" dalam URL diberikan ke metode dalam parameternya id .

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

Nilai yang dikembalikan

Jenis pengembalian metode GetTodoItems dan GetTodoItem adalah jenis ActionResult<T>. ASP.NET Core secara otomatis menserialisasikan objek ke JSAKTIF dan menulis JSON ke dalam isi pesan respons. Kode respons untuk jenis pengembalian ini adalah 200, dengan asumsi tidak ada pengecualian yang tidak tertangani. Pengecualian yang tidak tertangani diterjemahkan ke dalam kesalahan 5xx.

ActionResult jenis pengembalian dapat mewakili berbagai kode status HTTP. Misalnya, GetTodoItem dapat mengembalikan dua nilai status yang berbeda:

  • Jika tidak ada item yang cocok dengan ID yang diminta, metode mengembalikan kode kesalahan 404 NotFound .
  • Jika tidak, metode mengembalikan 200 dengan JSisi respons ON. Mengembalikan item hasil dalam respons HTTP 200.

Metode PutTodoItem

Periksa metode :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 mirip PostTodoItemdengan , kecuali menggunakan HTTP PUT. Responsnya adalah 204 (Tanpa Konten). Menurut spesifikasi HTTP, permintaan PUT mengharuskan klien untuk mengirim seluruh entitas yang diperbarui, bukan hanya perubahan. Untuk mendukung pembaruan parsial, gunakan HTTP PATCH.

Jika Anda mendapatkan kesalahan saat memanggil PutTodoItem, panggil GET untuk memastikan ada item dalam database.

Menguji metode PutTodoItem

Sampel ini menggunakan database dalam memori yang harus diinisialisasi setiap kali aplikasi dimulai. Harus ada item dalam database sebelum Anda melakukan panggilan PUT. Panggil GET untuk memastikan ada item dalam database sebelum melakukan panggilan PUT.

Perbarui item yang harus dilakukan yang memiliki Id = 1 dan atur namanya ke "umpan ikan":

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

Gambar berikut menunjukkan pembaruan Postman:

Konsol Postman memperlihatkan respons 204 (Tanpa Konten)

Metode DeleteTodoItem

Periksa metode :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;
}

Menguji metode DeleteTodoItem

Gunakan Postman untuk menghapus item yang harus dilakukan:

  • Atur metode ke DELETE.
  • Atur URI objek yang akan dihapus (misalnya https://localhost:5001/api/todoitems/1).
  • Pilih Kirim.

Mencegah pengiriman berlebih

Saat ini aplikasi sampel mengekspos seluruh TodoItem objek. Aplikasi produksi biasanya membatasi data yang diinput dan dikembalikan menggunakan subset model. Ada beberapa alasan di balik ini dan keamanan adalah yang utama. Subset model biasanya disebut sebagai Objek Transfer Data (DTO), model input, atau model tampilan. DTO digunakan dalam artikel ini.

DTO dapat digunakan untuk:

  • Mencegah pengiriman berlebih.
  • Sembunyikan properti yang tidak seharusnya dilihat klien.
  • Hilangkan beberapa properti untuk mengurangi ukuran payload.
  • Meratakan grafik objek yang berisi objek berlapis. Grafik objek yang diratakan bisa lebih nyaman untuk klien.

Untuk menunjukkan pendekatan DTO, perbarui TodoItem kelas untuk menyertakan bidang rahasia:

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

Bidang rahasia perlu disembunyikan dari aplikasi ini, tetapi aplikasi administratif dapat memilih untuk mengeksposnya.

Verifikasi bahwa Anda dapat memposting dan mendapatkan bidang rahasia.

Buat model DTO:

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

TodoItemsController Perbarui untuk menggunakan 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
        };       
}

Verifikasi bahwa Anda tidak dapat memposting atau mendapatkan bidang rahasia.

Memanggil API web dengan JavaScript

Lihat Tutorial: Memanggil API web ASP.NET Core dengan JavaScript.

Menambahkan dukungan autentikasi ke API web

ASP.NET Core Identity menambahkan fungsionalitas login antarmuka pengguna (UI) ke aplikasi web ASP.NET Core. Untuk mengamankan API web dan SPAs, gunakan salah satu hal berikut ini:

Duende Identity Server adalah kerangka kerja OpenID Connect dan OAuth 2.0 untuk ASP.NET Core. Duende Identity Server memungkinkan fitur keamanan berikut:

  • Autentikasi sebagai Layanan (AaaS)
  • Akses menyeluruh (SSO) melalui beberapa jenis aplikasi
  • Kontrol akses untuk API
  • Gateway Federasi

Penting

Duende Software mungkin mengharuskan Anda membayar biaya lisensi untuk penggunaan produksi Duende Identity Server. Untuk informasi selengkapnya, lihat Migrasi dari ASP.NET Core 5.0 ke 6.0.

Untuk informasi selengkapnya, lihat dokumentasi Duende Identity Server (situs web Perangkat Lunak Duende).

Menerbitkan ke Azure

Untuk informasi tentang penyebaran ke Azure, lihat Mulai Cepat: Menyebarkan aplikasi web ASP.NET.

Sumber Daya Tambahan:

Lihat atau unduh kode sampel untuk tutorial ini. Lihat cara mengunduh.

Untuk informasi lebih lanjut, lihat sumber daya berikut ini: