Platforma Blazor ASP.NET Core — podstawy

Artykuły podstawowe zawierają wskazówki na temat podstawowych Blazor pojęć. 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 klienta i serwera

W całej Blazor dokumentacji działanie wykonywane w systemie użytkownika określane jest jako na kliencie lub po stronie klienta. Działanie, które odbywa się na serwerze, nazywa się, że występuje na serwerze lub po stronie serwera.

Termin rendering oznacza tworzenie znaczników HTML, które przeglądarki wyświetlają.

• Renderowanie po stronie klienta (CSR) oznacza, że końcowy znacznik HTML jest generowany przez środowisko uruchomieniowe zestawu WebAssembly platformy .NET na kliencie. Kod HTML dla interfejsu użytkownika generowanego po stronie klienta aplikacji nie jest wysyłany z serwera do klienta w przypadku tego typu renderowania. Zakłada się, że użytkownik będzie wchodził w interakcję ze stroną. Nie ma takiej koncepcji, jak statyczne renderowanie po stronie klienta. Zakłada się, że CSR jest interaktywne, dlatego "interaktywne renderowanie po stronie klienta" i "interaktywne 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 SSR: serwer tworzy statyczny kod HTML, który nie pozwala na interaktywność użytkownika ani utrzymywania stanu komponentu Razor.
  • Interaktywne SSR: Blazor zdarzenia umożliwiają interakcję użytkownika, a Razor stan komponentu jest utrzymywany przez Blazor framework.

• 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 wydaje się bardziej responsywna dla użytkowników. Prerendering może również poprawić optymalizację dla wyszukiwarek internetowych (SEO) przez renderowanie zawartości w początkowej odpowiedzi HTTP używanej przez wyszukiwarki do obliczania pozycjonowania strony. Prerendering jest zawsze poprzedzone ostatecznym renderowaniem, czy to na serwerze, czy po stronie klienta.

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. Razor to składnia łączenia znaczników HTML z kodem C# zaprojektowana dla zwiększenia 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:
  • Zasady inżynieryjne frameworka ASP.NET Core (repozytorium GitHub)
  • Konwencje kodowania C# (przewodnik po języku C#)
• 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 określane przez nazwę swojej klasy w języku C# (z wielkimi literami jak w języku Pascal), a następnie słowem „składnik”. Na przykład typowy składnik do przesyłania plików jest nazywany „składnikiem FileUpload”.
• Zazwyczaj nazwa klasy C# składnika jest taka sama jak jego nazwa pliku.
• Składniki podlegające trasowaniu zwykle ustawiają swoje względne adresy URL zgodnie z nazwą klasy składnika w kebab-case. 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.
• Chociaż nie są wymagane dla członków private, modyfikatory dostępu są stosowane w przykładach artykułów i aplikacjach demonstracyjnych. 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 zaczynają się od zastrzeżonego Razor@ symbolu, 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 znakiem podkreślenia (_), które są przypisywane w konstruktorach, co różni się od wytycznych inżynieryjnych dotyczących frameworka 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. W przykładach artykułów wiersze kodu są podzielone w celu zmniejszenia scrollowania w poziomie. Powyższe przerwy nie wpływają na działanie, ale można je usunąć podczas wklejania do projektu.

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

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:

@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"

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

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:

• Wprowadzenie do DOM (dokumentacja MDN)
• Specyfikacja modelu obiektów dokumentu poziomu 1 (W3C)

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 oznaczonymi jako [UnsupportedOSPlatform("browser")], w celu odkrycia, które interfejsy API platformy .NET nie są obsługiwane w WebAssembly.

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

• Biblioteki klas: Analizator zgodności przeglądarki po stronie klienta
• Adnotacja interfejsów API jako nieobsługiwanych na określonych platformach (dotnet/designs w repozytorium GitHub

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.

Aby uzyskać więcej informacji, listę przykładów oraz instrukcje pobierania, zapoznaj się z plikiem README repozytorium GitHub zawierającym przykłady Blazor.

Podstawowa aplikacja testowa z repozytorium ASP.NET Core to również przydatny zestaw przykładów dla różnych scenariuszy Blazor.

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

Wielokrotny bajt

Rozmiary bajtów w platformie .NET używają przedrostków metrycznych dla wielokrotności nie dziesiętnej bajtów na podstawie potęg liczby 1024.

Prośby o pomoc techniczną

Tylko problemy związane z dokumentacją są odpowiednie dla 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:

• Stack Overflow (tag: blazor)
• Ogólny zespół ASP.NET Core Slack
• Blazor Gitter

W przypadku potencjalnej usterki w frameworku lub opinii o produkcie, zgłoś problem dotyczący jednostki produktu ASP.NET Core w sekcji dotnet/aspnetcore Problemy. 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 reprodukcji: Umieść projekt na GitHubie, aby inżynierowie jednostki produktowej mogli go pobrać i uruchomić. Utwórz wzajemne połączenie między projektem a otwierającym komentarzem zagadnienia.

W przypadku potencjalnego problemu z artykułem Blazor, otwórz zgłoszenie dokumentacyjne. 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 zgłoszenia udostępniają dane śledzenia i automatycznie powiadamiają 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 zgłoszenie w repozytorium microsoft/vscode na GitHubie.

Problemy w serwisie GitHub dotyczące dokumentacji 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.

Linki społeczności do zasobów platformy Blazor

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