ASP.NET Core'dan web API'si çağırma Blazor

Bu makalede, bir uygulamadan web API'sini Blazor çağırma açıklanmaktadır.

Paket

paket, System.Net.Http.Json ve System.Text.Jsoniçin System.Net.Http.HttpClient System.Net.Http.HttpContent kullanarak otomatik serileştirme ve seri durumdan çıkarma gerçekleştiren uzantı yöntemleri sağlar. Paket System.Net.Http.Json .NET paylaşılan çerçevesi tarafından sağlanır ve uygulamaya paket başvurusu eklenmesini gerektirmez.

Örnek uygulamalar

GitHub deposundaki dotnet/blazor-samples örnek uygulamalara bakın.

BlazorWebAppCallWebApi

içinden bir dış (içinde değil Blazor Web App) yapılacaklar listesi web API'sini Blazor Web Appçağırın:

• Backend: Minimum API'leri temel alan bir yapılacaklar listesi tutmak için bir web API uygulaması. Web API'si uygulaması, büyük olasılıkla farklı bir sunucuda barındırılan Blazor Web Appuygulamasından ayrı bir uygulamadır.
• BlazorApp/BlazorApp.ClientBlazor Web App: Yapılacaklar listesinden öğe oluşturma, okuma, güncelleştirme ve silme (CRUD) gibi yapılacaklar listesi işlemleriyle HttpClient web API'sini çağıran bir.

CsR'yi benimseyen Etkileşimli WebAssembly bileşenlerini ve Otomatik bileşenleri içeren istemci tarafı işleme (CSR) için, çağrılar istemci projesinin dosyasında (HttpClientProgramBlazorApp.Client):

builder.Services.AddScoped(sp =>
    new HttpClient
    {
        BaseAddress = new Uri(builder.Configuration["FrontendUrl"] ?? "https://localhost:5002")
    });

Önceden oluşturulmuş ve etkileşimli Sunucu bileşenlerini, önceden yenilenen WebAssembly bileşenlerini ve önceden hazırlanmış veya SSR'yi benimsemiş Otomatik bileşenleri içeren sunucu tarafı işleme (SSR) için, çağrılar sunucu projesinin dosyasında kayıtlı ProgramBlazorApp(HttpClient):

builder.Services.AddHttpClient();

API'nin sunucu projesinde Blazor Web Appbulunduğu bir iç (içinde) film listesi API'sini çağırın Blazor Web App:

• BlazorAppBlazor Web App: Bir film listesi tutan:
  • sunucudaki uygulama içindeki film listesinde işlemler gerçekleştirildiğinde, sıradan API çağrıları kullanılır.
  • API çağrıları web tabanlı bir istemci tarafından yapıldığında, en düşük API'leri temel alan film listesi işlemleri için bir web API'si kullanılır.
• BlazorApp.Client: Film listesinin Blazor Web Appkullanıcı yönetimi için Interactive WebAssembly ve Auto bileşenlerini içeren istemci projesi.

CSR'yi benimseyen Etkileşimli WebAssembly bileşenlerini ve Otomatik bileşenleri içeren CSR için, API'ye çağrılar istemci projesinin () dosyasında önceden yapılandırılmış HttpClient bir kayıtlı Program kullanan istemci tabanlı hizmet (ClientMovieServiceBlazorApp.Client) aracılığıyla yapılır. Bu çağrılar genel veya özel bir web üzerinden yapıldığından, film listesi API'si bir web API'sidir.

Aşağıdaki örnek, uç noktadan film /movies listesini elde eder:

public class ClientMovieService(HttpClient http) : IMovieService
{
    public async Task<Movie[]> GetMoviesAsync(bool watchedMovies) => 
        await http.GetFromJsonAsync<Movie[]>("movies") ?? [];
}

Önceden oluşturulmuş ve etkileşimli Sunucu bileşenlerini, önceden yenilenen WebAssembly bileşenlerini ve önceden hazırlanmış veya SSR'yi benimsemiş Otomatik bileşenleri içeren SSR için, çağrılar doğrudan sunucu tabanlı bir hizmet (ServerMovieService üzerinden yapılır). API bir ağa güvenmediğinden film listesi CRUD işlemleri için standart bir API'dir.

Aşağıdaki örnek bir film listesi elde eder:

public class ServerMovieService(MovieContext db) : IMovieService
{
    public async Task<Movie[]> GetMoviesAsync(bool watchedMovies) => 
        watchedMovies ? 
        await db.Movies.Where(t => t.IsWatched).ToArrayAsync() : 
        await db.Movies.ToArrayAsync();
}

BlazorWebAppCallWebApi_Weather

Hava durumu verileri için akış işleme kullanan bir hava durumu verileri örnek uygulaması.

BlazorWebAssemblyCallWebApi

Bir uygulamadan yapılacaklar listesi web API'sini Blazor WebAssembly çağırır:

• Backend: Minimum API'leri temel alan bir yapılacaklar listesi tutmak için bir web API uygulaması.
• BlazorTodoBlazor WebAssembly: Yapılacaklar listesi CRUD işlemleri için önceden yapılandırılmış web API'sini çağıran HttpClient bir uygulama.

Dış web API'lerini çağırmak için sunucu tarafı senaryoları

Sunucu tabanlı bileşenler, genellikle kullanılarak IHttpClientFactoryoluşturulan örnekleri kullanarak HttpClient dış web API'lerini çağırır. Sunucu tarafı uygulamalarına yönelik yönergeler için bkz . ASP.NET Core'da IHttpClientFactory kullanarak HTTP istekleri oluşturma.

Sunucu tarafı uygulaması hizmet içermez HttpClient . Fabrika altyapısını kullanarak HttpClient uygulamaya bir HttpClient sağlayın.

Program dosyasında:

builder.Services.AddHttpClient();

Aşağıdaki Razor bileşen, ASP.NET Core'da IHttpClientFactory kullanarak HTTP istekleri oluşturma makalesindeki Temel Kullanım örneğine benzer şekilde GitHub dalları için bir web API'sine istekte bulunur.

