Bagikan melalui

Dukungan BSON di ASP.NET Web API 2.1

Topik ini menunjukkan cara menggunakan BSON di pengontrol API Web Anda (sisi server) dan di aplikasi klien .NET. Web API 2.1 memperkenalkan dukungan untuk BSON.

Apa itu BSON?

BSON adalah format serialisasi biner. "BSON" adalah singkatan dari "Binary JSON", tetapi BSON dan JSON diserialisasikan dengan sangat berbeda. BSON adalah "seperti JSON", karena objek direpresentasikan sebagai pasangan nama-nilai, mirip dengan JSON. Tidak seperti JSON, jenis data numerik disimpan sebagai byte, bukan string

BSON dirancang agar ringan, mudah dipindai, dan cepat dikodekan/didekodekan.

  • Ukuran BSON sebanding dengan JSON. Bergantung pada datanya, payload BSON mungkin lebih kecil atau lebih besar dari payload JSON. Untuk menserialisasikan data biner, seperti file gambar, BSON lebih kecil dari JSON, karena data biner tidak dikodekan base64.
  • Dokumen BSON mudah dipindai karena elemen diawali dengan bidang panjang, sehingga pengurai dapat melewati elemen tanpa mendekodenya.
  • Pengodean dan pendekodean efisien, karena jenis data numerik disimpan sebagai angka, bukan string.

Klien asli, seperti aplikasi klien .NET, dapat memperoleh manfaat dari penggunaan BSON sebagai pengganti format berbasis teks seperti JSON atau XML. Untuk klien browser, Anda mungkin ingin tetap menggunakan JSON, karena JavaScript dapat langsung mengonversi payload JSON.

Untungnya, Web API menggunakan negosiasi konten, sehingga API Anda dapat mendukung kedua format dan membiarkan klien memilih.

Mengaktifkan BSON di Server

Dalam konfigurasi API Web Anda, tambahkan BsonMediaTypeFormatter ke koleksi pemformat.

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.Formatters.Add(new BsonMediaTypeFormatter());

        // Other Web API configuration not shown...
    }
}

Sekarang jika klien meminta "application/bson", Web API akan menggunakan formatter BSON.

Untuk mengaitkan BSON dengan jenis media lain, tambahkan ke koleksi SupportedMediaTypes. Kode berikut menambahkan "application/vnd.contoso" ke jenis media yang didukung:

var bson = new BsonMediaTypeFormatter();
bson.SupportedMediaTypes.Add(new MediaTypeHeaderValue("application/vnd.contoso"));
config.Formatters.Add(bson);

Contoh Sesi HTTP

Untuk contoh ini, kita akan menggunakan kelas model berikut ditambah pengontrol Api Web sederhana:

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Author { get; set; }
    public decimal Price { get; set; }
    public DateTime PublicationDate { get; set; }
}

public class BooksController : ApiController
{
    public IHttpActionResult GetBook(int id)
    {
        var book = new Book()
        {
            Id = id,
            Author = "Charles Dickens",
            Title = "Great Expectations",
            Price = 9.95M,
            PublicationDate = new DateTime(2014, 1, 20)
        };

        return Ok(book);
    }
}

Klien mungkin mengirim permintaan HTTP berikut:

GET http://localhost:15192/api/books/1 HTTP/1.1
User-Agent: Fiddler
Host: localhost:15192
Accept: application/bson

Berikut adalah responsnya:

HTTP/1.1 200 OK
Content-Type: application/bson; charset=utf-8
Date: Fri, 17 Jan 2014 01:05:40 GMT
Content-Length: 111

.....Id......Title.....Great Expectations..Author.....Charles Dickens..Price..........PublicationDate.........

Di sini saya telah mengganti data biner dengan karakter ".". Cuplikan layar berikut dari Fiddler menunjukkan nilai heksa mentah.

Cuplikan layar panel jendela memperlihatkan nilai heksa mentah data biner dalam warna hijau di bagian atas dan tengah, dan hitam di bagian bawah.

Menggunakan BSON dengan HttpClient

