Blazor in ASP.NET Core: Grundlagen

Artikel zu Grundlagen bieten einen Leitfaden zu grundlegenden Blazor-Konzepten. Einige der Konzepte sind mit einem grundlegenden Verständnis von Razor-Komponenten verbunden, die im nächsten Abschnitt dieses Artikels näher beschrieben und in den Artikeln zu Komponenten ausführlich behandelt werden.

Statische und interaktive Renderingkonzepte

Razor Komponenten werden entweder statisch gerendert oder interaktiv gerendert.

Statisches oder statisches Rendering ist ein serverseitiges Szenario, das bedeutet, dass die Komponente ohne die Kapazität für das Zusammenspiel zwischen Benutzer- und .NET/C#-Code gerendert wird. JavaScript- und HTML-DOM-Ereignisse bleiben unberührt, aber es können keine Benutzerereignisse auf dem Client verarbeitet werden, wobei .NET auf dem Server ausgeführt wird.

Interaktives oder interaktives Rendering bedeutet, dass die Komponente die Kapazität zum Verarbeiten von .NET-Ereignissen über C#-Code hat. Die .NET-Ereignisse werden entweder von der ASP.NET Core-Laufzeit auf dem Server oder im Browser auf dem Client von der WebAssembly-basierten Blazor-Laufzeit verarbeitet.

Wichtig

Bei Verwendung einer Blazor Web Apperfordern die meisten Dokumentationsbeispielkomponenten von Blazor Interaktivität, um zu funktionieren und die Konzepte zu veranschaulichen, die in den Artikeln behandelt werden. Wenn Sie eine Beispielkomponente testen, die von einem Artikel bereitgestellt wird, stellen Sie sicher, dass die App globale Interaktivität verwendet oder die Komponente einen interaktiven Rendermodus verwendet.

Weitere Informationen zu diesen Konzepten und zum Steuern von statischem und interaktivem Rendering finden Sie im Artikel ASP.NET CoreBlazor-Rendermodi weiter unten in der Blazor-Dokumentation.

Client- und Serverrenderingkonzepte

In der gesamten Blazor Dokumentation werden Aktivitäten, die auf dem System des Benutzers stattfinden , auf client- oder clientseitiger Seite ausgeführt. Aktivitäten, die auf einem Server stattfinden, werden auf dem Server oder serverseitig ausgeführt.

Das Ausdruck Rendering bedeutet, das HTML-Markup zu erzeugen, das von Browsern angezeigt wird.

• Clientseitiges Rendering (CSR) bedeutet, dass das endgültige HTML-Markup von der .NET WebAssembly-Laufzeit auf dem Client generiert wird. Bei dieser Art des Renderings wird kein HTML für die vom Client generierte Benutzeroberfläche der Anwendung von einem Server an den Client gesendet. Die Interaktivität des Benutzers mit der Seite wird vorausgesetzt. Es gibt kein solches Konzept wie statisches clientseitiges Rendering. CSR wird als interaktiv angenommen, daher werden „interaktives clientseitiges Rendering“ und „interaktives CSR“ nicht von der Branche oder in der Blazor-Dokumentation verwendet.

• Das serverseitige Rendering (SSR) bedeutet, dass das endgültige HTML-Markup von der ASP.NET Core-Laufzeit auf dem Server generiert wird. Der HTML-Code wird über ein Netzwerk an den Client gesendet, um ihn vom Browser des Clients anzuzeigen. Bei dieser Art des Renderings wird vom Client kein HTML für die vom Server generierte Benutzeroberfläche der Anwendung erstellt. SSR kann in zwei Varianten auftreten:

  • Statisches SSR: Der Server erzeugt statisches HTML, das keine Interaktivität mit Benutzer*innen oder die Pflege des Zustands von Razor-Komponenten vorsieht.
  • Interaktives SSR: Blazor-Ereignisse ermöglichen Interaktivität mit Benutzer*innen und der Zustand der Razor-Komponente wird vom Blazor-Framework gepflegt.