CallWebAPI.razor:

@page "/call-web-api"
@using System.Text.Json
@using System.Text.Json.Serialization
@inject IHttpClientFactory ClientFactory

<h1>Call web API from a Blazor Server Razor component</h1>

@if (getBranchesError || branches is null)
{
    <p>Unable to get branches from GitHub. Please try again later.</p>
}
else
{
    <ul>
        @foreach (var branch in branches)
        {
            <li>@branch.Name</li>
        }
    </ul>
}

@code {
    private IEnumerable<GitHubBranch>? branches = [];
    private bool getBranchesError;
    private bool shouldRender;

    protected override bool ShouldRender() => shouldRender;

    protected override async Task OnInitializedAsync()
    {
        var request = new HttpRequestMessage(HttpMethod.Get,
            "https://api.github.com/repos/dotnet/AspNetCore.Docs/branches");
        request.Headers.Add("Accept", "application/vnd.github.v3+json");
        request.Headers.Add("User-Agent", "HttpClientFactory-Sample");

        var client = ClientFactory.CreateClient();

        var response = await client.SendAsync(request);

        if (response.IsSuccessStatusCode)
        {
            using var responseStream = await response.Content.ReadAsStreamAsync();
            branches = await JsonSerializer.DeserializeAsync
                <IEnumerable<GitHubBranch>>(responseStream);
        }
        else
        {
            getBranchesError = true;
        }

        shouldRender = true;
    }

    public class GitHubBranch
    {
        [JsonPropertyName("name")]
        public string? Name { get; set; }
    }
}

Yukarıdaki C# 12 veya üzeri örnekte, değişken için branches boş bir dizi ([]) oluşturulur. Önceki C# sürümleri için boş bir dizi (Array.Empty<GitHubBranch>()) oluşturun.

Ek bir çalışma örneği için, ASP.NET Core Blazor dosya yüklemeleri makalesindeki bir web API denetleyicisine dosya yükleyen sunucu tarafı dosya yükleme örneğine bakın.

Web API çağrıları için hizmet özetleri

Bu bölüm, sunucu projesinde bir web API'sini koruyan veya web API çağrılarını dış web API'sine dönüştürenler için geçerlidir Blazor Web App.