Aplikasi klien .NET dapat menggunakan formatter BSON dengan HttpClient. Untuk informasi selengkapnya tentang HttpClient, lihat Memanggil API Web Dari Klien .NET.

Kode berikut mengirimkan permintaan GET yang menerima BSON, lalu mendeserialisasi payload BSON dalam respons.

static async Task RunAsync()
{
    using (HttpClient client = new HttpClient())
    {
        client.BaseAddress = new Uri("http://localhost");

        // Set the Accept header for BSON.
        client.DefaultRequestHeaders.Accept.Clear();
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/bson"));

        // Send GET request.
        result = await client.GetAsync("api/books/1");
        result.EnsureSuccessStatusCode();

        // Use BSON formatter to deserialize the result.
        MediaTypeFormatter[] formatters = new MediaTypeFormatter[] {
            new BsonMediaTypeFormatter()
        };

        var book = await result.Content.ReadAsAsync<Book>(formatters);
    }
}

Untuk meminta BSON dari server, atur header Terima ke "application/bson":

client.DefaultRequestHeaders.Accept.Clear();
client.DefaultRequestHeaders.Accept.Add(new  
    MediaTypeWithQualityHeaderValue("application/bson"));

Untuk mendeserialisasi isi respons, gunakan BsonMediaTypeFormatter. Pemformat ini tidak ada dalam koleksi pemformat default, jadi Anda harus menentukannya saat Anda membaca isi respons:

MediaTypeFormatter[] formatters = new MediaTypeFormatter[] {
    new BsonMediaTypeFormatter()
};

var book = await result.Content.ReadAsAsync<Book>(formatters);

Contoh berikutnya menunjukkan cara mengirim permintaan POST yang berisi BSON.

static async Task RunAsync()
{
    using (HttpClient client = new HttpClient())
    {
        client.BaseAddress = new Uri("http://localhost:15192");

        // Set the Accept header for BSON.
        client.DefaultRequestHeaders.Accept.Clear();
        client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/bson"));

        var book = new Book()
        {
            Author = "Jane Austen",
            Title = "Emma",
            Price = 9.95M,
            PublicationDate = new DateTime(1815, 1, 1)
        };

        // POST using the BSON formatter.
        MediaTypeFormatter bsonFormatter = new BsonMediaTypeFormatter();
        var result = await client.PostAsync("api/books", book, bsonFormatter);
        result.EnsureSuccessStatusCode();
    }
}

Sebagian besar kode ini sama dengan contoh sebelumnya. Tetapi dalam metode PostAsync , tentukan BsonMediaTypeFormatter sebagai pemformat :

MediaTypeFormatter bsonFormatter = new BsonMediaTypeFormatter();
var result = await client.PostAsync("api/books", book, bsonFormatter);

Serialisasi Top-Level Jenis Primitif

Setiap dokumen BSON adalah daftar pasangan kunci/nilai. Spesifikasi BSON tidak menentukan sintaksis untuk menserialisasikan satu nilai mentah, seperti bilangan bulat atau string.

Untuk mengatasi batasan ini, BsonMediaTypeFormatter memperlakukan jenis primitif sebagai kasus khusus. Sebelum diserialisasikan, ia mengonversi nilai menjadi pasangan kunci/nilai dengan kunci "Nilai". Misalnya, pengontrol API Anda mengembalikan bilangan bulat:

public class ValuesController : ApiController
{
    public IHttpActionResult Get()
    {
        return Ok(42);
    }
}

Sebelum membuat serialisasi, pemformat BSON mengonversi ini ke pasangan kunci/nilai berikut:

{ "Value": 42 }

Saat Anda mendeserialisasi, pemformat mengonversi data kembali ke nilai asli. Namun, klien yang menggunakan parser BSON yang berbeda perlu menangani kasus ini, jika API web Anda mengembalikan nilai mentah. Secara umum, Anda harus mempertimbangkan untuk mengembalikan data terstruktur, bukan nilai mentah.

Sumber Daya Tambahan

Sampel Web API BSON

Media Formatters

  • Last updated on