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.

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. In Artikelbeispielen werden Codezeilen aufgeteilt, um das horizontale Scrollen zu reduzieren. Diese Unterbrechungen wirken sich nicht auf die Ausführung aus, können aber beim Einfügen in Ihr Projekt entfernt werden.

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:

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

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.

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.

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, eine Liste der Beispiele im Repository und Downloadanweisungen finden Sie in der Blazor GitHub-Repository-README-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)

Byte-Vielfache

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

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.