Etkileşimli WebAssembly ve Otomatik işleme modlarını kullanırken, bileşenler varsayılan olarak önceden oluşturulur. Paket istemciye indirilmeden ve istemci tarafı çalışma zamanı etkinleştirilmeden önce Blazor otomatik bileşenler başlangıçta sunucudan etkileşimli olarak işlenir. Bu, bu işleme modlarını kullanan bileşenlerin hem istemciden hem de sunucudan başarıyla çalışacak şekilde tasarlanması gerektiği anlamına gelir. Bileşenin istemcide çalışırken sunucu proje tabanlı API'yi çağırması veya bir isteği dış web API'sine dönüştürmesi gerekiyorsa (dış web API'sinin Blazor Web Appdışındadır), önerilen yaklaşım bu API çağrısını bir hizmet arabiriminin arkasında soyutlayıp hizmetin istemci ve sunucu sürümlerini uygulamaktır:

• İstemci sürümü, önceden yapılandırılmış bir ile web API'sini HttpClientçağırır.
• Sunucu sürümü genellikle sunucu tarafı kaynaklarına doğrudan erişebilir. Ağ isteği normalde gereksiz olduğundan, sunucuya geri çağrı yapan sunucuya bir HttpClient ekleme önerilmez. Alternatif olarak, API sunucu projesinin dışında olabilir, ancak isteği bir şekilde dönüştürmek için sunucu için bir hizmet soyutlaması gerekir; örneğin, bir prxied isteğine erişim belirteci eklemek için.

WebAssembly işleme modunu kullanırken, bileşenler yalnızca istemciden işlendiğinden, ön kayıt işlemini devre dışı bırakma seçeneğiniz de vardır. Daha fazla bilgi için bkz . ASP.NET Core Blazor işleme modları.

Örnekler (örnek uygulamalar):

• Örnek uygulamada film listesi web API'si BlazorWebAppCallWebApi .
• Örnek uygulamada hava durumu verileri web API'sini işleme akışı BlazorWebAppCallWebApi_Weather .
• (BFF olmayan desen) veya BlazorWebAppOidcBff (BFF deseni) örnek uygulamalarında istemciye BlazorWebAppOidc döndürülen hava durumu verileri. Bu uygulamalar güvenli (web) API çağrılarını gösterir. Daha fazla bilgi için bkz . OpenID Connect (OIDC) ile ASP.NET Çekirdeğinin Blazor Web App güvenliğini sağlama.

Blazor Web App dış web API'leri

Bu bölüm, büyük olasılıkla farklı bir sunucuda barındırılan ayrı (dış) bir proje tarafından tutulan bir web API'sini çağıran için geçerlidir Blazor Web App.

Blazor Web Apps normalde istemci tarafı WebAssembly bileşenlerini önceden hazırlar ve Statik veya etkileşimli sunucu tarafı işleme (SSR) sırasında otomatik bileşenler sunucuda işlenir. HttpClient hizmetleri varsayılan olarak bir Blazor Web App'nin ana projesine kaydedilmez. Hizmet ekleme HttpClient bölümünde açıklandığı gibi uygulama yalnızca HttpClient projede .Client kayıtlı hizmetlerle çalıştırılıyorsa, uygulamanın yürütülmesi çalışma zamanı hatasıyla sonuçlanır:

InvalidOperationException: '... türündeki 'Http' özelliği için değer sağlanamaz. {COMPONENT}'. 'System.Net.Http.HttpClient' türünde kayıtlı hizmet yok.

Aşağıdaki yaklaşımlardan birini kullanın:

• HttpClient SSR sırasında kullanılabilir duruma getirmek için hizmetleri sunucu projesine HttpClient ekleyin. Sunucu projesinin Program dosyasında aşağıdaki hizmet kaydını kullanın:

  builder.Services.AddHttpClient();
  

  HttpClient hizmetleri paylaşılan çerçeve tarafından sağlandığından, uygulamanın proje dosyasında paket başvurusu gerekmez.

  Örnek: Örnek uygulamada yapılacaklar listesi web API'si BlazorWebAppCallWebApi

• Web API'sini çağıran bir WebAssembly bileşeni için prerendering gerekli değilse, ASP.NET Core Blazor işleme modlarındaki yönergeleri izleyerek ön kayıt özelliğini devre dışı bırakın. Bu yaklaşımı benimserseniz, bileşen sunucuda önceden ayarlanmamış olduğundan ana projesine Blazor Web App hizmet eklemeniz HttpClient gerekmez.

Daha fazla bilgi için bkz . İstemci tarafı hizmetleri ön kayıt sırasında çözümlenememesi.

Önceden oluşturulmuş veriler

Prerendering sırasında bileşenler iki kez işlenir: önce statik, sonra etkileşimli. Durum, önceden oluşturulmuş bileşenden etkileşimli bileşene otomatik olarak akmıyor. Bir bileşen zaman uyumsuz başlatma işlemleri gerçekleştiriyorsa ve başlatma sırasında "Yükleniyor..." gibi farklı durumlar için farklı içerik işleniyorsa ilerleme göstergesi, bileşen iki kez işlendiğinde titreme görebilirsiniz.

Ve örnek uygulamalarının gösterdiği Kalıcı Bileşen Durumu API'sini BlazorWebAppCallWebApi BlazorWebAppCallWebApi_Weather kullanarak önceden alınan durumu akarak bu sorunu giderebilirsiniz. Bileşen etkileşimli olarak işlendiğinde, aynı durumu kullanarak aynı şekilde işlenebilir. Ancak, API şu anda gelişmiş gezintiyle çalışmaz. Bu işlem, sayfaya (data-enhanced-nav=false) yönelik bağlantılarda gelişmiş gezintiyi devre dışı bırakarak geçici bir çözüm olarak kullanılabilir. Daha fazla bilgi edinmek için aşağıdaki kaynaklara bakın:

• Prerender ASP.NET Core Razor bileşenleri
• ASP.NET Temel Blazor yönlendirme ve gezinti
• Gelişmiş sayfa gezintilerinde kalıcı bileşen durumunu destekleme (dotnet/aspnetcore #51584)

HttpClient Hizmeti ekleme

Bu bölümdeki yönergeler istemci tarafı senaryoları için geçerlidir.

İstemci tarafı bileşenleri, kaynak sunucuya geri istek göndermeye odaklanan HttpClient önceden yapılandırılmış bir hizmet kullanarak web API'lerini çağırır. Geliştirici kodunda diğer web API'leri için ek HttpClient hizmet yapılandırmaları oluşturulabilir. İstekler JSON yardımcıları kullanılarak Blazor veya ile HttpRequestMessageoluşturulur. İstekler, Fetch API seçeneği yapılandırmasını içerebilir.

Bu bölümdeki yapılandırma örnekleri yalnızca uygulamadaki tek bir örnek için tek HttpClient bir web API'sinin çağrıldığında yararlıdır. Uygulamanın her biri kendi temel adresine ve yapılandırmasına sahip birden çok web API'sini çağırması gerektiğinde, bu makalenin devamında ele alınan aşağıdaki yaklaşımları benimseyebilirsiniz:

• ile IHttpClientFactoryadlandırılırHttpClient: Her web API'sinde benzersiz bir ad sağlanır. Uygulama kodu veya bileşen Razor bir web API'sini çağırdığında, çağrıyı yapmak için adlandırılmış HttpClient bir örnek kullanır.
• HttpClientYazılan: Her web API'si yazıldı. Uygulama kodu veya bileşen Razor bir web API'sini çağırdığında, çağrıyı yapmak için yazılan HttpClient bir örneği kullanır.

Dosyada Program , uygulamayı oluşturmak için kullanılan bir HttpClient Blazor proje şablonundan henüz mevcut değilse bir hizmet ekleyin:

builder.Services.AddScoped(sp => 
    new HttpClient
    {
        BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
    });

Yukarıdaki örnek, uygulamanın temel adresini alan ve genellikle ana bilgisayar sayfasındaki etiketin href değerinden <base> türetilen temel adresi ()IWebAssemblyHostEnvironment.BaseAddress ile builder.HostEnvironment.BaseAddress ayarlar.

İstemcinin kendi temel adresini kullanmaya yönelik en yaygın kullanım örnekleri şunlardır:

• (.NET 8 veya üzeri) istemci projesi (.Client) Blazor Web App WebAssembly bileşenlerinden veya WebAssembly'deki istemcide çalışan koddan sunucu uygulamasındaki API'lere web API'leri çağrıları yapar.
• Barındırılan Blazor WebAssembly bir uygulamanın istemci projesi (Client), sunucu projesine (Server) web API çağrıları yapar. Barındırılan Blazor WebAssembly proje şablonunun artık .NET 8 veya sonraki sürümlerinde kullanılamadığını unutmayın. Ancak barındırılan Blazor WebAssembly uygulamalar .NET 8 için desteklenmeye devam etmektedir.

Dış web API'sini çağırıyorsanız (istemci uygulamasıyla aynı URL alanında değil), URI'yi web API'sinin temel adresine ayarlayın. Aşağıdaki örnek, ayrı bir web API'sinin https://localhost:5001çalıştığı ve istemci uygulamasından gelen isteklere yanıt vermeye hazır olduğu web API'sinin temel adresini olarak ayarlar:

builder.Services.AddScoped(sp => 
    new HttpClient
    {
        BaseAddress = new Uri("https://localhost:5001")
    });

JSON yardımcıları

HttpClient kaynak sunucuya geri istek göndermek için önceden yapılandırılmış bir hizmet olarak kullanılabilir.

HttpClient ve JSON yardımcıları (System.Net.Http.Json.HttpClientJsonExtensions), üçüncü taraf web API'leri uç noktalarını çağırmak için de kullanılır. HttpClienttarayıcının Fetch API'si kullanılarak uygulanır ve bu makalenin devamında Çıkış Noktaları Arası Kaynak Paylaşımı (CORS) bölümünde açıklanan aynı kaynak ilkesinin uygulanması da dahil olmak üzere sınırlamalarına tabidir.

İstemcinin temel adresi, kaynak sunucunun adresine ayarlanır. HttpClient yönergesini kullanarak bir bileşenine örnek ekleme@inject:

@using System.Net.Http
@inject HttpClient Http

, ve PostAsJsonAsyncdahil olmak üzere PutAsJsonAsyncGetFromJsonAsyncöğesine HttpClientJsonExtensionserişmek için ad alanını System.Net.Http.Json kullanın:

@using System.Net.Http.Json

Aşağıdaki bölümlerde JSON yardımcıları ele alınıyor:

• GET
• POST
• PUT
• PATCH

System.Net.Http HTTP istekleri göndermek ve HTTP yanıtları almak için, örneğin DELETE isteği göndermek için ek yöntemler içerir. Daha fazla bilgi için DELETE ve ek uzantı yöntemleri bölümüne bakın.

JSON'dan GET (GetFromJsonAsync)

GetFromJsonAsync bir HTTP GET isteği gönderir ve nesne oluşturmak için JSON yanıt gövdesini ayrıştırır.

Aşağıdaki bileşen kodunda todoItems , bileşeni tarafından görüntülenir. GetFromJsonAsync , bileşen başlatmayı () tamamladığında çağrılırOnInitializedAsync.

todoItems = await Http.GetFromJsonAsync<TodoItem[]>("todoitems");

JSON olarak POST (PostAsJsonAsync)

PostAsJsonAsync belirtilen URI'ye, istek gövdesinde JSON olarak serileştirilmiş değeri içeren bir POST isteği gönderir.

Aşağıdaki bileşen kodunda, newItemName bileşenin bağlı bir öğesi tarafından sağlanır. AddItem yöntemi bir <button> öğe seçilerek tetikleniyor.

await Http.PostAsJsonAsync("todoitems", addItem);

PostAsJsonAsync döndürür HttpResponseMessage. Yanıt iletisinden JSON içeriğini seri durumdan çıkarmak için uzantı yöntemini kullanın ReadFromJsonAsync . Aşağıdaki örnekte JSON hava durumu verileri bir dizi olarak okunur:

var content = await response.Content.ReadFromJsonAsync<WeatherForecast[]>() ?? 
    Array.Empty<WeatherForecast>();

JSON olarak PUT (PutAsJsonAsync)

PutAsJsonAsync JSON ile kodlanmış içeriğe sahip bir HTTP PUT isteği gönderir.

Aşağıdaki bileşen kodunda ve IsCompleted değerleriName, editItem bileşenin bağlı öğeleri tarafından sağlanır. Öğe Id kullanıcı arabiriminin başka bir bölümünde seçildiğinde (gösterilmediğinde) öğe ayarlanır ve EditItem çağrılır. SaveItem yöntemi öğesi seçilerek <button> tetikleniyor. Aşağıdaki örnekte kısa süre için yükleme todoItems gösterilmiyor. Öğeleri yükleme örneği için JSON'dan GET (GetFromJsonAsync) bölümüne bakın.

await Http.PutAsJsonAsync($"todoitems/{editItem.Id}", editItem);

PutAsJsonAsync döndürür HttpResponseMessage. Yanıt iletisinden JSON içeriğini seri durumdan çıkarmak için uzantı yöntemini kullanın ReadFromJsonAsync . Aşağıdaki örnekte JSON hava durumu verileri bir dizi olarak okunur:

var content = await response.Content.ReadFromJsonAsync<WeatherForecast[]>() ?? 
    Array.Empty<WeatherForecast>();

JSON olarak PATCH (PatchAsJsonAsync)

PatchAsJsonAsync JSON ile kodlanmış içeriğe sahip bir HTTP PATCH isteği gönderir.

Not

Daha fazla bilgi için bkz . ASP.NET Core web API'sinde JsonPatch.

Aşağıdaki örnekte, PatchAsJsonAsync bir JSON PATCH belgesini kaçış tırnak işaretleri içeren düz metin dizesi olarak alır:

await Http.PatchAsJsonAsync(
    $"todoitems/{id}", 
    "[{\"operationType\":2,\"path\":\"/IsComplete\",\"op\":\"replace\",\"value\":true}]");

PatchAsJsonAsync döndürür HttpResponseMessage. Yanıt iletisinden JSON içeriğini seri durumdan çıkarmak için uzantı yöntemini kullanın ReadFromJsonAsync . Aşağıdaki örnekte JSON todo öğesi verileri bir dizi olarak okunur. yöntemi tarafından hiçbir öğe verisi döndürülmezse boş bir dizi oluşturulur, bu nedenle content deyim yürütüldükten sonra null olmaz:

var response = await Http.PatchAsJsonAsync(...);
var content = await response.Content.ReadFromJsonAsync<TodoItem[]>() ??
    Array.Empty<TodoItem>();

Girinti, aralık ve sıralanmamış tırnak işaretleriyle düzenlenmiş kodlanmamış PATCH belgesi aşağıdaki JSON olarak görünür:

[
  {
    "operationType": 2,
    "path": "/IsComplete",
    "op": "replace",
    "value": true
  }
]

Patch istekleri veren uygulamada PATCH belgelerinin oluşturulmasını basitleştirmek için, aşağıdaki kılavuzda gösterildiği gibi bir uygulama .NET JSON PATCH desteğini kullanabilir.

Microsoft.AspNetCore.JsonPatch Bir PATCH isteği oluşturmak için NuGet paketini yükleyin ve paketin JsonPatchDocument API özelliklerini kullanın.

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri) paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

, System.Text.Json.Serializationve ad alanları için System.Text.Jsonyönergeleri bileşenin Razor en üstüne ekleyin @using Microsoft.AspNetCore.JsonPatch:

@using System.Text.Json
@using System.Text.Json.Serialization
@using Microsoft.AspNetCore.JsonPatch

JsonPatchDocument yöntemini kullanarak Replace set true ile IsComplete için TodoItem öğesini oluşturun:

var patchDocument = new JsonPatchDocument<TodoItem>()
    .Replace(p => p.IsComplete, true);

Belgenin işlemlerini (patchDocument.Operations) çağrıya geçirin PatchAsJsonAsync :

private async Task UpdateItem(long id)
{
    await Http.PatchAsJsonAsync(
        $"todoitems/{id}", 
        patchDocument.Operations, 
        new JsonSerializerOptions()
        {
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingDefault
        });
}

JsonSerializerOptions.DefaultIgnoreCondition yalnızca türü için varsayılan değere eşitse özelliği yoksayacak şekilde ayarlanır JsonIgnoreCondition.WhenWritingDefault .

JSON yükünü görüntüleme için hoş bir biçimde sunmak istiyorsanız olarak ayarlayın JsonSerializerOptions.WriteIndented true . Girintili JSON yazmanın PATCH isteklerini işlemeyle bir ilgisi yoktur ve genellikle web API'leri istekleri için üretim uygulamalarında gerçekleştirilmez.

Web API'sine PATCH denetleyicisi eylemi eklemek için ASP.NET Core web API'sindeki JsonPatch makalesindeki yönergeleri izleyin. Alternatif olarak PATCH isteği işleme, aşağıdaki adımlarla Minimal API olarak uygulanabilir.

Web API'sine Microsoft.AspNetCore.Mvc.NewtonsoftJson NuGet paketi için bir paket başvurusu ekleyin.

Not

Paket başvurusu otomatik olarak geçişli olarak için bir paket başvurusu Microsoft.AspNetCore.JsonPatch eklediğinden Microsoft.AspNetCore.Mvc.NewtonsoftJson , paket için Microsoft.AspNetCore.JsonPatchpaket başvurusu eklemeye gerek yoktur.

Program dosyasına ad alanı için Microsoft.AspNetCore.JsonPatch bir @using yönerge ekleyin:

using Microsoft.AspNetCore.JsonPatch;

Uç noktayı web API'sinin istek işleme işlem hattına sağlayın:

app.MapPatch("/todoitems/{id}", async (long id, TodoContext db) =>
{
    if (await db.TodoItems.FindAsync(id) is TodoItem todo)
    {
        var patchDocument = 
            new JsonPatchDocument<TodoItem>().Replace(p => p.IsComplete, true);
        patchDocument.ApplyTo(todo);
        await db.SaveChangesAsync();

        return TypedResults.Ok(todo);
    }

    return TypedResults.NoContent();
});

Uyarı

ASP.NET Core web API'sindeki JsonPatch makalesindeki diğer örneklerde olduğu gibi, yukarıdaki PATCH API'si web API'sini aşırı gönderme saldırılarına karşı korumaz. Daha fazla bilgi için bkz . Öğretici: ASP.NET Core ile web API'sini oluşturma.

Tam olarak çalışan bir PATCH deneyimi için örnek uygulamaya bakın BlazorWebAppCallWebApi .

DELETE (DeleteAsync) ve ek uzantı yöntemleri

System.Net.Http HTTP istekleri göndermek ve HTTP yanıtları almak için ek uzantı yöntemleri içerir. HttpClient.DeleteAsync bir web API'sine HTTP DELETE isteği göndermek için kullanılır.

Aşağıdaki bileşen kodunda <button> öğesi yöntemini çağırır DeleteItem . İlişkili <input> öğe silinecek öğenin öğesini sağlar id .

await Http.DeleteAsync($"todoitems/{id}");

ile adlandırılır HttpClientIHttpClientFactory

IHttpClientFactory hizmetleri ve adlandırılmış bir yapılandırma HttpClient desteklenir.

Not

'den IHttpClientFactory adlandırılmış HttpClient bir ad kullanmanın bir alternatifi, yazılan HttpClientbir kullanmaktır. Daha fazla bilgi için Yazılan HttpClient bölümüne bakın.

Microsoft.Extensions.Http NuGet paketini uygulamaya ekleyin.

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri) paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