• Prerendering ist der Prozess des anfänglichen Renderns von Seiteninhalten auf dem Server, ohne Ereignishandler für gerenderte Steuerelemente zu aktivieren. Der Server gibt die HTML-Benutzeroberfläche der Seite so schnell wie möglich als Reaktion auf die anfängliche Anforderung aus, wodurch die Anwendung für Benutzer besser reagiert. Prerendering kann auch die Suchmaschinenoptimierung (SEO) verbessern, indem Inhalte für die erste HTTP-Antwort gerendert werden, die Suchmaschinen zur Berechnung des Seitenrangs verwenden. Prerendering folgt immer dem endgültigen Rendering, entweder auf dem Server oder auf dem Client.

Razor-Komponenten

Blazor-Apps basieren auf Razor-Komponenten, die oft auch einfach als Komponenten bezeichnet werden. Eine Komponente ist ein Element der Benutzeroberfläche, beispielsweise eine Seite, ein Dialogfeld oder Dateneingabeformular. Komponenten sind in .NET-Assemblys integrierte .NET-C#-Klassen.

Razor verweist darauf, dass Komponenten in der Regel in Form einer Razor-Markupseite für die clientseitige Benutzeroberflächenlogik und -zusammensetzung geschrieben werden. Razor ist eine Syntax, mit der HTML-Markup mit C#-Code kombiniert werden kann, ausgerichtet auf die Produktivität der Entwickler. Razor-Dateien haben die Dateierweiterung .razor.

Obwohl von einigen Blazor-Entwicklern und Onlineressourcen der Begriff „Blazor-Komponenten“ verwendet wird, vermeidet die Dokumentation diesen Begriff, sodass durchgängig „Razor-Komponenten“ oder „Komponenten“ verwendet werden.

In der Blazor-Dokumentation werden verschiedene Konventionen für die Darstellung und Erläuterung von Komponenten verwendet:

• Im Allgemeinen halten sich die Beispiele an die Programmierkonventionen und technischen Richtlinien von ASP.NET Core/C#. Weitere Informationen finden Sie in den folgenden Ressourcen:
  • Entwicklungsrichtlinien zum ASP.NET Core Framework (dotnet/aspnetcore GitHub-Repository)
  • Programmierkonventionenfür C# (C#-Anleitung)
