Volání webového rozhraní API z ASP.NET Core Blazor

Tento článek popisuje, jak volat webové rozhraní API z Blazor aplikace.

Balíček

Balíček System.Net.Http.Json poskytuje rozšiřující metody pro System.Net.Http.HttpClient a System.Net.Http.HttpContent které provádět automatické serializace a deserializace pomocí System.Text.Json. Balíček System.Net.Http.Json poskytuje sdílená architektura .NET a nevyžaduje přidání odkazu na balíček do aplikace.

Ukázkové aplikace

Podívejte se na ukázkové aplikace v dotnet/blazor-samples úložišti GitHub.

BlazorWebAppCallWebApi

Volání externího webového Blazor rozhraní API seznamu úkolů (ne ve webové aplikaci) z Blazor webové aplikace:

• Backend: Aplikace webového rozhraní API pro udržování seznamu úkolů na základě minimálních rozhraní API. Webová aplikace API je samostatná aplikace od Blazor webové aplikace, která je pravděpodobně hostovaná na jiném serveru.
• BlazorApp/BlazorApp.ClientBlazor: Webová aplikace, která volá aplikaci webového rozhraní API s operacemi HttpClient seznamu úkolů, jako jsou vytváření, čtení, aktualizace a odstraňování položek (CRUD) ze seznamu úkolů.

Pro vykreslování na straně klienta (CSR), které zahrnuje interaktivní komponenty WebAssembly a automatické komponenty, které přijaly CSR, se provádějí volání s předem nakonfigurovaným HttpClient zaregistrovaným v Program souboru klientského projektu (BlazorApp.Client):

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

Pro vykreslování na straně serveru (SSR), které zahrnuje předsledované a interaktivní součásti serveru, předsenderované komponenty WebAssembly a automatické komponenty, které jsou předem předsekfinované nebo přijaly SSR, se volání provádějí s registrovaným HttpClient v Program souboru projektu serveru (BlazorApp):

builder.Services.AddHttpClient();

Volání interního rozhraní API seznamu filmů (uvnitř Blazor webové aplikace), kde se rozhraní API nachází v serverovém projektu Blazor webové aplikace:

• BlazorAppBlazor: Webová aplikace, která udržuje seznam filmů:
  • Při provádění operací v seznamu filmů v aplikaci na serveru se použijí běžná volání rozhraní API.
  • Když webového klienta provádí volání rozhraní API, použije se webové rozhraní API pro operace se seznamem filmů na základě minimálních rozhraní API.
• BlazorApp.Client: Klientský projekt Blazor webové aplikace, který obsahuje interaktivní webassembly a automatické komponenty pro správu uživatelů seznamu filmů.

Pro CSR, která zahrnuje interaktivní komponenty WebAssembly a automatické komponenty, které přijaly CSR, se volání rozhraní API provádí prostřednictvím služby založené na klientovi (ClientMovieService), která používá předkonfigurovaný zaregistrovaný HttpClient v Program souboru klientského projektu (BlazorApp.Client). Vzhledem k tomu, že se tato volání provádějí přes veřejný nebo privátní web, je rozhraní API seznamu filmů webové rozhraní API.

Následující příklad získá seznam filmů z koncového /movies bodu:

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

Pro rozhraní SSR, které zahrnují předsledované a interaktivní součásti serveru, předem vysunuté komponenty WebAssembly a automatické komponenty, které jsou předem předsekfinované nebo přijaly SSR, se volání provádějí přímo prostřednictvím serverové služby (ServerMovieService). Rozhraní API nespoléhá na síť, takže se jedná o standardní rozhraní API pro operace CRUD seznamu filmů.

Následující příklad získá seznam filmů:

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

BlazorWebAppCallWebApi_Weather

Ukázková aplikace dat o počasí, která používá vykreslování streamovaných dat pro data o počasí.

BlazorWebAssemblyCallWebApi

Volá webové rozhraní API seznamu úkolů z Blazor WebAssembly aplikace:

• Backend: Aplikace webového rozhraní API pro udržování seznamu úkolů na základě minimálních rozhraní API.
• BlazorTodoBlazor WebAssembly: Aplikace, která volá webové rozhraní API s předem nakonfigurovaným HttpClient seznamem operací CRUD seznamu úkolů.

Scénáře na straně serveru pro volání externích webových rozhraní API

