Yang Baru di ASP.NET Web API 2.1

oleh Microsoft

Topik ini menjelaskan apa yang baru untuk ASP.NET Web API 2.1.

• Unduh

• Dokumentasi

• Fitur Baru di ASP.NET Web API 2.1

  • Penanganan Kesalahan Global
  • Peningkatan Perutean Atribut
  • Penyempurnaan Halaman Bantuan
  • Dukungan IgnoreRoute
  • BSON Media-Type Formatter
  • Dukungan yang Lebih Baik untuk Filter Asinkron
  • Penguraian Kueri untuk Pustaka Pemformatan Klien

• Masalah yang Diketahui dan Perubahan yang Melanggar

• Perbaikan Bug

Unduh

Fitur runtime dirilis sebagai paket NuGet di galeri NuGet. Semua paket runtime mengikuti spesifikasi Penerapan Versi Semantik . Paket RTM ASP.NET Web API 2.1 terbaru memiliki versi berikut: "5.1.2". Anda dapat menginstal atau memperbarui paket ini melalui NuGet. Rilis ini juga mencakup paket lokal yang sesuai di NuGet.

Anda dapat menginstal atau memperbarui ke paket NuGet yang dirilis dengan menggunakan NuGet Package Manager Console:

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

Dokumentasi

Tutorial dan informasi lain tentang ASP.NET Web API 2.1 RTM tersedia dari situs web ASP.NET (https://www.asp.net/web-api).

Fitur Baru di ASP.NET Web API 2.1

Penanganan Kesalahan Global

Semua pengecualian yang tidak tertangani sekarang dapat dicatat melalui satu mekanisme pusat, dan perilaku untuk pengecualian yang tidak tertangani dapat disesuaikan.

Kerangka kerja mendukung beberapa pencatat pengecualian, yang semuanya melihat pengecualian dan informasi yang tidak tertangani tentang konteks yang terjadi, seperti permintaan yang sedang diproses pada saat itu.

Misalnya, kode berikut menggunakan System.Diagnostics.TraceSource untuk mencatat semua pengecualian yang tidak tertangani:

public class TraceSourceExceptionLogger : ExceptionLogger
{
    private readonly TraceSource _traceSource;

    public TraceSourceExceptionLogger(TraceSource traceSource)
    {
        _traceSource = traceSource;
    }

    public override void Log(ExceptionLoggerContext context)
    {
        _traceSource.TraceEvent(TraceEventType.Error, 1,
            "Unhandled exception processing {0} for {1}: {2}",
            context.Request.Method,
            context.Request.RequestUri,
            context.Exception);
    }
}

config.Services.Add(typeof(IExceptionLogger), 
    new TraceSourceExceptionLogger(new 
    TraceSource("MyTraceSource", SourceLevels.All)));

Anda juga dapat mengganti handler pengecualian default, sehingga Anda dapat sepenuhnya menyesuaikan pesan respons HTTP yang dikirim ketika pengecualian yang tidak tertangani terjadi.

Kami telah menyediakan sampel yang mencatat semua pengecualian yang tidak tertangani melalui kerangka kerja ELMAH populer.

Peningkatan Perutean Atribut

Perutean atribut sekarang mendukung batasan, mengaktifkan penerapan versi dan pemilihan rute berbasis header. Selain itu, banyak aspek rute atribut sekarang dapat disesuaikan melalui antarmuka IDirectRouteFactory dan kelas RouteFactoryAttribute . Awalan rute sekarang dapat diperluas melalui antarmuka IRoutePrefix dan kelas RoutePrefixAttribute .

Kami telah menyediakan sampel yang menggunakan batasan untuk memfilter pengontrol secara dinamis dengan header HTTP 'versi api'.

Penyempurnaan Halaman Bantuan

Web API 2.1 menyertakan penyempurnaan berikut ke Halaman Bantuan API:

• Dokumentasi properti individual parameter atau jenis tindakan yang dikembalikan.
• Dokumentasi anotasi model data.

Desain UI halaman bantuan juga diperbarui, untuk mengakomodasi perubahan ini.

Dukungan IgnoreRoute

Web API 2.1 mendukung pengabaian pola URL dalam perutean API Web, melalui serangkaian metode ekstensi IgnoreRoute pada HttpRouteCollection. Metode ini menyebabkan WEB API mengabaikan URL apa pun yang cocok dengan templat tertentu, dan memungkinkan host menerapkan pemrosesan tambahan jika sesuai.

Contoh berikut mengabaikan URI yang dimulai dengan segmen "konten":

routes.IgnoreRoute("IgnoreContent", "content/{*paths}");
routes.MapHttpRoute("Default", "{controller}/{id}");

BSON Media-Type Formatter

WEB API sekarang mendukung format kawat BSON , baik di klien maupun di server.

Untuk mengaktifkan BSON di sisi server, tambahkan BsonMediaTypeFormatter ke koleksi pemformat:

config.Formatters.Add(new BsonMediaTypeFormatter());

Berikut adalah bagaimana klien .NET dapat menggunakan format BSON:

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

// POST data in BSON format.
HttpResponseMessage response = await client.PostAsync<MyData>("api/MyData", data, new 
BsonMediaTypeFormatter());

// GET data in BSON format.
data = await response.Content.ReadAsAsync<MyData>(new MediaTypeFormatter[] { 
  new BsonMediaTypeFormatter() });

Kami telah menyediakan sampel yang menunjukkan sisi klien dan server.

Untuk informasi selengkapnya, lihat Dukungan BSON di Web API 2.1

Dukungan yang Lebih Baik untuk Filter Asinkron

Web API sekarang mendukung cara mudah untuk membuat filter yang dijalankan secara asinkron. Fitur ini berguna adalah filter Anda perlu melakukan tindakan asinkron, seperti mengakses database. Sebelumnya, untuk membuat filter asinkron, Anda harus mengimplementasikan antarmuka filter sendiri, karena kelas dasar filter hanya mengekspos metode sinkron. Sekarang Anda dapat mengambil alih metode virtual On*Async kelas dasar filter.

Contohnya:

public class AsyncLoggingFilter : ActionFilterAttribute
{
    public override async Task OnActionExecutingAsync(HttpActionContext actionContext, CancellationToken cancellationToken)
    {
        await Trace.WriteAsync("Executing action named {0} for request {1}.", 
            actionContext.ActionDescriptor.ActionName, 
            actionContext.Request.GetCorrelationId());
    }
}

Kelas AuthorizationFilterAttribute, ActionFilterAttribute, dan ExceptionFilterAttribute semuanya mendukung asinkron di Web API 2.1.

Penguraian Kueri untuk Pustaka Pemformatan Klien

Sebelumnya, System.Net.Http.Formatting mendukung penguraian dan pembaruan kueri URI untuk kode sisi server, tetapi pustaka portabel yang setara tidak memiliki fitur ini. Di Web API 2.1, aplikasi klien sekarang dapat dengan mudah mengurai dan memperbarui string kueri.

Contoh berikut menunjukkan cara mengurai, memodifikasi, dan menghasilkan kueri URI. (Contoh menunjukkan aplikasi konsol untuk kesederhanaan.)

// Query parsing
HttpValueCollection collection = new Uri("http://api/something?catId=3&catId=4&dogId=1,2").ParseQueryString();

Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2

// Modify the query
collection.Add("dogId", "7");

// Index into the values
Console.WriteLine(collection["catId"]); // output: 3,4
Console.WriteLine(collection["dogId"]); // output: 1,2,7

// Recreate the query string
Console.WriteLine(collection.ToString()); // output: catId=3&catId=4&dogId=1%2C2&dogId=7

// Query generation
HttpValueCollection newCollection = new HttpValueCollection();

newCollection.Add("catId", "1");
newCollection.Add("dogId", "7");

// Index into the values
Console.WriteLine(newCollection["catId"]); // output: 1
Console.WriteLine(newCollection["dogId"]); // output: 7

// Create the query string
Console.WriteLine(newCollection.ToString()); // catId=1&dogId=7

Masalah yang Diketahui dan Perubahan yang Melanggar

Bagian ini menjelaskan masalah yang diketahui dan melanggar perubahan di ASP.NET Web API 2.1 RTM.

Perutean Atribut

Ambiguitas dalam kecocokan perutean atribut sekarang melaporkan kesalahan daripada memilih kecocokan pertama.

Rute atribut dilarang menggunakan parameter {controller} , dan dari menggunakan parameter {action} pada rute yang ditempatkan pada tindakan. Parameter ini kemungkinan besar akan menyebabkan ambiguitas.

Perancah MVC/Web API ke dalam proyek dengan paket 5.1 menghasilkan paket 5.0 untuk paket yang belum ada dalam proyek

Memperbarui paket NuGet untuk ASP.NET Web API 2.1 RTM tidak memperbarui alat Visual Studio, seperti perancah ASP.NET atau templat proyek Aplikasi Web ASP.NET. Mereka menggunakan versi sebelumnya dari paket runtime ASP.NET (5.0.0.0). Akibatnya, perancah ASP.NET akan menginstal versi sebelumnya (5.0.0.0) dari paket yang diperlukan, jika belum tersedia di proyek Anda. Namun, perancah ASP.NET di Visual Studio 2013 RTM atau Pembaruan 1 tidak menimpa paket terbaru dalam proyek Anda.

Jika Anda menggunakan perancah ASP.NET setelah memperbarui paket ke Web API 2.1 atau ASP.NET MVC 5.1, pastikan versi Web API dan MVC konsisten.

Ketik Ganti Nama

Beberapa jenis yang digunakan untuk ekstensibilitas perutean atribut diubah namanya dari RC menjadi 2.1 RTM.

Nama jenis lama (2.1 RC)	Nama Jenis Baru (2.1 RTM)
IDirectRouteProvider	IDirectRouteFactory
RouteProviderAttribute	RouteFactoryAttribute
DirectRouteProviderContext	DirectRouteFactoryContext

Filter pengecualian tidak membongkar pengecualian agregat yang dilemparkan dalam tindakan asinkron

Sebelumnya, jika tindakan asinkron melempar AggregateException, filter pengecualian akan membongkar pengecualian, dan OnException akan mendapatkan pengecualian dasar. Dalam 2.1, filter pengecualian tidak membongkarnya, dan OnException mendapatkan AggregateException asli.

Perbaikan Bug

Rilis ini juga mencakup beberapa perbaikan bug.

Paket 5.1.2 berisi pembaruan IntelliSense tetapi tidak ada perbaikan bug.