Blazor in ASP.NET Core: Grundlagen

  • Artikel

Hinweis

Dies ist nicht die neueste Version dieses Artikels. Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

Wichtig

Diese Informationen beziehen sich auf ein Vorabversionsprodukt, das vor der kommerziellen Freigabe möglicherweise noch wesentlichen Änderungen unterliegt. Microsoft gibt keine Garantie, weder ausdrücklich noch impliziert, hinsichtlich der hier bereitgestellten Informationen.

Informationen zum aktuellen Release finden Sie in der .NET 8-Version dieses Artikels.

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

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.

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.

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:

  • 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. Weitere Informationen zur Razor-Direktivenordnung finden Sie im Abschnitt Razor SyntaxASP.NET Core-Razor-Komponenten.
  • Zugriffsmodifizierer werden in Artikelbeispielen verwendet. So sind beispielsweise Felder standardmäßig private, im Code der Komponente jedoch explizit vorhanden. 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.
  • 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:

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

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

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 Webanwendung 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 Benutzers auf dem Server gerendert wird oder für die Interaktivität des Benutzers auf dem Client gerendert wird (normalerweise mit Prerendering 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 Webanwendungen 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
Server (interaktiv) Interaktives serverseitiges Rendering (interaktives SSR) mit Blazor Server Server
WebAssembly (interaktiv) Clientseitiges Rendering (CSR) mit Blazor WebAssembly† Client
Automatisch (interaktiv) Interaktives SSR mit Blazor Server (anfänglich) und anschließendem CSR bei weiteren Aufrufen nach Herunterladen des Blazor-Bundles Server, dann Client

†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:

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:

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.

Beispiel-Apps im Repository:

Das Repository enthält zwei Arten von Beispielen:

  • Schnipselbeispiel-Apps bieten die Codebeispiele, die in Artikeln verwendet werden. Diese Apps kompilieren, sind aber nicht notwendigerweise ausführbare Apps. Diese Apps sind nützlich, um lediglich Beispielcode zu erhalten, der in Artikeln verwendet wird.
  • Beispiel-Apps zur Begleitung von Blazor-Artikeln werden für die folgenden Szenarien kompiliert und ausgeführt:
    • Blazor Server mit EF Core
    • Blazor Server und Blazor WebAssembly mit SignalR
    • Protokollierung mit Unterstützung von Blazor WebAssembly-Bereichen

Weitere Informationen finden Sie in der README.md-Datei des Blazor GitHub-Beispielrepositorys.

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:

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:

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 Problem in der Dokumentation zu öffnen, verwenden Sie die Feedbackschaltfläche Diese Seite und das Formular am Ende des Artikels. Belassen Sie die Metadaten an Ort und Stelle, wenn Sie den Eröffnungskommentar erstellen. Die Metadaten enthalten Daten zur Nachverfolgung und pingen automatisch den Autor des Artikels an. Wenn die Angelegenheit mit der Produkteinheit besprochen wurde, platzieren Sie im Eröffnungskommentar der Dokumentationsausgabe einen Querverweis auf das Problem in der Dokumentation.

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.

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.