Serverové komponenty volají externí webová rozhraní API pomocí HttpClient instancí, obvykle vytvořených pomocí IHttpClientFactory. Pokyny, které platí pro aplikace na straně serveru, najdete v tématu Vytváření požadavků HTTP pomocí IHttpClientFactory v ASP.NET Core.

Aplikace na straně serveru ve výchozím nastavení neobsahuje HttpClient službu. HttpClient Poskytněte aplikaci pomocí HttpClient infrastruktury továrny.

V souboru Program:

builder.Services.AddHttpClient();

Následující Razor komponenta vytvoří požadavek na webové rozhraní API pro větve GitHubu podobné příkladu základního použití v části Vytváření požadavků HTTP pomocí IHttpClientFactory v článku ASP.NET Core .

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

V předchozím příkladu pro C# 12 nebo novější se pro proměnnou vytvoří branches prázdná matice ([]). V dřívějších verzích jazyka C# vytvořte prázdné pole (Array.Empty<GitHubBranch>()).

Další funkční příklad najdete v příkladu nahrání souboru na straně serveru, který nahraje soubory do kontroleru webového rozhraní API v článku o nahrávání souborů ASP.NET CoreBlazor.

Abstrakce služby pro volání webového rozhraní API

Tato část se týká Blazor webových aplikací, které udržují webové rozhraní API v serverovém projektu nebo transformují volání webového rozhraní API do externího webového rozhraní API.

Při použití interaktivního režimu WebAssembly a automatického vykreslení jsou komponenty standardně předem vygenerovány. Automatické komponenty se také zpočátku interaktivně vykreslují ze serveru před stažením Blazor sady do klienta a aktivací modulu runtime na straně klienta. To znamená, že komponenty používající tyto režimy vykreslování by měly být navrženy tak, aby se úspěšně spouštěly z klienta i ze serveru. Pokud komponenta musí při spuštění na klientovi volat serverové projektové rozhraní API nebo transformovat požadavek na externí webové rozhraní API (který je mimo Blazor webovou aplikaci), doporučuje se tento přístup abstraktovat volání rozhraní API za rozhraním služby a implementovat klientské a serverové verze služby:

• Verze klienta volá webové rozhraní API s předkonfigurovaným HttpClientrozhraním .
• Verze serveru má obvykle přímý přístup k prostředkům na straně serveru. Vložení na HttpClient server, který provádí volání zpět na server, se nedoporučuje , protože síťový požadavek je obvykle zbytečný. Alternativně může být rozhraní API externí pro serverový projekt, ale abstrakce služby pro server se vyžaduje k transformaci požadavku nějakým způsobem, například k přidání přístupového tokenu k žádosti oxidu.

Při použití režimu vykreslování WebAssembly máte také možnost zakázat předběžné vykreslování, takže komponenty se vykreslují pouze z klienta. Další informace najdete v tématu ASP.NET režimy vykreslování coreBlazor.

Příklady (ukázkové aplikace):

• Webové rozhraní API seznamu filmů v BlazorWebAppCallWebApi ukázkové aplikaci
• Streamování webového BlazorWebAppCallWebApi_Weather rozhraní API pro vykreslování dat o počasí v ukázkové aplikaci
• Data o počasí vrácená klientovi v BlazorWebAppOidc ukázkových aplikacích (mimo vzor BFF) nebo BlazorWebAppOidcBff (vzor BFF). Tyto aplikace demonstrují zabezpečená (webová) volání rozhraní API. Další informace najdete v tématu Zabezpečení webové aplikace ASP.NET Core Blazor pomocí OpenID Připojení (OIDC).

Blazor Externí webová rozhraní API webové aplikace

Tato část se týká Blazor webových aplikací, které volají webové rozhraní API spravované samostatným (externím) projektem, který je pravděpodobně hostovaný na jiném serveru.

Blazor Webové aplikace obvykle prerender komponenty WebAssembly na straně klienta a automatické součásti vykreslují na serveru během statického nebo interaktivního vykreslování na straně serveru (SSR). HttpClient služby nejsou ve výchozím nastavení zaregistrované v Blazor hlavním projektu webové aplikace. Pokud je aplikace spuštěná pouze HttpClient se službami zaregistrovanými v .Client projektu, jak je popsáno v části Přidat HttpClient službu , spuštění aplikace způsobí chybu za běhu:

InvalidOperationException: Nelze zadat hodnotu vlastnosti Http typu .... {COMPONENT}'. Neexistuje žádná registrovaná služba typu System.Net.Http.HttpClient.