Program İstemci projesinin dosyasında:

builder.Services.AddHttpClient("WebAPI", client => 
    client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress));

Adlandırılmış istemci, bir Blazor Web Appöğesinin önceden oluşturulmuş istemci tarafı bileşenleri tarafından kullanılacaksa, önceki hizmet kaydı hem sunucu projesinde .Client hem de projede görünmelidir. sunucuda, builder.HostEnvironment.BaseAddress web API'sinin aşağıda açıklanan temel adresiyle değiştirilir.

Yukarıdaki istemci tarafı örneği, temel adresi ()IWebAssemblyHostEnvironment.BaseAddress ile builder.HostEnvironment.BaseAddress ayarlar. Bu, istemci tarafı uygulamasının temel adresini alır ve genellikle ana bilgisayar sayfasındaki etiketin <base> href değerinden türetilir.

İstemcinin kendi temel adresini kullanmaya yönelik en yaygın kullanım örnekleri şunlardır:

• WebAssembly/Auto bileşenlerinden veya WebAssembly'deki istemcide çalışan koddan sunucu uygulamasındaki API'lere aynı konak adresinde web API'leri çağrıları yapan istemci Blazor Web App projesi (.Client).
• Sunucu projesine (Client) web API çağrıları yapan barındırılan Blazor WebAssembly bir uygulamanın istemci projesi (Server).

