ASP.NET Web API 2.1 Sürümündeki Yenilikler

  • Makale

Microsoft tarafından

Bu konuda, ASP.NET Web API 2.1'e yönelik yenilikler açıklanmaktadır.

İndir

Çalışma zamanı özellikleri, NuGet galerisinde NuGet paketleri olarak yayımlanmaktadır. Tüm çalışma zamanı paketleri AnlamSal Sürüm Oluşturma belirtimini izler. En son ASP.NET Web API 2.1 RTM paketi şu sürüme sahiptir: "5.1.2". NuGet aracılığıyla bu paketleri yükleyebilir veya güncelleştirebilirsiniz. Sürüm, NuGet'te karşılık gelen yerelleştirilmiş paketleri de içerir.

NuGet Paket Yöneticisi Konsolu'nu kullanarak yayımlanan NuGet paketlerini yükleyebilir veya güncelleştirebilirsiniz:

Install-Package Microsoft.AspNet.WebApi -Version 5.1.2

Belgeler

ASP.NET Web API 2.1 RTM ile ilgili öğreticiler ve diğer bilgiler ASP.NET web sitesinden (https://www.asp.net/web-api) edinilebilir.

ASP.NET Web API 2.1'deki Yeni Özellikler

Genel Hata İşleme

İşlenmeyen tüm özel durumlar artık tek bir merkezi mekanizma aracılığıyla günlüğe kaydedilebilir ve işlenmeyen özel durumların davranışı özelleştirilebilir.

Çerçeve, işlenmeyen özel durumu ve o sırada işlenen istek gibi gerçekleştiği bağlamla ilgili bilgileri gören birden çok özel durum günlükçüsünü destekler.

Örneğin, aşağıdaki kod tüm işlenmeyen özel durumları günlüğe kaydetmek için System.Diagnostics.TraceSource kullanır:

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

Ayrıca, işlenmeyen bir özel durum oluştuğunda gönderilen HTTP yanıt iletisini tamamen özelleştirebilmeniz için varsayılan özel durum işleyicisini de değiştirebilirsiniz.

Popüler ELMAH çerçevesi aracılığıyla işlenmeyen tüm özel durumları günlüğe kaydeden bir örnek sağladık.

Öznitelik Yönlendirme Geliştirmeleri

Öznitelik yönlendirme artık kısıtlamaları destekleyerek sürüm oluşturma ve üst bilgi tabanlı yol seçimini etkinleştirmektedir. Ayrıca, öznitelik yollarının birçok yönü artık IDirectRouteFactory arabirimi ve RouteFactoryAttribute sınıfı aracılığıyla özelleştirilebilir. Yol ön eki artık IRoutePrefix arabirimi ve RoutePrefixAttribute sınıfı aracılığıyla genişletilebilir.

Denetleyicileri 'api-version' HTTP üst bilgisine göre dinamik olarak filtrelemek için kısıtlamaları kullanan bir örnek sağladık.

Yardım Sayfası Geliştirmeleri

Web API 2.1, API Yardım Sayfalarında aşağıdaki iyileştirmeleri içerir:

  • Parametrelerin veya dönüş eylem türlerinin tek tek özelliklerinin belgeleri.
  • Veri modeli ek açıklamalarının belgeleri.

Yardım sayfalarının kullanıcı arabirimi tasarımı da bu değişikliklere uyum sağlayacak şekilde güncelleştirildi.

IgnoreRoute Desteği

Web API 2.1, HttpRouteCollection'daki bir dizi IgnoreRoute uzantı yöntemi aracılığıyla Web API yönlendirmesindeki URL desenlerini yoksaymayı destekler. Bu yöntemler, Web API'sinin belirtilen şablonla eşleşen URL'leri yoksaymasına ve konağın uygunsa ek işlem uygulamasına izin vermesine neden olur.

Aşağıdaki örnek bir "içerik" kesimiyle başlayan URI'leri yoksayar:

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

BSON Media-Type Biçimlendirici

Web API artık hem istemcide hem de sunucuda BSON kablo biçimini destekliyor.

Sunucu tarafında BSON'u etkinleştirmek için BsonMediaTypeFormatter'ı biçimlendiriciler koleksiyonuna ekleyin:

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

Bir .NET istemcisi BSON biçimini şu şekilde kullanabilir:

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

Hem istemci hem de sunucu tarafını gösteren bir örnek sağladık.

Daha fazla bilgi için bkz. Web API 2.1'de BSON Desteği

Zaman Uyumsuz Filtreler için Daha İyi Destek

Web API artık zaman uyumsuz olarak yürütülen filtreler oluşturmanın kolay bir yolunu destekliyor. Bu özellik, filtrenizin veritabanına erişim gibi zaman uyumsuz bir eylem gerçekleştirmesi gerektiğinden yararlıdır. Daha önce, zaman uyumsuz bir filtre oluşturmak için filtre arabirimini kendiniz uygulamanız gerekiyordu çünkü filtre temel sınıfları yalnızca zaman uyumlu yöntemleri kullanıma sunmuştu. Artık filtre temel sınıfının sanal On*Async yöntemlerini geçersiz kılabilirsiniz.

Örneğin:

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

AuthorizationFilterAttribute, ActionFilterAttribute ve ExceptionFilterAttribute sınıflarının tümü Web API 2.1'de zaman uyumsuz hizmeti destekler.

İstemci Biçimlendirme Kitaplığı için Sorgu Ayrıştırma

Daha önce , System.Net.Http.Formatting sunucu tarafı kodu için URI sorgularının ayrıştırılıp güncelleştirilmesini destekliyordu, ancak eşdeğer taşınabilir kitaplıkta bu özellik eksikti. Web API 2.1'de bir istemci uygulaması artık sorgu dizesini kolayca ayrıştırabilir ve güncelleştirebilir.

Aşağıdaki örneklerde URI sorgularını ayrıştırma, değiştirme ve oluşturma adımları gösterilir. (Örneklerde kolaylık sağlamak için bir konsol uygulaması gösterilir.)

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

Bilinen Sorunlar ve Hataya Neden Olan Değişiklikler

Bu bölümde, ASP.NET Web API 2.1 RTM'deki bilinen sorunlar ve hataya neden olan değişiklikler açıklanmaktadır.

Öznitelik Yönlendirme

Öznitelik yönlendirme eşleşmelerindeki belirsizlikler artık ilk eşleşmeyi seçmek yerine bir hata bildiriyor.

Öznitelik yollarının {controller} parametresini ve eylemlere yerleştirilen yollarda {action} parametresini kullanmaları yasaktır. Bu parametreler büyük olasılıkla belirsizliklere neden olabilir.

MVC/Web API'sini 5.1 paketli bir projeye iskelesi oluşturmak, projede henüz mevcut olmayanlar için 5.0 paketleriyle sonuçlanmıştır

ASP.NET Web API 2.1 RTM için NuGet paketlerinin güncelleştirilmesi, ASP.NET yapı iskelesi veya ASP.NET Web Uygulaması proje şablonu gibi Visual Studio araçlarını güncelleştirmez. ASP.NET çalışma zamanı paketlerinin önceki sürümünü (5.0.0.0) kullanırlar. Sonuç olarak, ASP.NET yapı iskelesi, projelerinizde mevcut değilse gerekli paketlerin önceki sürümünü (5.0.0.0) yükler. Ancak, Visual Studio 2013 RTM veya Güncelleştirme 1'deki ASP.NET yapı iskelesi, projelerinizdeki en son paketlerin üzerine yazılmaz.

Paketleri Web API 2.1 veya ASP.NET MVC 5.1'e güncelleştirdikten sonra ASP.NET yapı iskelesi kullanıyorsanız, Web API ve MVC sürümlerinin tutarlı olduğundan emin olun.

Tür Yeniden Adlandırmaları

Öznitelik yönlendirme genişletilebilirliği için kullanılan türlerden bazıları RC'den 2.1 RTM'ye yeniden adlandırıldı.

Eski tür adı (2.1 RC) Yeni Tür Adı (2.1 RTM)
IDirectRouteProvider IDirectRouteFactory
RouteProviderAttribute RouteFactoryAttribute
DirectRouteProviderContext DirectRouteFactoryContext

Özel durum filtreleri zaman uyumsuz eylemlerde oluşan toplama özel durumlarını kaldırmaz

Daha önce zaman uyumsuz bir eylem AggregateException oluşturursa, özel durum filtresi özel durumu kaldıracaktı ve OnException temel özel durumu alacaktı. 2.1'de özel durum filtresi bu filtreyi açmaz ve OnException özgün AggregateException'ı alır.

Hata Düzeltmeleri

Bu sürüm çeşitli hata düzeltmeleri de içerir.

5.1.2 paketi IntelliSense güncelleştirmelerini içerir ancak hata düzeltmesi içermez.