Použijte některý z následujících přístupů:

• HttpClient Přidejte služby do projektu serveru, aby byly HttpClient dostupné během SSR. V souboru projektu serveru Program použijte následující registraci služby:

  builder.Services.AddHttpClient();
  

  Nevyžaduje se žádný explicitní odkaz na balíček, protože HttpClient sdílené rozhraní poskytuje služby.

  Příklad: Webové rozhraní API seznamu úkolů v BlazorWebAppCallWebApiukázkové aplikaci

• Pokud se pro komponentu WebAssembly, která volá webové rozhraní API, nevyžaduje předběžné vykreslování, zakažte předběžné vykreslování podle pokynů v režimu vykreslování ASP.NET CoreBlazor. Pokud tento přístup přijmete, nemusíte do hlavního Blazor projektu webové aplikace přidávat HttpClient služby, protože komponenta nebude na serveru předem vyřazována.

Další informace naleznete v tématu Služby na straně klienta se nepodařilo vyřešit během předdefinování.

Předem vyřazovaná data

Při předkreslování se komponenty vykreslují dvakrát: nejprve staticky a interaktivně. Stav automaticky neprochází z předem vyřazené komponenty do interaktivní komponenty. Pokud komponenta provádí asynchronní inicializační operace a vykresluje jiný obsah pro různé stavy během inicializace, například "Načítání..." indikátor průběhu, může se zobrazit blikající, když se komponenta vykresluje dvakrát.

Můžete to vyřešit tokem předem předdedukovaného stavu pomocí rozhraní API stavu trvalých komponent, které BlazorWebAppCallWebApi demonstrují a BlazorWebAppCallWebApi_Weatherukázkové aplikace . Když se komponenta vykreslí interaktivně, může se vykreslit stejným způsobem jako ve stejném stavu. Rozhraní API ale v současné době nefunguje s vylepšenou navigaci, kterou můžete obejít zakázáním rozšířené navigace u odkazů na stránku (data-enhanced-nav=false). Další informace naleznete v následujících zdrojích:

• Prerender ASP.NET Core Razor components
• ASP.NET Základní Blazor směrování a navigace
• Podpora stavu trvalých komponent napříč rozšířenými navigacemi na stránkách (dotnet/aspnetcore #51584)

HttpClient Přidání služby

Pokyny v této části platí pro scénáře na straně klienta.

Komponenty na straně klienta volají webová rozhraní API pomocí předkonfigurované HttpClient služby, která se zaměřuje na provádění požadavků zpět na server původu. V kódu pro vývojáře je možné vytvořit další HttpClient konfigurace služby pro jiná webová rozhraní API. Žádosti se skládají pomocí BlazorJSpomocných rutin ON nebo s HttpRequestMessage. Požadavky můžou zahrnovat konfiguraci možností rozhraní API pro načtení.

Příklady konfigurace v této části jsou užitečné jenom v případě, že se pro jednu instanci v aplikaci volá jedno HttpClient webové rozhraní API. Když aplikace musí volat více webových rozhraní API, každá s vlastní základní adresou a konfigurací, můžete přijmout následující přístupy, které jsou popsány dále v tomto článku:

• IHttpClientFactoryPojmenované HttpClient pomocí: Každé webové rozhraní API má jedinečný název. Když kód aplikace nebo komponenta Razor volá webové rozhraní API, použije k volání pojmenovanou HttpClient instanci.
• Typ: HttpClientKaždé webové rozhraní API je zadáno. Když kód aplikace nebo komponenta Razor volá webové rozhraní API, používá k volání typovou HttpClient instanci.

Program V souboru přidejte HttpClient službu, pokud ještě není k dispozici ze Blazor šablony projektu použité k vytvoření aplikace:

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

Předchozí příklad nastaví základní adresu na builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress), která získá základní adresu aplikace a obvykle se odvozuje od <base> hodnoty značky href na stránce hostitele.

Nejběžnější případy použití pro použití vlastní základní adresy klienta jsou:

• Klientský projekt () webové aplikace (.Client.NET 8 nebo novější) provádí volání webového Blazor rozhraní API z komponent WebAssembly nebo kódu, které běží na klientovi ve službě WebAssembly pro rozhraní API v serverové aplikaci.
• Klientský projekt (Client) hostované Blazor WebAssembly aplikace volá webové rozhraní API do serveru projektu (Server). Všimněte si, že šablona hostovaného Blazor WebAssembly projektu už není dostupná v .NET 8 nebo novějším. Hostované Blazor WebAssembly aplikace ale zůstávají podporované pro .NET 8.