Dış web API'sini (istemci uygulamasıyla aynı URL alanında değil) çağırıyorsanız veya hizmetleri bir sunucu tarafı uygulamasında yapılandırıyorsanız (örneğin, sunucudaki istemci tarafı bileşenlerinin önceden yenilenmesiyle başa çıkmak için), URI'yi web API'sinin temel adresine ayarlayın. Aşağıdaki örnek, ayrı bir web API'sinin https://localhost:5001çalıştığı ve istemci uygulamasından gelen isteklere yanıt vermeye hazır olduğu web API'sinin temel adresini olarak ayarlar:

builder.Services.AddHttpClient("WebAPI", client => 
    client.BaseAddress = new Uri("https://localhost:5001"));

Aşağıdaki bileşen kodunda:

• örneği IHttpClientFactory adlı HttpClientbir oluşturur.
• adı HttpClient , konumundaki /forecastweb API'sinden JSON hava durumu tahmin verileri için bir GET isteği göndermek için kullanılır.

@inject IHttpClientFactory ClientFactory

...

@code {
    private Forecast[]? forecasts;

    protected override async Task OnInitializedAsync()
    {
        var client = ClientFactory.CreateClient("WebAPI");

        forecasts = await client.GetFromJsonAsync<Forecast[]>("forecast") ?? [];
    }
}

