Udostępnij za pośrednictwem

Platforma Blazor ASP.NET Core — podstawy

  • Artykuł

Uwaga

Nie jest to najnowsza wersja tego artykułu. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ostrzeżenie

Ta wersja ASP.NET Core nie jest już obsługiwana. Aby uzyskać więcej informacji, zobacz zasady pomocy technicznej platformy .NET i platformy .NET Core. Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Ważne

Te informacje odnoszą się do produktu w wersji wstępnej, który może zostać znacząco zmodyfikowany, zanim zostanie wydany komercyjnie. Firma Microsoft nie udziela żadnych gwarancji, jawnych lub domniemanych, w odniesieniu do informacji podanych w tym miejscu.

Aby zapoznać się z bieżącą wersją, zobacz wersję tego artykułu platformy .NET 9.

Artykuły dotyczące podstaw zawierają wskazówki na temat podstawowych pojęć platformy Blazor. Niektóre pojęcia wiążą się z podstawową znajomością składników Razor, które dokładniej opisano w następnej sekcji tego artykułu i szczegółowo omówiono w artykułach dotyczących składników.

Pojęcia dotyczące renderowania statycznego i interaktywnego

Razor składniki są renderowane statycznie lub interaktywnie renderowane.

Renderowanie statyczne lub statyczne to scenariusz po stronie serwera, który oznacza, że składnik jest renderowany bez możliwości współdziałania między użytkownikiem a kodem .NET/C#. Zdarzenia JavaScript i HTML DOM pozostają nienaruszone, ale żadne zdarzenia użytkownika na kliencie nie mogą być przetwarzane przy użyciu platformy .NET uruchomionej na serwerze.

Renderowanie interakcyjne lub interakcyjne oznacza, że składnik ma pojemność przetwarzania zdarzeń platformy .NET za pośrednictwem kodu języka C#. Zdarzenia platformy .NET są przetwarzane na serwerze przez środowisko uruchomieniowe ASP.NET Core lub w przeglądarce na kliencie przez środowisko uruchomieniowe oparte na Blazor zestawie WebAssembly.

Ważne

W przypadku korzystania z elementu Blazor Web Appwiększość przykładowych Blazor składników dokumentacji wymaga interakcyjności do działania i zademonstrowania pojęć omówionych w artykułach. Podczas testowania przykładowego składnika dostarczonego przez artykuł upewnij się, że aplikacja przyjmuje globalną interakcyjność lub składnik przyjmuje tryb renderowania interaktywnego.

Więcej informacji na temat tych pojęć i sposobu kontrolowania renderowania statycznego i interakcyjnego można znaleźć w artykule ASP.NET Core render modes (Tryby renderowania podstawowegoBlazor) w Blazor dalszej części dokumentacji.

Pojęcia dotyczące renderowania klienta i serwera

W całej Blazor dokumentacji działanie wykonywane w systemie użytkownika ma miejsce po stronie klienta lub klienta. Działanie, które odbywa się na serwerze, mówi się, że występuje po stronie serwera lub serwera.