Pokud voláte externí webové rozhraní API (ne ve stejném prostoru adres URL jako klientská aplikace), nastavte identifikátor URI na základní adresu webového rozhraní API. Následující příklad nastaví základní adresu webového rozhraní API na https://localhost:5001, kde je spuštěná samostatná webová aplikace API a připravená reagovat na požadavky z klientské aplikace:

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

JSPOMOCNÍCI

HttpClient je k dispozici jako předkonfigurovaná služba pro provádění požadavků zpět na původní server.

HttpClientJSPomocné rutiny ON (System.Net.Http.Json.HttpClientJsonExtensions) se také používají k volání koncových bodů webového rozhraní API třetích stran. HttpClientse implementuje pomocí rozhraní API pro načítání prohlížeče a podléhá jeho omezením, včetně vynucování zásad stejného původu, které je popsáno dále v tomto článku v části Sdílení prostředků mezi zdroji (CORS).

Základní adresa klienta je nastavená na adresu původního serveru. HttpClient Vložení instance do komponenty pomocí direktivy@inject:

@using System.Net.Http
@inject HttpClient Http

System.Net.Http.Json Použití oboru názvů pro přístup k HttpClientJsonExtensions, včetně GetFromJsonAsync, PutAsJsonAsynca PostAsJsonAsync:

@using System.Net.Http.Json

Následující části se týkají JSpomocných rutin ON:

• GET
• POST
• PUT
• PATCH

System.Net.Http obsahuje další metody pro odesílání požadavků HTTP a přijímání odpovědí HTTP, například pro odeslání požadavku DELETE. Další informace najdete v části DELETE a další metody rozšíření.

GET from JSON (GetFromJsonAsync)

GetFromJsonAsync odešle požadavek HTTP GET a parsuje JStělo odpovědi ON a vytvoří objekt.

V následujícím kódu todoItems komponenty se zobrazí komponenta. GetFromJsonAsync je volána po dokončení inicializace komponenty (OnInitializedAsync).

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

POST as JSON (PostAsJsonAsync)

PostAsJsonAsync odešle požadavek POST na zadaný identifikátor URI obsahující hodnotu serializovanou jako JSON v textu požadavku.

V následujícím kódu newItemName komponenty je poskytována vázaným prvkem komponenty. Metoda AddItem se aktivuje výběrem elementu <button> .

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

PostAsJsonAsync vrátí hodnotu HttpResponseMessage. K deserializaci JSobsahu ON ze zprávy odpovědi použijte metodu ReadFromJsonAsync rozšíření. Následující příklad čte JSdata o počasí ON jako pole:

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

PUT as JSON (PutAsJsonAsync)

PutAsJsonAsync odešle požadavek HTTP PUT s obsahem s kódováním JSON.

V následujícím kódu editItem komponenty jsou hodnoty pro Name a IsCompleted jsou poskytovány vázané prvky komponenty. Položka Id je nastavena, když je položka vybrána v jiné části uživatelského rozhraní (není zobrazena) a EditItem je volána. Metoda SaveItem se aktivuje výběrem elementu <button> . Následující příklad nezobrazuje načítání todoItems pro stručnost. Příklad načítání položek najdete v části GET from JSON (GetFromJsonAsync).

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

PutAsJsonAsync vrátí hodnotu HttpResponseMessage. K deserializaci JSobsahu ON ze zprávy odpovědi použijte metodu ReadFromJsonAsync rozšíření. Následující příklad čte JSdata o počasí ON jako pole:

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

PATCH as JSON (PatchAsJsonAsync)

PatchAsJsonAsync odešle požadavek HTTP PATCH s obsahem s kódováním JSON.

Poznámka:

Další informace najdete v tématu JsonPatch ve webovém rozhraní API ASP.NET Core.

V následujícím příkladu PatchAsJsonAsyncJSobdrží dokument ON PATCH jako řetězec prostého textu s řídicími uvozovkami:

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

PatchAsJsonAsync vrátí hodnotu HttpResponseMessage. K deserializaci JSobsahu ON ze zprávy odpovědi použijte metodu ReadFromJsonAsync rozšíření. Následující příklad čte JSdata položky typu ON todo jako pole. Pokud metoda nevrací žádná data položek, vytvoří se prázdné pole, takže content po provedení příkazu není null:

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