Örnek BlazorWebAppCallWebApi uygulama , bileşeninde adlı HttpClient bir web API'sini çağırmayı CallTodoWebApiCsrNamedClient gösterir. adlı HttpClientbir Microsoft Graph çağrısına dayalı bir istemci uygulamasında ek çalışma tanıtımı için bkz . ASP.NET Core Blazor WebAssemblyile Graph API'sini kullanma.

Yazılı HttpClient

HttpClient Yazılan, bir veya daha fazla web API'sinden HttpClient veri döndürmek için uygulamanın varsayılan veya adlandırılmış örneklerinden birini veya daha fazlasını kullanır.

Not

Türü yazılan HttpClient bir kullanmanın alternatifi, adlı bir HttpClient öğesini IHttpClientFactorykullanmaktır. Daha fazla bilgi için Şununla adlandırılmış HttpClient IHttpClientFactory bölümüne bakın.

Microsoft.Extensions.Http NuGet paketini uygulamaya ekleyin.

Not

.NET uygulamalarına paket ekleme hakkında yönergeler için, Paket tüketimi iş akışında (NuGet belgeleri) paketleri yüklemek ve yönetmek altındaki makalelere bakın. NuGet.org'da doğru paket sürümlerini onaylayın.

Aşağıdaki örnek, konumundaki /forecastweb API'sinden JSON hava durumu tahmin verileri için bir GET isteği verir.

ForecastHttpClient.cs:

using System.Net.Http.Json;

namespace BlazorSample.Client;

public class ForecastHttpClient(HttpClient http)
{
    public async Task<Forecast[]> GetForecastAsync() => 
        await http.GetFromJsonAsync<Forecast[]>("forecast") ?? [];
}

Program İstemci projesinin dosyasında:

builder.Services.AddHttpClient<ForecastHttpClient>(client => 
    client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress));

Yazılan istemci, önceden oluşturulmuş istemci Blazor Web Apptarafı bileşenleri tarafından kullanılacaksa, önceki hizmet kaydı hem sunucu projesinde .Client hem de projede görünmelidir. sunucuda, builder.HostEnvironment.BaseAddress web API'sinin aşağıda açıklanan temel adresiyle değiştirilir.

Yukarıdaki örnek, istemci tarafı uygulamasının temel adresini alan ve genellikle ana bilgisayar sayfasındaki etiketin href değerinden <base> türetilen temel adresi ()IWebAssemblyHostEnvironment.BaseAddress ile builder.HostEnvironment.BaseAddress ayarlar.

İstemcinin kendi temel adresini kullanmaya yönelik en yaygın kullanım örnekleri şunlardır:

• WebAssembly/Auto bileşenlerinden veya WebAssembly'deki istemcide çalışan koddan sunucu uygulamasındaki API'lere aynı konak adresinde web API'leri çağrıları yapan istemci Blazor Web App projesi (.Client).
• Sunucu projesine (Client) web API çağrıları yapan barındırılan Blazor WebAssembly bir uygulamanın istemci projesi (Server).

Dış web API'sini (istemci uygulamasıyla aynı URL alanında değil) çağırıyorsanız veya hizmetleri bir sunucu tarafı uygulamasında yapılandırıyorsanız (örneğin, sunucudaki istemci tarafı bileşenlerinin önceden yenilenmesiyle başa çıkmak için), URI'yi web API'sinin temel adresine ayarlayın. Aşağıdaki örnek, ayrı bir web API'sinin https://localhost:5001çalıştığı ve istemci uygulamasından gelen isteklere yanıt vermeye hazır olduğu web API'sinin temel adresini olarak ayarlar:

builder.Services.AddHttpClient<ForecastHttpClient>(client => 
    client.BaseAddress = new Uri("https://localhost:5001"));

Bileşenler, web API'sini çağırmak için yazılanı HttpClient ekler.

Aşağıdaki bileşen kodunda:

• Öncekinin ForecastHttpClient bir örneği eklenir ve bu da türü oluşturulan HttpClientbir .
• Yazılan HttpClient , web API'sinden JSON hava durumu tahmin verileri için get isteği göndermek için kullanılır.

@inject ForecastHttpClient Http

...

@code {
    private Forecast[]? forecasts;

    protected override async Task OnInitializedAsync()
    {
        forecasts = await Http.GetForecastAsync();
    }
}

Örnek BlazorWebAppCallWebApi uygulama , bileşeninde yazılan HttpClient bir web API'sini çağırmayı CallTodoWebApiCsrTypedClient gösterir. Bileşenin ön kayıt ile istemci tarafı işlemeyi (CSR) (InteractiveWebAssemblyişleme modu) benimsediğini, dolayısıyla yazılan istemci hizmeti kaydının hem sunucu projesinin .Client hem de projenin dosyasında göründüğünü Program unutmayın.

Cookietabanlı istek kimlik bilgileri

Bu bölümdeki kılavuz, kimlik doğrulaması cookiekullanan istemci tarafı senaryoları için geçerlidir.

Taşıyıcı cookiebelirteç kimlik doğrulamasından daha güvenli olarak kabul edilen tabanlı kimlik doğrulaması için kimlik bilgileri önceden cookie yapılandırılmış HttpClientbir üzerinde ile çağrılarak AddHttpMessageHandler her web API isteğiyle DelegatingHandler gönderilebilir. İşleyici, tarayıcının çıkış noktaları arası istekler de dahil olmak üzere tanımlama bilgileri veya HTTP kimlik doğrulaması üst bilgileri gibi her istekle kimlik bilgileri göndermesini öneren ile BrowserRequestCredentials.IncludeyapılandırırSetBrowserRequestCredentials.

