ASP.NET Web API 2.1'de BSON Desteği

Makale
07/13/2023

Bu konuda, BSON'un Web API denetleyicinizde (sunucu tarafında) ve bir .NET istemci uygulamasında nasıl kullanılacağı gösterilmektedir. Web API 2.1, BSON desteği sağlar.

BSON nedir?

BSON bir ikili serileştirme biçimidir. "BSON", "İkili JSON" anlamına gelir, ancak BSON ve JSON çok farklı serileştirilir. Nesneler JSON'a benzer şekilde ad-değer çiftleri olarak temsil edildiğinden BSON "JSON benzeridir". JSON'un aksine sayısal veri türleri dize olarak değil bayt olarak depolanır

BSON basit, kolay taranacak ve kodlaması/kodunu çözmesi hızlı olacak şekilde tasarlanmıştır.

BSON, boyut olarak JSON ile karşılaştırılabilir. Verilere bağlı olarak bir BSON yükü, JSON yükünden daha küçük veya daha büyük olabilir. İkili veriler base64 ile kodlanmadığından, görüntü dosyası gibi ikili verileri serileştirmek için BSON, JSON'dan daha küçüktür.
Öğelere bir uzunluk alanı eklendiği için BSON belgeleri kolayca taranabilir, bu nedenle ayrıştırıcı öğelerin kodunu çözmeden atlayabilir.
Sayısal veri türleri dize olarak değil sayı olarak depolandığından kodlama ve kod çözme verimlidir.

.NET istemci uygulamaları gibi yerel istemciler, JSON veya XML gibi metin tabanlı biçimler yerine BSON kullanmaktan yararlanabilir. JavaScript, JSON yükünü doğrudan dönüştürebildiğinden, tarayıcı istemcileri için büyük olasılıkla JSON ile devam etmek isteyeceksiniz.

Neyse ki Web API'niz içerik anlaşması kullandığından, API'niz her iki biçimi de destekleyebilir ve istemcinin seçim yapmasına izin verebilir.

Sunucuda BSON'yi etkinleştirme

Web API yapılandırmanızda , BsonMediaTypeFormatter'ı biçimlendiriciler koleksiyonuna ekleyin.

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

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

Şimdi istemci "application/bson" isteğinde bulunursa Web API'sinde BSON biçimlendiricisi kullanılır.

BSON'u diğer medya türleriyle ilişkilendirmek için bunları SupportedMediaTypes koleksiyonuna ekleyin. Aşağıdaki kod desteklenen medya türlerine "application/vnd.contoso" ekler:

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

Örnek HTTP Oturumu

Bu örnekte, aşağıdaki model sınıfının yanı sıra basit bir Web API denetleyicisi kullanacağız:

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

İstemci aşağıdaki HTTP isteğini gönderebilir:

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

Yanıt şu şekildedir:

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

Burada ikili verileri "." karakterleriyle değiştirdim. Fiddler'ın aşağıdaki ekran görüntüsünde ham onaltılık değerler gösterilir.

HttpClient ile BSON Kullanma

.NET istemci uygulamaları BSON biçimlendiricisini HttpClient ile kullanabilir. HttpClient hakkında daha fazla bilgi için bkz. .NET İstemcisinden Web API'sini Çağırma.

Aşağıdaki kod, BSON kabul eden bir GET isteği gönderir ve ardından yanıttaki BSON yükünü seri durumdan çıkartır.

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

Sunucudan BSON istemek için Accept üst bilgisini "application/bson" olarak ayarlayın:

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

Yanıt gövdesinin seri durumdan çıkarılması için BsonMediaTypeFormatter'ı kullanın. Bu biçimlendirici varsayılan biçimlendiriciler koleksiyonunda olmadığından, yanıt gövdesini okurken bunu belirtmeniz gerekir:

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

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

Sonraki örnek, BSON içeren bir POST isteğinin nasıl gönderildiğini gösterir.

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

Bu kodun çoğu önceki örnekle aynıdır. Ancak PostAsync yönteminde, biçimlendirici olarak BsonMediaTypeFormatter'ı belirtin:

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

Top-Level Temel Türleri Seri Hale Getirme

Her BSON belgesi, anahtar/değer çiftlerinin listesidir. BSON belirtimi, tamsayı veya dize gibi tek bir ham değeri seri hale getirme söz dizimini tanımlamaz.

Bu sınırlamayı geçici olarak çözmek için , BsonMediaTypeFormatter ilkel türleri özel bir durum olarak ele alır. Seri hale getirmeden önce, değeri "Value" anahtarıyla bir anahtar/değer çiftine dönüştürür. Örneğin, API denetleyicinizin bir tamsayı döndürdüğü varsayabilirsiniz:

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

BSON biçimlendiricisi seri hale getirmeden önce bunu aşağıdaki anahtar/değer çiftine dönüştürür:

{ "Value": 42 }

Seri durumdan çıkardığınızda, biçimlendirici verileri özgün değere geri dönüştürür. Ancak, web API'niz ham değerler döndürüyorsa farklı bir BSON ayrıştırıcısı kullanan istemcilerin bu durumu işlemesi gerekir. Genel olarak ham değerler yerine yapılandırılmış verileri döndürmeyi göz önünde bulundurmalısınız.

Ek Kaynaklar

Web API'si BSON Örneği

Medya Biçimlendiricileri

Aracılığıyla paylaş