Rozložené s odsazením, mezerami a nepoupravenými uvozovkami, se nekódovaný dokument PATCH zobrazí jako následující JSZAPNUTO:

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

Pro zjednodušení vytváření dokumentů PATCH v aplikaci vydávajících požadavky PATCH může aplikace používat podporu .NET ON JSPATCH, jak ukazuje následující doprovodné materiály.

Microsoft.AspNetCore.JsonPatch Nainstalujte balíček NuGet a pomocí funkcí rozhraní API balíčku JsonPatchDocument vytvořte požadavek PATCH.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Přidejte @using direktivy pro System.Text.Json, System.Text.Json.Serializationa Microsoft.AspNetCore.JsonPatch obory názvů na začátek Razor komponenty:

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

Nastavte pro sadu metodu IsCompleteReplaceTodoItem:trueJsonPatchDocument

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

Předejte operace dokumentu (patchDocument.Operations) do PatchAsJsonAsync volání:

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

JsonSerializerOptions.DefaultIgnoreCondition je nastavena tak, aby JsonIgnoreCondition.WhenWritingDefault ignorovala vlastnost pouze v případě, že se rovná výchozí hodnotě pro jeho typ.

Pokud chcete datovou JSčást ON prezentovat v příjemném formátu pro zobrazení, přidejte JsonSerializerOptions.WriteIndented ji true na hodnotu nastavenou. Zápis odsazený JSon nemá žádný vliv na zpracování požadavků PATCH a obvykle se neprovádí v produkčních aplikacích pro požadavky webového rozhraní API.

Pokud chcete do webového rozhraní API přidat akci kontroleru PATCH, postupujte podle pokynů v článku JsonPatch v ASP.NET core webovém rozhraní API. Případně je možné zpracování požadavků PATCH implementovat jako minimální rozhraní API pomocí následujícího postupu.

Přidejte odkaz na Microsoft.AspNetCore.Mvc.NewtonsoftJson balíček NuGet do aplikace webového rozhraní API.

Poznámka:

Není nutné do aplikace přidat odkaz Microsoft.AspNetCore.JsonPatch na balíček, protože odkaz na Microsoft.AspNetCore.Mvc.NewtonsoftJson balíček automaticky tranzitivně přidá odkaz na balíček pro Microsoft.AspNetCore.JsonPatch.

Program Do souboru přidejte direktivu @usingMicrosoft.AspNetCore.JsonPatch pro obor názvů:

using Microsoft.AspNetCore.JsonPatch;

Zadejte koncový bod kanálu zpracování požadavků webového rozhraní API:

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

Upozorňující

Stejně jako u ostatních příkladů v jsonPatch v článku o webovém rozhraní API ASP.NET Core nechrání předchozí rozhraní PATCH API webové rozhraní API před útoky nadměrného publikování. Další informace najdete v tématu Kurz: Vytvoření webového rozhraní API s ASP.NET Core.

Plně funkční prostředí PATCH najdete v BlazorWebAppCallWebApiukázkové aplikaci.

DELETE (DeleteAsync) a další rozšiřující metody

System.Net.Http obsahuje další metody rozšíření pro odesílání požadavků HTTP a přijímání odpovědí HTTP. HttpClient.DeleteAsync slouží k odeslání požadavku HTTP DELETE do webového rozhraní API.

V následujícím kódu <button> komponenty prvek volá metodu DeleteItem . Vázaný <input> prvek poskytuje id položku k odstranění.

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

Pojmenované HttpClient pomocí IHttpClientFactory

IHttpClientFactory podporují se služby a konfigurace pojmenovaného HttpClient souboru.

Poznámka:

Alternativou k použití pojmenovaného HttpClient z objektu IHttpClientFactory je použití typu HttpClient. Další informace najdete v části Typ.HttpClient

Přidejte do Microsoft.Extensions.Http aplikace balíček NuGet.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Program V souboru klientského projektu:

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

Pokud se pojmenovaný klient má používat předseklovanými komponentami Blazor webové aplikace na straně klienta, měla by se předchozí registrace služby zobrazit v projektu serveru i v .Client projektu. Na serveru builder.HostEnvironment.BaseAddress se nahrazuje základní adresou webového rozhraní API, která je popsána níže.