CookieHandler.cs:

public class CookieHandler : DelegatingHandler
{
    protected override Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken cancellationToken)
    {
        request.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);
        request.Headers.Add("X-Requested-With", ["XMLHttpRequest"]);

        return base.SendAsync(request, cancellationToken);
    }
}

CookieHandler dosyasında kayıtlıdırProgram:

builder.Services.AddTransient<CookieHandler>();

İleti işleyicisi, kimlik doğrulaması gerektiren önceden yapılandırılmış HttpClient tüm dosyalara cookie eklenir:

builder.Services.AddHttpClient(...)
    .AddHttpMessageHandler<CookieHandler>();

Tanıtım için bkz . ASP.NET Core Blazor WebAssembly ile güvenli ASP.NET Çekirdek Identity.

oluştururken HttpRequestMessagetarayıcı isteği kimlik bilgilerini ve üst bilgisini doğrudan ayarlayın:

var requestMessage = new HttpRequestMessage() { ... };

requestMessage.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);
requestMessage.Headers.Add("X-Requested-With", ["XMLHttpRequest"]);

HttpClient ve HttpRequestMessage Fetch API isteği seçenekleriyle

Bu bölümdeki yönergeler taşıyıcı belirteç kimlik doğrulamasını kullanan istemci tarafı senaryoları için geçerlidir.

HttpClient (API belgeleri) ve HttpRequestMessage istekleri özelleştirmek için kullanılabilir. Örneğin, HTTP yöntemini ve istek üst bilgilerini belirtebilirsiniz. Aşağıdaki bileşen bir POST web API uç noktasına istekte bulunur ve yanıt gövdesini gösterir.

TodoRequest.razor:

@page "/todo-request"
@using System.Net.Http.Headers
@using Microsoft.AspNetCore.Components.WebAssembly.Authentication
@inject HttpClient Http
@inject IAccessTokenProvider TokenProvider

<h1>ToDo Request</h1>

<h1>ToDo Request Example</h1>

<button @onclick="PostRequest">Submit POST request</button>

<p>Response body returned by the server:</p>

<p>@responseBody</p>

@code {
    private string? responseBody;

    private async Task PostRequest()
    {
        var requestMessage = new HttpRequestMessage()
        {
            Method = new HttpMethod("POST"),
            RequestUri = new Uri("https://localhost:10000/todoitems"),
            Content =
                JsonContent.Create(new TodoItem
                {
                    Name = "My New Todo Item",
                    IsComplete = false
                })
        };

        var tokenResult = await TokenProvider.RequestAccessToken();

        if (tokenResult.TryGetToken(out var token))
        {
            requestMessage.Headers.Authorization =
                new AuthenticationHeaderValue("Bearer", token.Value);

            requestMessage.Content.Headers.TryAddWithoutValidation(
                "x-custom-header", "value");

            var response = await Http.SendAsync(requestMessage);
            var responseStatusCode = response.StatusCode;

            responseBody = await response.Content.ReadAsStringAsync();
        }
    }

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

Blazor'nin istemci tarafı uygulaması HttpClient Fetch API'sini kullanır ve uzantı yöntemleri ve WebAssemblyHttpRequestMessageExtensionsaracılığıyla HttpRequestMessage isteğe özgü Fetch API seçeneklerini yapılandırıyor. Genel SetBrowserRequestOption uzantı yöntemini kullanarak ek seçenekleri ayarlayın. Blazor temel alınan Fetch API'sinin istek üst bilgilerini doğrudan eklemesi veya değiştirmesi gerekmez. Tarayıcılar gibi kullanıcı aracılarının üst bilgilerle nasıl etkileşimde bulunduğu hakkında daha fazla bilgi için dış kullanıcı aracısı belge kümelerine ve diğer web kaynaklarına başvurun.

HTTP yanıtı genellikle yanıt içeriğinde zaman uyumlu okuma desteği sağlamak için arabelleğe alınıyor. Yanıt akışı desteğini etkinleştirmek için istekte SetBrowserResponseStreamingEnabled uzantı yöntemini kullanın.

Çıkış noktaları arası bir isteğe kimlik bilgilerini eklemek için uzantı yöntemini kullanın SetBrowserRequestCredentials :

requestMessage.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);

Fetch API seçenekleri hakkında daha fazla bilgi için bkz . MDN web belgeleri: WindowOrWorkerGlobalScope.fetch(): Parametreler.

Hataları işleme

Geliştirici kodunda ortaya çıkan web API'si yanıt hatalarını işleyin. Örneğin, GetFromJsonAsync ile web API'sinden bir Content-Type application/jsonJSON yanıtı bekler. Yanıt JSON biçiminde değilse, içerik doğrulaması bir NotSupportedExceptionoluşturur.

Aşağıdaki örnekte, hava durumu tahmini veri isteği için URI uç noktası yanlış yazılmıştır. URI'sinin içinde WeatherForecast olması gerekir, ancak çağrısında olarak WeatherForcastgörünür ve içinde harfi e Forecasteksiktir.

Çağrı JSON'un GetFromJsonAsync döndürülmesini bekler, ancak web API'si text/htmlile işlenmeyen bir özel durum Content-Type için HTML döndürür. İşlenmeyen özel durum, yolu /WeatherForcast bulunamadığından ve ara yazılım istek için bir sayfaya veya görünüme hizmet vermediğinden oluşur.

OnInitializedAsync istemcisinde, NotSupportedException yanıt içeriği JSON olmayan olarak doğrulandığında oluşturulur. Özel durum, özel mantığın hatayı günlüğe catch kaydedebileceği veya kullanıcıya kolay bir hata iletisi sunabildiği blokta yakalanmış olur.

ReturnHTMLOnException.razor:

@page "/return-html-on-exception"
@using {PROJECT NAME}.Shared
@inject HttpClient Http