• Projektcode, Dateipfade und -namen, Namen von Projektvorlagen und andere Fachausdrücke sind in US-Englisch und in der Regel mit Code geschützt.
• Auf Komponenten wird in der Regel durch ihren C#-Klassennamen (Pascal-Schreibweise), gefolgt vom Wort „Komponente“, verwiesen. Zum Beispiel wird eine typische Komponente zum Hochladen von Dateien als „FileUpload-Komponente“ bezeichnet.
• In der Regel entspricht der C#-Klassenname einer Komponente deren Dateinamen.
• Bei routingfähigen Komponenten werden die relativen URLs normalerweise auf den Klassennamen der Komponente in Kebab-Schreibweise festgelegt. Beispielsweise enthält die Komponente FileUpload eine Routingkonfiguration, um die gerenderte Komponente unter der relativen URL /file-upload zu erreichen. Routing und Navigation werden unter ASP.NET Core: Routing und Navigation in Blazor behandelt.
• Bei Verwendung mehrerer Versionen einer Komponente werden diese sequenziell nummeriert. Beispielsweise befindet sich die Komponente FileUpload3 unter /file-upload-3.
• Razor Direktiven am Anfang einer Komponentendefinition (.razor file) werden in der folgenden Reihenfolge platziert: @page, @rendermode (.NET 8 oder höher), @using-Anweisungen, andere Direktiven in alphabetischer Reihenfolge.
• Obwohl für private Mitglieder nicht erforderlich, werden Zugriffsmodifizierer in Artikelbeispielen und Beispiel-Apps verwendet. Zum Beispiel wird private angegeben, um ein Feld namens maxAllowedFiles als private int maxAllowedFiles = 3; zu deklarieren.
• Die Werte von Komponentenparametern beginnen mit einem für Razor reservierten @-Symbol, das aber nicht erforderlich ist. Literale (z. B. boolesche Werte), Schlüsselwörter (z. B. this) und null als Komponentenparameterwerte wird nicht @ vorangestellt, dies ist aber lediglich eine Dokumentationskonvention. Bei Bedarf können Sie in Ihrem Code das Präfix @ für Literale verwenden.
• C#-Klassen verwenden das this-Schlüsselwort und vermeiden das Voranstellen eines Unterstrichs (_) vor Feldern, die in Konstruktoren zugewiesen werden. Dies weicht von den Entwicklungsrichtlinien zum ASP.NET Core Framework ab.
• In Beispielen, die primäre Konstruktoren (C# 12 oder höher) verwenden, werden primäre Konstruktorparameter in der Regel direkt von Klassenmitgliedern verwendet.

Weitere Informationen zur Razor-Komponentensyntax finden Sie im Abschnitt Razor Syntax von ASP.NET Core Razor-Komponenten.

Im Folgenden sehen Sie ein Beispiel einer Zählerkomponente und Teil einer App, die anhand einer Blazor-Projektvorlage erstellt wurde. Eine detaillierte Beschreibung der Komponenten finden Sie in den Artikeln zu Komponenten weiter unten in der Dokumentation. Das folgende Beispiel veranschaulicht die Konzepte von Komponenten, die in den Artikeln Grundlagen und später in den Artikeln zu Komponenten behandelt werden.

Counter.razor:

Die Komponente geht davon aus, dass ein interaktive Rendermodus von einer übergeordneten Komponente geerbt oder global auf die App angewendet wird.

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

Aufgabe der vorherigen Counter-Komponente:

• Legt ihre Route mit der Anweisung @page in der ersten Zeile fest.
• Legt Titel und Überschrift ihrer Seite fest.
• Rendert die aktuelle Anzahl mit @currentCount. currentCount ist eine Variable mit ganzer Zahl, die im C#-Code des Blocks @code definiert ist.
• Zeigt eine Schaltfläche zum Auslösen der Methode IncrementCount an, die sich auch im Block @code befindet und den Wert der Variablen currentCount erhöht.

Rendermodi

Artikel im Knoten Grundlagen beziehen sich auf das Konzept der Rendermodi. Dieses Thema wird im Artikel ASP.NET CoreBlazor-Rendermodi im Knoten Komponenten ausführlich behandelt, der nach den Grundlagen-Knoten der Artikel angezeigt wird.

Für die ersten Verweise in diesem Knotenpunkt von Artikeln auf Renderingmoduskonzepte sei an dieser Stelle nur Folgendes angemerkt:

Jede Komponente in einer Blazor Web App nimmt einen Rendermodus an, um zu bestimmen, welches Hostingmodell sie verwendet, wo sie gerendert wird und ob sie statisch auf dem Server gerendert wird, für die Interaktivität des Benutzenden auf dem Server gerendert wird oder für die Interaktivität des Benutzenden auf dem Client gerendert wird (normalerweise mit Voarabrendering auf dem Server).

Blazor Server und Blazor WebAssembly Anwendungen für ASP.NET Core-Versionen vor .NET 8 bleiben auf Hostingmodellkonzepten, nicht auf Rendermodi fixiert. Rendermodi werden konzeptionell auf Blazor Web Apps in .NET 8 oder höher angewendet.

Die folgende Tabelle zeigt die verfügbaren Rendermodi zum Rendern von Razor-Komponenten in einer Blazor Web App. Rendermodi werden auf Komponenten mit der @rendermode-Anweisung für die Komponenteninstanz oder auf die Komponentendefinition angewendet. Es ist auch möglich, einen Rendermodus für die gesamte Anwendung festzulegen.

Name	Beschreibung	Renderort	Interactive
Statischer Server	Statisches serverseitiges Rendering (Statisches SSR)	Server	❌Nein
Server (interaktiv)	Interaktives serverseitiges Rendering (interaktives SSR) mit Blazor Server	Server	✔️Ja
WebAssembly (interaktiv)	Clientseitiges Rendering (CSR) mit Blazor WebAssembly†	Client	✔️Ja
Automatisch (interaktiv)	Interaktives SSR mit Blazor Server (anfänglich) und anschließendem CSR bei weiteren Aufrufen nach Herunterladen des Blazor-Bundles	Server, dann Client	✔️Ja

†Clientseitiges Rendering (CSR) wird als interaktiv angenommen. „Interaktives clientseitiges Rendering“ und „interaktives CSR“ werden nicht von der Branche oder in der Blazor-Dokumentation verwendet.

Die vorangegangenen Informationen zu den Rendermodi sind alles, was Sie zum Verständnis der Artikel über die Grundlagen des Knotens wissen müssen. Wenn Sie neu sind und die Artikel in der Reihenfolge des Inhaltsverzeichnisses Blazor lesen Blazor, können Sie die ausführlichen Informationen zu den Rendermodi so lange hinauszögern, bis Sie den Artikel ASP.NET Core Blazor- Rendermodi im Knoten Komponenten erreichen.

Dokumentobjektmodell (DOM)

Verweise auf das Dokumentobjektmodell verwenden die Abkürzung DOM.

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Einführung in DOM (MDN-Dokumentation)
• Spezifikation des Dokumentobjektmodells der Ebene 1 (W3C)

Teilmenge der .NET-APIs für Blazor WebAssembly-Apps

Eine kuratierte Liste bestimmter .NET-APIs, die im Browser für Blazor WebAssembly unterstützt werden, ist nicht verfügbar. Sie können jedoch manuell nach einer Liste von .NET-APIs mit der Annotation [UnsupportedOSPlatform("browser")] suchen, um .NET-APIs zu finden, die in WebAssembly nicht unterstützt werden.

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

Weitere Informationen finden Sie in den folgenden Ressourcen:

• Klassenbibliotheken: Clientseitiges Browserkompatibilitäts-Analysetool
• Annotieren von APIs als nicht unterstützt auf bestimmten Plattformen (dotnet/designsGitHub-Repository

Beispiel-Apps

In der Dokumentation stehen Beispiel-Apps zum Überprüfen oder Herunterladen zur Verfügung:

Blazor GitHub-Beispielrepository (dotnet/blazor-samples)

Suchen Sie eine Beispiel-App, indem Sie zuerst den Versionsordner auswählen, der der Version von .NET entspricht, mit der Sie arbeiten.

Weitere Informationen und eine Liste der Beispiele im Repository finden Sie in den Blazor Beispielen im GitHub-Repository README.md Datei.

Die Basic Test App des ASP.NET Core-Repositorys ist ebenfalls eine hilfreiche Sammlung von Beispielen für verschiedene Blazor-Szenarien:

BasicTestApp in ASP.NET Core-Referenzquelle (dotnet/aspnetcore)

Hinweis

Dokumentationslinks zur .NET-Referenzquelle laden in der Regel den Standardbranch des Repositorys, der die aktuelle Entwicklung für das nächste Release von .NET darstellt. Um ein Tag für ein bestimmtes Release auszuwählen, wählen Sie diesen mit der Dropdownliste Switch branches or tags (Branches oder Tags wechseln) aus. Weitere Informationen finden Sie unter How to select a version tag of ASP.NET Core source code (dotnet/AspNetCore.Docs #26205) (Auswählen eines Versionstags von ASP.NET Core-Quellcode (dotnet/AspNetCore.Docs #26205)).

So laden Sie die Beispiel-Apps herunter:

• Laden Sie die Zip-Datei des Blazor-Beispielrepositorys herunter.
• Entzippen Sie die Datei.

Byte-Vielfache

.NET-Bytegrößen verwenden metrische Präfixe für nicht dezimale Byte-Vielfache, die auf Potenzen von 1024 basieren.

Name (Abkürzung)	Größe	Beispiel
Kilobyte (KB)	1.024 Bytes	1 KB = 1.024 Bytes
Megabyte (MB)	1.0242 Bytes	1 MB = 1.048.576 Bytes
Gigabyte (GB)	1.0243 Bytes	1 GB = 1.073.741.824 Bytes

Supportanfragen

Nur dokumentationsbezogene Probleme sind für das Repository dotnet/AspNetCore.Docs geeignet. Öffnen Sie für Produktsupport kein Problem in der Dokumentation. Suchen Sie Hilfe über einen oder mehrere der folgenden Supportkanäle:

• Stack Overflow (Tag: blazor)
• Allgemeines Slack-Team für ASP.NET Core
• Blazor Gitter

Bei einem potenziellen Fehler im Framework oder für Produktfeedback können Sie ein Ticket für die ASP.NET Core-Produktgruppe unter dotnet/aspnetcore-Issues öffnen. Fehlerberichte erfordern in der Regel Folgendes:

• Klare Erläuterung des Problems: Folgen Sie den Anweisungen in der GitHub-Vorlage, die von der Produkteinheit zur Verfügung gestellt wird, wenn Sie das Ticket öffnen.
• Minimales Reproduktionsprojekt: Legen Sie ein Projekt auf GitHub ab, das die Entwickler der Produkteinheit herunterladen und ausführen können. Verknüpfen Sie das Projekt mit dem Eröffnungskommentar des Issues.

Bei einem potenziellen Problem mit einem Blazor-Artikel, öffnen Sie ein Problem in der Dokumentation. Um ein Dokumentationsproblem zu melden, verwenden Sie den Link Dokumentationsproblem öffnen unten im Artikel. Die Metadaten, die Sie zu Ihrem Problem hinzufügen, liefern Daten zur Nachverfolgung und benachrichtigen automatisch den Autor bzw. die Autorin des Artikels. Wenn das Thema vor der Eröffnung des Dokumentationsproblems mit der Produkteinheit besprochen wurde, fügen Sie im Eröffnungskommentar des Dokumentationsproblems einen Querverweis auf das technische Problem ein.

Wenn Sie Probleme oder Feedback zu Visual Studio haben, verwenden Sie die Gesten Problem melden oder Feature vorschlagen in Visual Studio, über die Sie interne Probleme für Visual Studio öffnen können. Weitere Informationen finden Sie unter Visual Studio-Feedback.

Wenn Sie Probleme mit Visual Studio Code haben, bitten Sie in den Supportforen der Community um Unterstützung. Für Fehlerberichte und Produktfeedback öffnen Sie ein Issue imGitHub-Repository microsoft/vscode.

GitHub-Issues für die Blazor-Dokumentation werden automatisch für die Selektierung im Blazor.Docs-Projekt (dotnet/AspNetCore.Docs GitHub-Repository) markiert. Sie müssen mit einer kurzen Wartezeit rechnen, insbesondere an Wochenenden und Feiertagen. Normalerweise antworten Dokumentationsautoren an Wochentagen binnen 24 Stunden.

Communitylinks zu Blazor-Ressourcen

Eine Sammlung von Links zu Blazor-Ressourcen, die von der Community verwaltet werden, finden Sie unter Awesome Blazor.

Hinweis

Microsoft besitzt, pflegt oder unterstützt Awesome Blazor und die meisten der dort beschriebenen und mit diesem Link verbundenen Communityprodukte und -dienste nicht.