Předchozí příklad na straně klienta nastaví základní adresu na builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress), která získá základní adresu pro aplikaci na straně klienta a obvykle je odvozena od <base> hodnoty značky href na stránce hostitele.

Nejběžnější případy použití pro použití vlastní základní adresy klienta jsou:

• Klientský projekt (.Client) webové aplikace, která provádí volání webového Blazor rozhraní API z webových komponent nebo kódu, které běží na klientovi ve službě WebAssembly, na rozhraní API v serverové aplikaci na stejné adrese hostitele.
• Klientský projekt (Client) hostované Blazor WebAssembly aplikace, která provádí volání webového rozhraní API do projektu serveru (Server).

Pokud voláte externí webové rozhraní API (ne ve stejném prostoru adres URL jako klientská aplikace) nebo konfigurujete služby v aplikaci na straně serveru (například pro řešení předběžného nastavení komponent na straně klienta na serveru), nastavte identifikátor URI na základní adresu webového rozhraní API. Následující příklad nastaví základní adresu webového rozhraní API na https://localhost:5001, kde je spuštěná samostatná webová aplikace API a připravená reagovat na požadavky z klientské aplikace:

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

V následujícím kódu komponenty:

• Instance IHttpClientFactory vytvoří pojmenovanou HttpClient.
• HttpClient Název se používá k vydání požadavku GET na data předpovědi počasí z JSwebového rozhraní API na adrese /forecast.

@inject IHttpClientFactory ClientFactory

...