Termin renderowania oznacza tworzenie znaczników HTML wyświetlanych przez przeglądarki.

  • Renderowanie po stronie klienta (CSR) oznacza, że końcowy znacznik HTML jest generowany przez środowisko uruchomieniowe zestawu WebAssembly platformy .NET na kliencie. Brak kodu HTML dla interfejsu użytkownika wygenerowanego przez klienta aplikacji jest wysyłany z serwera do klienta na potrzeby tego typu renderowania. Zakłada się, że interakcyjność użytkownika ze stroną. Nie ma takiej koncepcji, jak statyczne renderowanie po stronie klienta. Zakłada się, że csr jest interakcyjne, więc "interaktywne renderowanie po stronie klienta" i "interakcyjne csr" nie są używane przez branżę ani w Blazor dokumentacji.

  • Renderowanie po stronie serwera (SSR) oznacza, że ostateczny znacznik HTML jest generowany przez środowisko uruchomieniowe ASP.NET Core na serwerze. Kod HTML jest wysyłany do klienta za pośrednictwem sieci do wyświetlania przez przeglądarkę klienta. Klient tego typu renderowania nie tworzy kodu HTML dla interfejsu użytkownika wygenerowanego przez serwer aplikacji. SSR może mieć dwie odmiany:

    • Statyczny przewodnik SSR: serwer tworzy statyczny kod HTML, który nie zapewnia interakcyjności użytkownika ani stanu Razor składnika.
    • Interakcyjne SSR: Blazor zdarzenia zezwalają na interakcyjność użytkownika i Razor stan składnika jest utrzymywany przez platformę Blazor .

  • Prerendering to proces początkowego renderowania zawartości strony na serwerze bez włączania procedur obsługi zdarzeń dla renderowanych kontrolek. Serwer zwraca interfejs użytkownika HTML strony tak szybko, jak to możliwe w odpowiedzi na początkowe żądanie, co sprawia, że aplikacja czuje się bardziej elastyczna dla użytkowników. Prerendering może również poprawić optymalizację aparatu wyszukiwania (SEO) przez renderowanie zawartości początkowej odpowiedzi HTTP używanej przez wyszukiwarki do obliczania rangi strony. Prerendering zawsze następuje ostateczne renderowanie na serwerze lub kliencie.

Składniki Razor

Aplikacje Blazor są oparte na składnikach Razor, często nazywanych tylko składnikami. Składnik to element interfejsu użytkownika, taki jak strona, okno dialogowe lub formularz wprowadzania danych. Składniki to klasy języka C# na platformie .NET wbudowane w zestawy platformy .NET.

Składnia Razor odnosi się do sposobu, w jaki składniki są zwykle zapisywane w postaci strony znaczników Razor na potrzeby obsługi kompozycji i logiki interfejsu użytkownika po stronie klienta. Aparat Razor to składnia do łączenia języka znaczników HTML z kodem w języku C# zaprojektowana pod kątem produktywności deweloperów. W plikach Razor używa się rozszerzenia nazwy pliku .razor.

Chociaż niektórzy deweloperzy Blazor i autorzy zasobów online używają terminu „składniki Blazor”, w dokumentacji unika się tego terminu i powszechnie używa się terminów „składniki Razor” lub „składniki”.