<h1>Fetch data but receive HTML on unhandled exception</h1>

@if (forecasts == null)
{
    <p><em>Loading...</em></p>
}
else
{
    <h2>Temperatures by Date</h2>

    <ul>
        @foreach (var forecast in forecasts)
        {
            <li>
                @forecast.Date.ToShortDateString():
                @forecast.TemperatureC &#8451;
                @forecast.TemperatureF &#8457;
            </li>
        }
    </ul>
}

<p>
    @exceptionMessage
</p>

@code {
    private WeatherForecast[]? forecasts;
    private string? exceptionMessage;

    protected override async Task OnInitializedAsync()
    {
        try
        {
            // The URI endpoint "WeatherForecast" is misspelled on purpose on the 
            // next line. See the preceding text for more information.
            forecasts = await Http.GetFromJsonAsync<WeatherForecast[]>("WeatherForcast");
        }
        catch (NotSupportedException exception)
        {
            exceptionMessage = exception.Message;
        }
    }
}

Not

Yukarıdaki örnek, tanıtım amaçlıdır. Bir web API'si, bir uç nokta mevcut olmadığında veya sunucuda işlenmeyen bir özel durum oluştuğunda bile JSON döndürecek şekilde yapılandırılabilir.

Daha fazla bilgi için bkz . ASP.NET Core Blazor uygulamalarında hataları işleme.

Çıkış Noktaları Arası Kaynak Paylaşma (CORS)

Tarayıcı güvenliği, bir web sayfasının web sayfasına hizmet verenden farklı bir etki alanına istekte bulunmasını kısıtlar. Bu kısıtlama aynı çıkış noktası ilkesi olarak adlandırılır. Aynı kaynak ilkesi, kötü amaçlı bir sitenin başka bir siteden hassas verileri okumasını kısıtlar (ancak engellemez). Tarayıcıdan farklı bir çıkış noktası olan bir uç noktaya istekte bulunmak için uç noktanın Çıkış Noktaları Arası Kaynak Paylaşımı'nı (CORS) etkinleştirmesi gerekir.

Sunucu tarafı CORS hakkında daha fazla bilgi için bkz . ASP.NET Core'da Çıkış Noktaları Arası İstekleri (CORS) Etkinleştirme. Makalenin örnekleri doğrudan Razor bileşen senaryolarıyla ilgili değildir, ancak makale genel CORS kavramlarını öğrenmek için kullanışlıdır.

İstemci tarafı CORS istekleri hakkında bilgi için bkz . ASP.NET Core Blazor WebAssembly ek güvenlik senaryoları.

Antiforgery desteği

HTTP isteğine kötü amaçlı yazılımdan koruma desteği eklemek için öğesini ekleyin AntiforgeryStateProvider ve RequestToken üst bilgi koleksiyonuna olarak ekleyin RequestVerificationToken:

@inject AntiforgeryStateProvider Antiforgery

private async Task OnSubmit()
{
    var antiforgery = Antiforgery.GetAntiforgeryToken();
    var request = new HttpRequestMessage(HttpMethod.Post, "action");
    request.Headers.Add("RequestVerificationToken", antiforgery.RequestToken);
    var response = await client.SendAsync(request);
    ...
}

Daha fazla bilgi için bkz . ASP.NET Çekirdek Blazor kimlik doğrulaması ve yetkilendirme.

Blazor web API erişimini test etme için çerçeve bileşeni örnekleri

Web API arka uç uygulamalarını doğrudan test etmek için Firefox Browser Developer gibi çeşitli ağ araçları genel kullanıma sunulmuştur. Blazor framework'ün başvuru kaynağı, test için yararlı olan test varlıklarını içerir HttpClient :

HttpClientTest GitHub deposundaki dotnet/aspnetcore varlıklar

Not

.NET başvuru kaynağına yönelik belge bağlantıları genellikle deponun varsayılan dalını yükler ve bu dal .NET'in sonraki sürümü için geçerli geliştirmeyi temsil eder. Belirli bir sürümün etiketini seçmek için Dalları veya etiketleri değiştir açılan listesini kullanın. Daha fazla bilgi için bkz. ASP.NET Core kaynak kodunun sürüm etiketini seçme (dotnet/AspNetCore.Docs #26205).

Ek kaynaklar

Genel

• W3C'de Çıkış Noktaları Arası Kaynak Paylaşımı (CORS)
• ASP.NET Core'da Çıkış Noktaları Arası İstekleri (CORS) etkinleştirme: İçerik bileşenler için değil Razor ASP.NET Core uygulamaları için geçerli olsa da makale genel CORS kavramlarını kapsar.

Aşırı paylaşım saldırılarını azaltma

Web API'leri, toplu atama saldırısı olarak da bilinen bir paylaşım saldırısına karşı savunmasız olabilir. Kötü amaçlı bir kullanıcı, işlenen formun parçası olmayan özellikler için verileri işleyen ve geliştiricinin kullanıcıların değiştirmesine izin vermek istemediği bir HTML formu POST'unu sunucuya yayınladığında bir paylaşım saldırısı oluşur. "Overposting" terimi, kötü amaçlı kullanıcının formla aşırı poz verdiği anlamına gelir.

Fazla paylaşım saldırılarını azaltma yönergeleri için bkz . Öğretici: ASP.NET Core ile web API'sini oluşturma.

Sunucu tarafı

• Sunucu tarafı ASP.NET Core Blazor ek güvenlik senaryoları: Güvenli web API'leri istekleri yapmak için kullanımın HttpClient kapsamını içerir.
• ASP.NET Core'da IHttpClientFactory kullanarak HTTP isteklerinde bulunma
• ASP.NET Core'da HTTPS'i zorunlu kılma
• Kestrel HTTPS uç nokta yapılandırması

İstemci tarafı

• ASP.NET Core Blazor WebAssembly ek güvenlik senaryoları: Güvenli web API'si isteklerinde bulunmak için kullanımı HttpClient kapsayan kapsam içerir.
• ASP.NET Core ile Graph API kullanma Blazor WebAssembly
• API'sini getirme