@code {
    private Forecast[]? forecasts;

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

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

Ukázková BlazorWebAppCallWebApiaplikace ukazuje volání webového rozhraní API s názvem HttpClient ve své CallTodoWebApiCsrNamedClient komponentě. Další funkční ukázku v klientské aplikaci založenou na volání Microsoft Graphu s názvem HttpClientnajdete v tématu Použití rozhraní Graph API s ASP.NET Core Blazor WebAssembly.

Zadaný HttpClient

Typed HttpClient používá k vrácení dat z jednoho nebo více koncových bodů webového rozhraní API jednu nebo více instancí aplikace HttpClient ( výchozí nebo pojmenované).

Poznámka:

Alternativou k použití zadaného typu HttpClient je použití pojmenovaného HttpClient z objektu IHttpClientFactory. Další informace najdete v části Pojmenované HttpClient s oddílem IHttpClientFactory .

Přidejte do Microsoft.Extensions.Http aplikace balíček NuGet.

Poznámka:

Pokyny k přidávání balíčků do aplikací .NET najdete v článcích v části Instalace a správa balíčků na webu Pracovní postup používání balíčků (dokumentace k NuGetu). Ověřte správné verze balíčků na NuGet.org.

Následující příklad vydává požadavek GET na JSdata předpovědi počasí z webového rozhraní API na adrese /forecast.

ForecastHttpClient.cs:

using System.Net.Http.Json;

namespace BlazorSample.Client;

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

Program V souboru klientského projektu:

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

Pokud se má typový klient používat v předem uspořádaných komponentách Blazor webové aplikace na straně klienta, měla by se předchozí registrace služby zobrazit jak v projektu serveru, tak v projektu serveru i v .Client projektu. Na serveru builder.HostEnvironment.BaseAddress se nahrazuje základní adresou webového rozhraní API, která je popsána níže.

Předchozí příklad nastaví základní adresu na builder.HostEnvironment.BaseAddress (IWebAssemblyHostEnvironment.BaseAddress), která získá základní adresu pro aplikaci na straně klienta a obvykle je odvozena z <base> hodnoty značky href na stránce hostitele.

Nejběžnější případy použití pro použití vlastní základní adresy klienta jsou:

• Klientský projekt (.Client) webové aplikace, která provádí volání webového Blazor rozhraní API z webových komponent nebo kódu, které běží na klientovi ve službě WebAssembly, na rozhraní API v serverové aplikaci na stejné adrese hostitele.
• Klientský projekt (Client) hostované Blazor WebAssembly aplikace, která provádí volání webového rozhraní API do projektu serveru (Server).

Pokud voláte externí webové rozhraní API (ne ve stejném prostoru adres URL jako klientská aplikace) nebo konfigurujete služby v aplikaci na straně serveru (například pro řešení předběžného nastavení komponent na straně klienta na serveru), nastavte identifikátor URI na základní adresu webového rozhraní API. Následující příklad nastaví základní adresu webového rozhraní API na https://localhost:5001, kde je spuštěná samostatná webová aplikace API a připravená reagovat na požadavky z klientské aplikace:

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

Komponenty vloží typ, HttpClient který volá webové rozhraní API.

V následujícím kódu komponenty:

• Instance předchozího vloženíForecastHttpClient, která vytvoří typ .HttpClient
• Typ se HttpClient používá k vydání požadavku GET na JSdata předpovědi počasí z webového rozhraní API.

@inject ForecastHttpClient Http

...

@code {
    private Forecast[]? forecasts;

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

Ukázková BlazorWebAppCallWebApiaplikace ukazuje volání webového rozhraní API s typem HttpClient v jeho CallTodoWebApiCsrTypedClient komponentě. Všimněte si, že komponenta přijímá a vykreslování na straně klienta (CSR) (InteractiveWebAssemblyrežim vykreslování) s předběžném vykreslováním, takže se v souboru projektu serveru i .Client projektu zobrazí Program registrace zadané klientské služby.

CookiePřihlašovací údaje žádosti na základě

Pokyny v této části platí pro scénáře na straně klienta, které spoléhají na ověřování cookie.

Pro cookieověřování založené na základě, které je považováno za bezpečnější než ověřování nosného tokenu, cookie je možné přihlašovací údaje odesílat s každou žádostí webového rozhraní API voláním AddHttpMessageHandler s DelegatingHandler předkonfigurovaným HttpClient. Obslužná rutina se konfiguruje SetBrowserRequestCredentials tak BrowserRequestCredentials.Include, aby prohlížeč posílal přihlašovací údaje s jednotlivými požadavky, jako cookiejsou hlavičky ověřování HTTP, včetně požadavků mezi zdroji.

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

Soubor CookieHandler je zaregistrovaný v souboru Program :

builder.Services.AddTransient<CookieHandler>();

Obslužná rutina zprávy se přidá do libovolného předkonfigurovaného objektu HttpClient , který vyžaduje cookie ověření:

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

Ukázku najdete v tématu Zabezpečení ASP.NET Core Blazor WebAssembly s ASP.NET Core Identity.

Při vytváření HttpRequestMessagepožadavku prohlížeče nastavte přihlašovací údaje a hlavičku přímo:

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

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

HttpClient a HttpRequestMessage s možnostmi požadavků rozhraní API pro načtení

Pokyny v této části platí pro scénáře na straně klienta, které spoléhají na ověřování nosných tokenů.

HttpClient (Dokumentace k rozhraní API) a HttpRequestMessage lze ji použít k přizpůsobení požadavků. Můžete například zadat metodu HTTP a hlavičky požadavku. Následující komponenta odešle POST požadavek na koncový bod webového rozhraní API a zobrazí text odpovědi.

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

BlazorImplementace HttpClient rozhraní API na straně klienta používá rozhraní Fetch API a konfiguruje základní možnosti rozhraní Fetch API specifické pro požadavky prostřednictvím HttpRequestMessage rozšiřujících metod a WebAssemblyHttpRequestMessageExtensions. Nastavte další možnosti pomocí obecné SetBrowserRequestOption metody rozšíření. Blazor a podkladové rozhraní API pro načítání přímo nepřidávejte ani neupravují hlavičky požadavků. Další informace o tom, jak uživatelé agenti, jako jsou prohlížeče, pracují se záhlavími, najdete v dokumentaci externích uživatelských agentů a dalších webových prostředcích.

Odpověď HTTP je obvykle uložena do vyrovnávací paměti, aby bylo možné povolit podporu synchronních čtení v obsahu odpovědi. Pokud chcete povolit podporu streamování odpovědí, použijte v požadavku metodu SetBrowserResponseStreamingEnabled rozšíření.

Pokud chcete do požadavku mezi zdroji zahrnout přihlašovací údaje, použijte metodu SetBrowserRequestCredentials rozšíření:

requestMessage.SetBrowserRequestCredentials(BrowserRequestCredentials.Include);

Další informace o možnostech rozhraní API pro načítání najdete ve webové dokumentaci MDN: WindowOrWorkerGlobalScope.fetch(): Parametry.

Zpracování chyb

Zpracování chyb odpovědí webového rozhraní API v kódu vývojáře při jejich výskytu Například GetFromJsonAsync očekává odpověď ON z webového rozhraní API s příponou Content-Typeapplication/json.JS Pokud odpověď není ve JSformátu ON, ověření obsahu vyvolá NotSupportedExceptionchybu .

V následujícím příkladu je koncový bod identifikátoru URI pro požadavek na data předpovědi počasí chybně napsaný. Identifikátor URI by měl být WeatherForecast uveden ve volání jako WeatherForcast, který chybí písmeno e v Forecast.

Volání GetFromJsonAsync očekává vrácení funkce ON, ale webové rozhraní API vrátí kód HTML pro neošetřenou výjimku s chybou Content-Typetext/html.JS Neošetřená výjimka nastane, protože cesta /WeatherForcast nebyla nalezena a middleware nemůže pro požadavek obsluhovat stránku ani zobrazení.

V OnInitializedAsync klientovi se vyvolá, NotSupportedException když se obsah odpovědi ověří jako nezapněteJS. Výjimka se zachytí v catch bloku, kde vlastní logika může chybu protokolovat nebo uživateli zobrazit popisnou chybovou zprávu.

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

Poznámka:

Předchozí příklad je určený pro demonstrační účely. Webové rozhraní API je možné nakonfigurovat tak, aby se vracelo JS, i když koncový bod neexistuje nebo na serveru dojde k neošetřené výjimce.

Další informace najdete v tématu Zpracování chyb v aplikacích ASP.NET CoreBlazor.

Cross-Origin Resource Sharing (CORS)

Zabezpečení prohlížeče omezuje webovou stránku v provádění požadavků na jinou doménu než webovou stránku, která obsluhovala webovou stránku. Toto omezení se označuje jako zásada stejného zdroje. Zásady stejného původu omezují (ale nebrání) škodlivému webu číst citlivá data z jiného webu. Aby bylo možné provádět žádosti z prohlížeče do koncového bodu s jiným původem, musí koncový bod povolit sdílení prostředků mezi zdroji (CORS).

Další informace o CORS na straně serveru najdete v tématu Povolení požadavků mezi zdroji (CORS) v ASP.NET Core. Příklady článku se netýknou přímo Razor komponentními scénáři, ale článek je užitečný pro výuku obecných konceptů CORS.

Informace o požadavcích CORS na straně klienta najdete v ASP.NET dalších Blazor WebAssembly scénářích zabezpečení.

Podpora antiforgery

Chcete-li přidat podporu antiforgery do požadavku HTTP, vložte AntiforgeryStateProvider a přidejte RequestToken do kolekce hlaviček jako 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);
    ...
}