W dokumentacji platformy Blazor przyjmuje się kilka konwencji dotyczących prezentowania i omawiania składników:

  • Ogólnie rzecz biorąc, przykłady są zgodne z konwencjami kodowania ASP.NET Core/C# i wytycznymi inżynieryjnymi. Aby uzyskać więcej informacji, zobacz następujące zasoby:
  • Kod projektu, ścieżki i nazwy plików, nazwy szablonów projektu i inne terminy specjalistyczne są napisane w języku angielskim (Stany Zjednoczone) i zwykle są oznaczone jako kod.
  • Składniki są zwykle wskazywane za pomocą ich nazw klas języka C# (z wielkością liter jak w języku Pascal) i są określane jako składniki (ang. „component”). Na przykład typowy składnik do przekazywania plików jest określany jako „składnik FileUpload”.
  • Zazwyczaj nazwa klasy C# składnika jest taka sama jak jego nazwa pliku.
  • Składniki podlegające trasowaniu mają zwykle ustawiane względne adresy URL z użyciem nazwy klasy składnika w konwencji zapisu, w której odstępy zastępuje się myślnikami (zapis „kebabowy”). Na przykład składnik FileUpload zawiera konfigurację routingu na potrzeby docierania do renderowanego składnika pod względnym adresem URL /file-upload. Routing i nawigację omówiono w artykule ASP.NET Core Blazor — routing i nawigacja.
  • Gdy jest używanych wiele wersji składnika, są one numerowane sekwencyjnie. Na przykład FileUpload3 składnik jest osiągany pod adresem /file-upload-3.
  • Razor dyrektywy w górnej części definicji składnika (.razor file) są umieszczane w następującej kolejności: @page, @rendermode (.NET 8 lub nowsza), @using instrukcje, inne dyrektywy w kolejności alfabetycznej.
  • Mimo że nie są wymagane dla private członków, modyfikatory dostępu są używane w przykładach artykułów i przykładowych aplikacjach. Na przykład parametr private jest podawany w celu zadeklarowania pola o nazwie maxAllowedFiles jako private int maxAllowedFiles = 3;.
  • Wartości parametrów składników prowadzą z zastrzeżonym @ symbolemRazor, ale nie jest to wymagane. Literały (na przykład wartości logiczne), słowa kluczowe (na przykład this), a null jako wartości parametrów składnika nie są poprzedzone prefiksem @, ale jest to również tylko konwencja dokumentacji. Jeśli chcesz, twój własny kod może prefiksować literały @ .
  • Klasy języka C# używają słowa kluczowego this i unikaj prefiksowania pól ze znakiem podkreślenia (_), które są przypisane do konstruktorów, co różni się od wytycznych inżynieryjnych dotyczących platformy ASP.NET Core.
  • W przykładach korzystających z konstruktorów podstawowych (C# 12 lub nowszych) podstawowe parametry konstruktora są zwykle używane bezpośrednio przez składowe klasy.

Dodatkowe informacje na Razor temat składni składników znajdują się w Razor sekcji składni składników ASP.NET CoreRazor.

Poniżej przedstawiono przykładowy składnik licznika i część aplikacji utworzonej na podstawie szablonu projektu Blazor. Szczegółowe omówienie składników można znaleźć w artykułach dotyczących składników w dalszej części dokumentacji. W poniższym przykładzie przedstawiono pojęcia dotyczące składników przedstawione w artykułach dotyczących podstaw, a w dalszej części dokumentacji znajdują się artykuły dotyczące składników.

Counter.razor:

Składnik zakłada, że tryb renderowania interaktywnego jest dziedziczony z składnika nadrzędnego lub stosowany globalnie do aplikacji.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

Składnik zakłada, że tryb renderowania interaktywnego jest dziedziczony z składnika nadrzędnego lub stosowany globalnie do aplikacji.

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount() => currentCount++;
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<PageTitle>Counter</PageTitle>

<h1>Counter</h1>

<p role="status">Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

Poprzedni składnik Counter:

  • Ustawia swoją trasę za pomocą dyrektywy @page w pierwszym wierszu.
  • Ustawia tytuł i nagłówek strony.
  • Renderuje bieżącą liczbę za pomocą @currentCount. currentCount jest zmienną całkowitą zdefiniowaną w kodzie C# bloku @code.
  • Wyświetla przycisk wyzwalający metodę IncrementCount, która również znajduje się w bloku @code i zwiększa wartość zmiennej currentCount.

Tryby renderowania

Artykuły w węźle Podstawy odwołują się do koncepcji trybów renderowania. Ten temat został szczegółowo omówiony w artykule ASP.NET Core Blazor render tryby w węźle Składniki, który pojawia się po węźle Podstawy artykułów.

W przypadku wczesnych odwołań w tym węźle artykułów dotyczących koncepcji trybu renderowania należy pamiętać tylko o następujących kwestiach:

Każdy składnik w programie Blazor Web App przyjmuje tryb renderowania w celu określenia modelu hostingu, którego używa, gdzie jest renderowany i czy jest renderowany statycznie na serwerze, renderowany na potrzeby interakcyjności użytkownika na serwerze lub renderowany na potrzeby interakcyjności użytkownika na kliencie (zwykle z prerenderingiem na serwerze).

Blazor Server i Blazor WebAssembly aplikacje dla wersji ASP.NET Core przed platformą .NET 8 pozostają naprawione w przypadku koncepcji modelu hostingu, a nie trybów renderowania. Tryby renderowania są koncepcyjnie stosowane do Blazor Web Apps na platformie .NET 8 lub nowszej.

W poniższej tabeli przedstawiono dostępne tryby renderowania składników renderowania Razor w obiekcie Blazor Web App. Tryby renderowania są stosowane do składników z dyrektywą @rendermode dotyczącą wystąpienia składnika lub definicji składnika. Można również ustawić tryb renderowania dla całej aplikacji.

Nazwa/nazwisko opis Lokalizacja renderowania Interakcyjny
Serwer statyczny Renderowanie statyczne po stronie serwera (statyczne SSR) Serwer
Serwer interaktywny Interakcyjne renderowanie po stronie serwera (interakcyjne SSR) przy użyciu polecenia Blazor Server Serwer
Interakcyjny zestaw WebAssembly Renderowanie po stronie klienta (CSR) przy użyciu Blazor WebAssembly† Klient
Autointerakcyjne Interakcyjne SSR przy użyciu Blazor Server początkowego, a następnie CSR podczas kolejnych wizyt po Blazor pobraniu pakietu Serwer, a następnie klient

† przyjmuje się, że renderowanie po stronie klienta (CSR) jest interaktywne. "Interaktywne renderowanie po stronie klienta" i "interakcyjne csr" nie są używane przez branżę Blazor ani w dokumentacji.

Powyższe informacje na temat trybów renderowania to wszystko, co musisz wiedzieć, aby zrozumieć artykuły dotyczące węzła Podstawy . Jeśli dopiero zaczynasz Blazor czytać artykuły w spisie treści, możesz opóźnić korzystanie ze szczegółowych informacji na temat trybów renderowania, dopóki nie osiągniesz artykułu trybów renderowania ASP.NET Core Blazor w węźle SkładnikiBlazor.

Model obiektów dokumentu (DOM)

Odwołania do modelu obiektów dokumentów używają skrótu DOM.

Aby uzyskać więcej informacji, zobacz następujące zasoby:

Podzestaw interfejsów API platformy .NET dla Blazor WebAssembly aplikacji

Wyselekcjonowana lista określonych interfejsów API platformy .NET obsługiwanych w przeglądarce Blazor WebAssembly nie jest dostępna. Można jednak ręcznie wyszukać listę interfejsów API platformy .NET z adnotacjami [UnsupportedOSPlatform("browser")] , aby odnaleźć interfejsy API platformy .NET, które nie są obsługiwane w zestawie WebAssembly.

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Aby uzyskać więcej informacji, zobacz następujące zasoby:

Przykładowe aplikacje

Przykładowe aplikacje z dokumentacji są dostępne do przejrzenia i pobrania:

Blazor przykładowe repozytorium GitHub (dotnet/blazor-samples)

Znajdź przykładową aplikację, wybierając najpierw folder wersji zgodny z wersją platformy .NET, z którą pracujesz.

Przykłady aplikacji w repozytorium:

Przykładowe repozytorium zawiera dwa typy przykładów:

  • Przykładowe aplikacje fragmentu kodu zawierają przykłady kodu wyświetlane w artykułach. Te aplikacje kompilowane, ale nie muszą być uruchamiane aplikacje. Te aplikacje są przydatne tylko do uzyskiwania przykładowego kodu wyświetlanego w artykułach.
  • Przykłady aplikacji towarzyszących Blazor artykułom kompilowania i uruchamiania dla następujących scenariuszy:
    • Blazor Server z EF Core
    • Blazor Server i Blazor WebAssembly z SignalR
    • Blazor WebAssembly — rejestrowanie z obsługą zakresów

Aby uzyskać więcej informacji i listę przykładów w repozytorium, zobacz Blazor przykładowe repozytorium GitHub README.md pliku.

Podstawowa aplikacja testowa repozytorium ASP.NET Core jest również przydatnym zestawem przykładów dla różnych Blazor scenariuszy:

BasicTestApp w źródle referencyjnym ASP.NET Core (dotnet/aspnetcore)

Uwaga

Linki dokumentacji do źródła referencyjnego platformy .NET zwykle ładują domyślną gałąź repozytorium, która odzwierciedla bieżące programowanie dla następnej wersji platformy .NET. Aby wybrać tag dla określonej wersji, użyj listy rozwijanej Przełącz gałęzie lub tagi. Aby uzyskać więcej informacji, zobacz Jak wybrać tag wersji kodu źródłowego platformy ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Aby pobrać przykładowe aplikacje:

Wielokrotny bajt

Rozmiary bajtów platformy .NET używają prefiksów metryk dla wielokrotności nieprzecinkowej bajtów na podstawie uprawnień 1024.

Nazwa (skrót) Rozmiar Przykład
Kilobajt (KB) 1024 bajty 1 KB = 1024 bajty
Megabajt (MB) 10242 bajty 1 MB = 1048 576 bajtów
Gigabajt (GB) 10243 bajty 1 GB = 1,073,741,824 bajtów

Prośby o pomoc techniczną

Tylko problemy związane z dokumentacją są odpowiednie w przypadku repozytorium dotnet/AspNetCore.Docs. W celu uzyskania pomocy technicznej dotyczącej produktów nie otwieraj problemu z dokumentacją. Poszukaj pomocy za pośrednictwem co najmniej jednego z następujących kanałów pomocy technicznej:

W przypadku potencjalnej usterki na platformie lub opinii o produkcie otwórz problem dotyczący jednostki produktu ASP.NET Core tutaj: Problemy dotyczące dotnet/aspnetcore. Raporty o usterkach zwykle wymagają następujących elementów:

  • Jasne wyjaśnienie problemu: postępuj zgodnie z instrukcjami w szablonie problemu w serwisie GitHub udostępnionym dla jednostki produktu podczas otwierania problemu.
  • Minimalny projekt repozytorium: umieść projekt w serwisie GitHub, aby inżynierowie zajmujący się daną jednostką produktu mogli go pobrać i uruchomić. Połącz projekt z komentarzem otwierającym problem.

W przypadku potencjalnego problemu z artykułem na temat platformy Blazor otwórz problem z dokumentacją. Aby otworzyć problem z dokumentacją, użyj linku Otwórz opinię dotyczącą problemu z dokumentacją w dolnej części artykułu. Metadane dodane do problemu udostępniają dane śledzenia i automatycznie wysyłają polecenie ping do autora artykułu. Jeśli temat został omówiony z jednostką produktu przed otwarciem problemu z dokumentacją, umieść link krzyżowy do problemu inżynieryjnego w komentarzu otwierającym problem z dokumentacją.

W przypadku problemów lub opinii dotyczących programu Visual Studio użyj gestów Zgłoś problem lub Zasugeruj funkcję z poziomu programu Visual Studio, które otwierają wewnętrzne problemy dla programu Visual Studio. Aby uzyskać więcej informacji, zobacz Visual Studio Feedback (Opinie dotyczące programu Visual Studio).

W przypadku problemów z programem Visual Studio Code poproś o pomoc techniczną na forach pomocy technicznej społeczności. W przypadku zgłoszeń usterek i opinii o produktach otwórz problem dotyczący repozytorium microsoft/vscode w serwisie GitHub.

Problemy w serwisie GitHub dotyczące dokumentacji platformy Blazor są automatycznie oznaczane do klasyfikacji w projekcie Blazor.Docs (repozytorium dotnet/AspNetCore.Docs w serwisie GitHub). Poczekaj nieco na odpowiedź, zwłaszcza w weekendy i święta. Zwykle autorzy dokumentacji reagują w ciągu 24 godzin w dni powszednie.

Aby uzyskać zbiór linków do zasobów platformy Blazor obsługiwanych przez społeczność, odwiedź stronę Awesome Blazor.

Uwaga

Firma Microsoft nie jest właścicielem, nie zajmuje się konserwacją ani nie obsługuje strony Awesome Blazor ani większości produktów i usług społeczności na niej opisanych lub wskazanych.