Další informace najdete v tématu ASP.NET ověřování a autorizace jádraBlazor.

Blazor Příklady komponent architektury pro testování přístupu k webovému rozhraní API

Různé síťové nástroje jsou veřejně dostupné pro testování back-endových aplikací webového rozhraní API přímo, například vývojář prohlížeče Firefox. Blazor Referenční zdroj architektury zahrnuje HttpClient testovací prostředky, které jsou užitečné pro testování:

HttpClientTest prostředky v úložišti dotnet/aspnetcore GitHub

Poznámka:

Odkazy na dokumentaci k referenčnímu zdroji .NET obvykle načítají výchozí větev úložiště, která představuje aktuální vývoj pro příští verzi .NET. Pokud chcete vybrat značku pro konkrétní verzi, použijte rozevírací seznam pro přepnutí větví nebo značek. Další informace najdete v tématu Jak vybrat značku verze zdrojového kódu ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Další materiály

OBECNÉ

• Sdílení prostředků mezi zdroji (CORS) na webu konsorcia W3C
• Povolení žádostí mezi zdroji (CORS) v ASP.NET Core: I když se obsah vztahuje na aplikace ASP.NET Core, ne Razor komponenty, článek se zabývá obecnými koncepty CORS.

Na straně serveru

• Další scénáře zabezpečení na straně serveru ASP.NET CoreBlazor: Zahrnuje pokrytí při použití HttpClient k zajištění zabezpečených požadavků webového rozhraní API.
• Vytváření požadavků HTTP pomocí IHttpClientFactory v ASP.NET Core
• Vynucení HTTPS v ASP.NET Core
• Kestrel Konfigurace koncového bodu HTTPS

Na straně klienta

• ASP.NET core Blazor WebAssembly další scénáře zabezpečení: Zahrnuje pokrytí při použití HttpClient k vytváření zabezpečených požadavků webového rozhraní API.
• Použití Graph API s ASP.NET Core Blazor WebAssembly
• Načtení rozhraní API