Fehlerbehandlung in ASP.NET Core Blazor-Apps

In einer Blazor Web App, passen Sie die Erfahrung in der MainLayout-Komponente an. Da das Taghilfsprogramm für Umgebungen (z. B. <environment include="Production">...</environment>) in Razor-Komponenten nicht unterstützt wird, injiziert das folgende Beispiel IHostEnvironment, um Fehlermeldungen für verschiedene Umgebungen zu konfigurieren.

Am Anfang von MainLayout.razor:

@inject IHostEnvironment HostEnvironment

Erstellen oder ändern Sie das UI-Markup für Blazor-Fehler:

<div id="blazor-error-ui" data-nosnippet>
    @if (HostEnvironment.IsProduction())
    {
        <span>An error has occurred.</span>
    }
    else
    {
        <span>An unhandled exception occurred.</span>
    }
    <a href="" class="reload">Reload</a>
    <a class="dismiss">🗙</a>
</div>

Passen Sie in einer Blazor Server-App die Funktionalität in der Pages/_Host.cshtml-Datei an. Das folgende Beispiel verwendet das Taghilfsprogramm für Umgebungen, um Fehlermeldungen für verschiedene Umgebungen zu konfigurieren.

Passen Sie in einer Blazor Server-App die Funktionalität in der Pages/_Layout.cshtml-Datei an. Das folgende Beispiel verwendet das Taghilfsprogramm für Umgebungen, um Fehlermeldungen für verschiedene Umgebungen zu konfigurieren.

Passen Sie in einer Blazor Server-App die Funktionalität in der Pages/_Host.cshtml-Datei an. Das folgende Beispiel verwendet das Taghilfsprogramm für Umgebungen, um Fehlermeldungen für verschiedene Umgebungen zu konfigurieren.

Erstellen oder ändern Sie das UI-Markup für Blazor-Fehler:

<div id="blazor-error-ui" data-nosnippet>
    <environment include="Staging,Production">
        An error has occurred.
    </environment>
    <environment include="Development">
        An unhandled exception occurred.
    </environment>
    <a href="" class="reload">Reload</a>
    <a class="dismiss">🗙</a>
</div>

Das blazor-error-ui-Element wird normalerweise ausgeblendet, weil der display: none-Stil der blazor-error-ui-CSS-Klasse im automatisch generierten Stylesheet der App vorhanden ist. Wenn ein Fehler auftritt, wird display: block vom Framework auf das Element angewendet.

Das blazor-error-ui-Element ist normalerweise ausgeblendet, weil der display: none-Stil der blazor-error-ui-CSS-Klasse im Stylesheet der Website (im Ordner wwwroot/css) vorhanden ist. Wenn ein Fehler auftritt, wird display: block vom Framework auf das Element angewendet.

Dieser Abschnitt gilt für Blazor Web Apps, die über einen Stromkreis arbeiten.

Dieser Abschnitt gilt für Blazor Server-Apps.

Detaillierte Fehler für Razor serverseitiges Rendern von Komponenten

Dieser Abschnitt gilt für Blazor Web Apps.

Verwenden Sie die RazorComponentsServiceOptions.DetailedErrors Option, um die Erstellung detaillierter Informationen zu Fehlern für das serverseitige Rendern von Razor Komponenten zu steuern. Der Standardwert ist false.

Im folgenden Beispiel werden detaillierte Fehler aktiviert:

builder.Services.AddRazorComponents(options => 
    options.DetailedErrors = builder.Environment.IsDevelopment());

Ansätze zur globalen Behandlung von Ausnahmen finden Sie in den folgenden Abschnitten:

• Fehlerbegrenzungen: Gilt für alle Blazor-Apps.
• Alternative globale Ausnahmebehandlung: Gilt für Blazor Server, Blazor WebAssembly und Blazor Web App (8.0 oder später), die einen globalen interaktiven Rendermodus verwenden.

Fehlergrenzen

Fehlergrenzen bieten eine gut geeignete Möglichkeit für die Behandlung von Ausnahmen. Die Komponente ErrorBoundary:

• Rendert den untergeordneten Inhalt, wenn kein Fehler aufgetreten ist.
• Rendert die Fehler-UI, wenn eine unbehandelte Ausnahme von einer beliebigen Komponente innerhalb der Fehlergrenze ausgelöst wird.

Zum Definieren einer Fehlergrenze verwenden Sie die ErrorBoundary-Komponente, um andere Komponenten zu umschließen. Die Fehlergrenze verwaltet unbehandelte Ausnahmen, die von den umschlossenen Komponenten ausgelöst werden.

<ErrorBoundary>
    ...
</ErrorBoundary>

Um eine Fehlergrenze global zu implementieren, fügen Sie die Grenze um den Textinhalt des Hauptlayouts der App hinzu.

In MainLayout.razor:

<article class="content px-4">
    <ErrorBoundary>
        @Body
    </ErrorBoundary>
</article>

Bei Blazor Web Apps, bei denen die Fehlerbegrenzung nur auf eine statische MainLayout-Komponente angewendet wird, ist die Begrenzung nur während des statischen serverseitigen Renderings (static SSR) aktiv. Die Grenze wird nicht aktiviert, nur weil eine Komponente weiter unten in der Komponentenhierarchie interaktiv ist.

Auf die MainLayout-Komponente kann kein interaktiver Rendermodus angewandt werden, da der Parameter Body der Komponente ein RenderFragment-Delegat ist, der als beliebiger Code nicht serialisiert werden kann. Um Interaktivität für die MainLayout-Komponente und die rest-Komponenten weiter unten in der Komponentenhierarchie zu ermöglichen, muss die Anwendung einen globalen interaktiven Rendering-Modus annehmen, indem der interaktive Rendering-Modus auf die HeadOutlet- und Routes-Komponenteninstanzen in der Stammkomponente der Anwendung angewendet wird, die normalerweise die App-Komponente ist. Im folgenden Beispiel wird der Rendermodus für interaktive Server (InteractiveServer) global verwendet.

In Components/App.razor:

<HeadOutlet @rendermode="InteractiveServer" />

...

<Routes @rendermode="InteractiveServer" />

Wenn Sie lieber keine globale Interaktivität aktivieren möchten, platzieren Sie die Fehlergrenze weiter unten in der Komponentenhierarchie. Unabhängig von der Position der Fehlergrenze sollten Sie folgende wichtige Konzepte berücksichtigen:

• Wenn die Komponente, an der die Fehlergrenze platziert wurde, nicht interaktiv ist, kann die Fehlergrenze nur während statischem SSR auf dem Server aktiviert werden. Beispielsweise kann die Grenze aktiviert werden, wenn ein Fehler in einer Komponenten-Lebenszyklusmethode ausgelöst wird, aber nicht für ein Ereignis, das durch Benutzerinteraktivität innerhalb der Komponente ausgelöst wird, z. B. ein Fehler, der von einem Schaltflächenklickhandler ausgelöst wird.
• Wenn die Komponente, an der die Fehlergrenze platziert wurde, interaktiv ist, kann die Fehlergrenze für interaktive Komponenten aktiviert werden, die sie umschließt.

Betrachten Sie das folgende Beispiel, bei dem eine Ausnahme, die von einer eingebetteten Leistungsindikatorkomponente ausgelöst wird, von einer Fehlergrenze in der Home-Komponente abgefangen wird, die einen interaktiven Rendermodus verwendet.

EmbeddedCounter.razor:

<h1>Embedded 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++;

        if (currentCount > 5)
        {
            throw new InvalidOperationException("Current count is too big!");
        }
    }
}

Home.razor:

@page "/"
@rendermode InteractiveServer

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<ErrorBoundary>
    <EmbeddedCounter />
</ErrorBoundary>

Betrachten Sie das folgende Beispiel, bei dem eine Ausnahme, die von einer eingebetteten Leistungsindikatorkomponente ausgelöst wird, von einer Fehlergrenze in der Home-Komponente abgefangen wird.

EmbeddedCounter.razor:

<h1>Embedded 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++;

        if (currentCount > 5)
        {
            throw new InvalidOperationException("Current count is too big!");
        }
    }
}

Home.razor:

@page "/"

<PageTitle>Home</PageTitle>

<h1>Home</h1>

<ErrorBoundary>
    <EmbeddedCounter />
</ErrorBoundary>

Wenn die nicht behandelte Ausnahme für currentCount größer fünf ausgelöst wird, gilt:

• Der Fehler wird normal protokolliert (System.InvalidOperationException: Current count is too big!).
• Die ausgelöste Ausnahme wird von der Fehlergrenze verarbeitet.
• Die Standard-Fehlerbenutzeroberfläche wird durch die Fehlergrenze gerendert.

Standardmäßig rendert die ErrorBoundary-Komponente für den Fehlerinhalt ein leeres <div>-Element mit der CSS-Klasse blazor-error-boundary. Farben, Text und Symbol für die Standardbenutzeroberfläche werden über das Stylesheet der App im Ordner wwwroot definiert, sodass Sie die Fehlerbenutzeroberfläche beliebig anpassen können.

So ändern Sie den Standardfehlerinhalt

• Umschließen Sie die Komponenten der Fehlergrenze in der ChildContent-Eigenschaft.
• Legen Sie die ErrorContent-Eigenschaft auf den Fehlerinhalt fest.

Im folgenden Beispiel wird die EmbeddedCounter-Komponente umschlossen, und es werden benutzerdefinierte Fehlerinhalte bereitgestellt:

<ErrorBoundary>
    <ChildContent>
        <EmbeddedCounter />
    </ChildContent>
    <ErrorContent>
        <p class="errorUI">😈 A rotten gremlin got us. Sorry!</p>
    </ErrorContent>
</ErrorBoundary>

Im vorherigen Beispiel wird davon ausgegangen, dass das Stylesheet der App eine CSS-Klasse errorUI zum Formatieren des Inhalts enthält. Der Fehlerinhalt wird aus der ErrorContent-Eigenschaft ohne ein Element auf Blockebene gerendert. Ein Element auf Blockebene, z. B. eine Unterteilung (<div>) oder ein Absatzelement (<p>), kann das Fehlerinhaltsmarkup umschließen, ist jedoch nicht erforderlich.

Optional kann der Kontext (@context) des ErrorContent verwendet werden, um Fehlerdaten zu erhalten:

<ErrorContent>
    @context.HelpLink
</ErrorContent>

Der ErrorContent kann auch den Kontext benennen. Im folgenden Beispiel heißt der Kontext exception:

<ErrorContent Context="exception">
    @exception.HelpLink
</ErrorContent>

Wenn die Fehlergrenze im Layout der App definiert ist, wird die Fehlerbenutzeroberfläche unabhängig davon angezeigt, zu welcher Seite die Benutzer nach Auftreten des Fehlers navigieren. In den meisten Szenarien wird empfohlen, einen engen Bereich für die Fehlergrenze festzulegen. Wenn Sie den Bereich für die Fehlergrenze weit festlegen, können Sie sie bei nachfolgenden Seitennavigationsereignissen auf einen fehlerfreien Zustand zurücksetzen, indem Sie die Recover-Methode der Fehlergrenze aufrufen.

In MainLayout.razor:

• Fügen Sie ein Feld für die ErrorBoundary hinzu, um mithilfe der @ref-Attributanweisung einen Verweis darauf zu erfassen.
• In der OnParameterSet Lebenszyklusmethode können Sie mit Recover eine Wiederherstellung an der Fehlergrenze auslösen, um den Fehler zu löschen, wenn jemand zu einer anderen Komponente navigiert.

...

<ErrorBoundary @ref="errorBoundary">
    @Body
</ErrorBoundary>

...

@code {
    private ErrorBoundary? errorBoundary;

    protected override void OnParametersSet()
    {
        errorBoundary?.Recover();
    }
}

Zur Vermeidung einer Endlosschleife, bei der die Wiederherstellung eine Komponente lediglich neu rendert und diese den Fehler erneut auslöst, sollten Sie Recover nicht aus der Renderinglogik aufrufen. Rufen Sie Recover nur in diesen Fällen auf:

• Die Benutzer*innen zeigen durch Ausführung einer Benutzeroberflächengeste (z. B. Auswahl einer Schaltfläche) an, dass sie einen Vorgang wiederholen möchten, oder die Benutzer*innen navigieren zu einer neuen Komponente.
• Die Ausnahme wird auch durch zusätzlich ausgeführte Logik beseitigt. Wenn die Komponente neu gerendert wird, tritt der Fehler nicht mehr auf.

Im folgenden Beispiel lässt sich die Ausnahme mit einer Schaltfläche beheben:

<ErrorBoundary @ref="errorBoundary">
    <ChildContent>
        <EmbeddedCounter />
    </ChildContent>
    <ErrorContent>
        <div class="alert alert-danger" role="alert">
            <p class="fs-3 fw-bold">😈 A rotten gremlin got us. Sorry!</p>
            <p>@context.HelpLink</p>
            <button class="btn btn-info" @onclick="_ => errorBoundary?.Recover()">
                Clear
            </button>
        </div>
    </ErrorContent>
</ErrorBoundary>

@code {
    private ErrorBoundary? errorBoundary;
}

Sie können auch die Unterklasse ErrorBoundary für die benutzerdefinierte Verarbeitung durch Überschreiben von OnErrorAsync verwenden. Im folgenden Beispiel wird lediglich der Fehler protokolliert, Sie können jedoch jeden gewünschten Fehlerbehandlungscode implementieren. Sie können die Zeile entfernen, die CompletedTask zurückgibt, wenn ihr Code auf eine asynchrone Aufgabe wartet.

CustomErrorBoundary.razor:

@inherits ErrorBoundary
@inject ILogger<CustomErrorBoundary> Logger

@if (CurrentException is null)
{
    @ChildContent
}
else if (ErrorContent is not null)
{
    @ErrorContent(CurrentException)
}

@code {
    protected override Task OnErrorAsync(Exception ex)
    {
        Logger.LogError(ex, "😈 A rotten gremlin got us. Sorry!");
        return Task.CompletedTask;
    }
}

Das vorangehende Beispiel kann auch als Klasse implementiert werden.

CustomErrorBoundary.cs:

using Microsoft.AspNetCore.Components;
using Microsoft.AspNetCore.Components.Web;

namespace BlazorSample;

public class CustomErrorBoundary : ErrorBoundary
{
    [Inject]
    ILogger<CustomErrorBoundary> Logger {  get; set; } = default!;

    protected override Task OnErrorAsync(Exception ex)
    {
        Logger.LogError(ex, "😈 A rotten gremlin got us. Sorry!");
        return Task.CompletedTask;
    }
}

Eine der vorherigen Implementierungen, die in einer Komponente verwendet werden:

<CustomErrorBoundary>
    ...
</CustomErrorBoundary>

Alternative globale Ausnahmebehandlung

Der in diesem Abschnitt beschriebene Ansatz gilt für Blazor Server, Blazor WebAssembly und Blazor Web App, die einen globalen interaktiven Rendermodus verwenden (InteractiveServer, InteractiveWebAssembly oder InteractiveAuto). Der Ansatz funktioniert nicht mit Blazor Web Apps, die Rendering-Modi pro Seite/Komponente oder statisches Server-seitiges Rendering (static SSR) verwenden, da der Ansatz auf CascadingValue/CascadingParameter beruht, die nicht über Rendering-Modus-Grenzen hinweg oder mit Komponenten funktionieren, die statisches SSR verwenden.

Eine Alternative zur Verwendung von Fehlergrenzen (ErrorBoundary) besteht darin, eine benutzerdefinierte Fehlerkomponente als CascadingValue an untergeordnete Komponenten zu übergeben. Ein Vorteil der Verwendung einer Komponente gegenüber der Verwendung eines eingefügten Diensts oder der Implementierung einer benutzerdefinierten Protokollierung besteht darin, dass eine kaskadierenden Komponente Inhalte rendern und CSS-Stile anwenden kann, wenn ein Fehler auftritt.

Im folgenden Beispiel einer ProcessError-Komponente werden Fehler lediglich protokolliert, Methoden der Komponente können Fehler jedoch in beliebiger Weise je nach Anforderungen der App verarbeiten, auch mithilfe mehrerer Fehlerverarbeitungsmethoden.

ProcessError.razor:

@inject ILogger<ProcessError> Logger

<CascadingValue Value="this">
    @ChildContent
</CascadingValue>

@code {
    [Parameter]
    public RenderFragment? ChildContent { get; set; }

    public void LogError(Exception ex)
    {
        Logger.LogError("ProcessError.LogError: {Type} Message: {Message}", 
            ex.GetType(), ex.Message);

        // Call StateHasChanged if LogError directly participates in 
        // rendering. If LogError only logs or records the error,
        // there's no need to call StateHasChanged.
        //StateHasChanged();
    }
}

Wenn Sie diesen Ansatz in einem Blazor Web App verwenden, öffnen Sie die Komponente Routes und verpacken Sie die Komponente Router (<Router>...</Router>) mit der Komponente ProcessError. Dies erlaubt der ProcessError-Komponente eine Kaskadierung an beliebige Komponenten der App, wobei die ProcessError-Komponente als CascadingParameter empfangen wird.

In Routes.razor:

<ProcessError>
    <Router ...>
        ...
    </Router>
</ProcessError>

Wenn Sie diesen Ansatz in einer Blazor Server- oder Blazor WebAssembly-App verwenden, öffnen Sie die App-Komponente, und umschließen Sie die Router-Komponente (<Router>...</Router>) mit der ProcessError-Komponente. Dies erlaubt der ProcessError-Komponente eine Kaskadierung an beliebige Komponenten der App, wobei die ProcessError-Komponente als CascadingParameter empfangen wird.

In App.razor:

<ProcessError>
    <Router ...>
        ...
    </Router>
</ProcessError>

So verarbeiten Sie Fehler in einer-Komponente:

• Legen Sie die ProcessError-Komponente im @code-Block als CascadingParameter fest: Fügen Sie in einer Counter-Beispielkomponente in einer App, die auf einer Blazor-Projektvorlage basiert, die folgende ProcessError-Eigenschaft hinzu:

  [CascadingParameter]
  public ProcessError? ProcessError { get; set; }
  

• Rufen Sie eine Fehlerverarbeitungsmethode mit einem entsprechenden Ausnahmetyp in einem beliebigen catch-Block auf. Die ProcessError-Komponente aus dem Beispiel verfügt nur über eine einzige LogError-Methode, die Fehlerverarbeitungskomponente kann jedoch eine beliebige Anzahl von Fehlerverarbeitungsmethoden bereitstellen, um Anforderungen an eine alternative Fehlerverarbeitung für die gesamte App zu ermöglichen. Das folgende @code-Blockbeispiel mit Counter-Komponente enthält den Cascading-Parameter „ProcessError“ und fängt eine Ausnahme für die Protokollierung ein, wenn die Anzahl größer als fünf ist:

  @code {
      private int currentCount = 0;
  
      [CascadingParameter]
      public ProcessError? ProcessError { get; set; }
  
      private void IncrementCount()
      {
          try
          {
              currentCount++;
  
              if (currentCount > 5)
              {
                  throw new InvalidOperationException("Current count is over five!");
              }
          }
          catch (Exception ex)
          {
              ProcessError?.LogError(ex);
          }
      }
  }
  

Der protokollierte Fehler:

fail: {COMPONENT NAMESPACE}.ProcessError[0]
ProcessError.LogError: System.InvalidOperationException Message: Current count is over five!

Wenn die LogError-Methode direkt an einem Rendering beteiligt ist, z. B. wenn eine benutzerdefinierte Fehlermeldungsleiste angezeigt wird oder die CSS-Stile der gerenderten Elemente geändert werden, wird StateHasChanged am Ende der LogError-Methode aufgerufen, um die Benutzeroberfläche neu zu rendern.

Da bei den Ansätzen in diesem Abschnitt Fehler mit einer try-catch-Anweisung behandelt werden, wird die SignalR-Verbindung einer App zwischen Client und Server nicht getrennt, wenn ein Fehler auftritt, und die Leitung wird aufrechterhalten. Andere nicht behandelte Ausnahmefehler bleiben für eine Leitung schwerwiegend. Weitere Informationen finden Sie im vorherigen Abschnitt, in dem erläutert wird, wie eine Leitung auf Ausnahmefehler reagiert.

Eine App kann eine Fehlerverarbeitungskomponente als kaskadierenden Wert verwenden, um Fehler zentral zu verarbeiten.

Die folgende ProcessError-Komponente übergibt sich selbst als CascadingValue an untergeordnete Komponenten. Im folgenden Beispiel wird der Fehler lediglich protokolliert, Methoden der Komponente können Fehler jedoch in beliebiger Weise je nach Anforderungen der App verarbeiten, auch mithilfe mehrerer Fehlerverarbeitungsmethoden. Ein Vorteil der Verwendung einer Komponente gegenüber der Verwendung eines eingefügten Diensts oder der Implementierung einer benutzerdefinierten Protokollierung besteht darin, dass eine kaskadierenden Komponente Inhalte rendern und CSS-Stile anwenden kann, wenn ein Fehler auftritt.

ProcessError.razor:

@using Microsoft.Extensions.Logging
@inject ILogger<ProcessError> Logger

<CascadingValue Value="this">
    @ChildContent
</CascadingValue>

@code {
    [Parameter]
    public RenderFragment ChildContent { get; set; }

    public void LogError(Exception ex)
    {
        Logger.LogError("ProcessError.LogError: {Type} Message: {Message}", 
            ex.GetType(), ex.Message);
    }
}

Erstellen Sie in der App-Komponente mit der ProcessError-Komponente einen Wrapper für die Router-Komponente. Dies erlaubt der ProcessError-Komponente eine Kaskadierung an beliebige Komponenten der App, wobei die ProcessError-Komponente als CascadingParameter empfangen wird.

App.razor:

<ProcessError>
    <Router ...>
        ...
    </Router>
</ProcessError>

So verarbeiten Sie Fehler in einer-Komponente:

• Legen Sie die ProcessError-Komponente im @code-Block als CascadingParameter fest:

  [CascadingParameter]
  public ProcessError ProcessError { get; set; }
  

• Rufen Sie eine Fehlerverarbeitungsmethode mit einem entsprechenden Ausnahmetyp in einem beliebigen catch-Block auf. Die ProcessError-Komponente aus dem Beispiel verfügt nur über eine einzige LogError-Methode, die Fehlerverarbeitungskomponente kann jedoch eine beliebige Anzahl von Fehlerverarbeitungsmethoden bereitstellen, um Anforderungen an eine alternative Fehlerverarbeitung für die gesamte App zu ermöglichen.

  try
  {
      ...
  }
  catch (Exception ex)
  {
      ProcessError.LogError(ex);
  }
  

Bei Verwendung der ProcessError-Komponente und der LogError-Methode aus dem vorherigen Beispiel wird in Konsole mit den Entwicklertools des Browsers der aufgefangene protokollierte Fehler angegeben:

fail: {COMPONENT NAMESPACE}.Shared.ProcessError[0]
ProcessError.LogError: System.NullReferenceException Message: Object reference not set to an instance of an object.

Wenn die LogError-Methode direkt an einem Rendering beteiligt ist, z. B. wenn eine benutzerdefinierte Fehlermeldungsleiste angezeigt oder die CSS-Stile der gerenderten Elemente geändert werden, wird StateHasChanged am Ende der LogError-Methode aufgerufen, um die Benutzeroberfläche zu rendern.

Da bei den Ansätzen in diesem Abschnitt Fehler mit einer try-catch-Anweisung behandelt werden, wird die SignalR-Verbindung einer Blazor-App zwischen Client und Server nicht getrennt, wenn ein Fehler auftritt, und die Leitung wird aufrechterhalten. Unbehandelte Ausnahmen führen zu einem schwerwiegenden Leitungsfehler. Weitere Informationen finden Sie im vorherigen Abschnitt, in dem erläutert wird, wie eine Leitung auf Ausnahmefehler reagiert.

Im Fall eines Ausnahmefehlers wird die Ausnahme in den im Dienstcontainer konfiguriertenILogger-Instanzen protokolliert. Blazor-Apps protokollieren standardmäßig in die Konsolenausgabe beim Konsolenprotokollierungsanbieter. Überlegen Sie, ob Sie die Protokollierung an einem Speicherort auf dem Server (oder einer Back-End-Web-API für clientseitige Apps) mit einem Anbieter durchführen, der die Protokollgröße und die Protokollrotation verwaltet. Alternativ kann die App einen APM-Dienst (Application Performance Management) verwenden, z. B. Azure Application Insights (Azure Monitor).

Während der Entwicklung in einer Blazor-App, die über eine Leitung betrieben wird, sendet die App zur Unterstützung des Debuggings in der Regel alle Ausnahmedetails an die Konsole des Browsers. In der Produktionsumgebung werden keine ausführlichen Fehler an Clients gesendet, die vollständigen Details der Ausnahme werden jedoch auf dem Server protokolliert.

Sie müssen entscheiden, welche Vorfälle protokolliert werden sollen. Zudem müssen Sie den Schweregrad für protokollierte Vorfälle festlegen. Feindliche Benutzer können Fehler möglicherweise absichtlich auslöst. Protokollieren Sie beispielsweise keinen Vorfall aus einem Fehler, bei dem eine unbekannte ProductId in der URL einer Komponente angegeben wurde, über die Produktdetails angezeigt werden. Nicht alle Fehler sollten als zu protokollierende Vorfälle behandelt werden.

Weitere Informationen finden Sie in den folgenden Artikeln:

• Blazor-Protokollierung in ASP.NET Core
• Fehlerbehandlung in ASP.NET Core‡
• Erstellen von Web-APIs mit ASP.NET Core

‡Betrifft serverseitige Blazor-Apps und andere serverseitige ASP.NET Core-Apps, die als Web-API-Back-End-Apps für Blazor dienen. Clientseitige Apps können Fehlerinformationen auf dem Client abfangen und an eine Web-API senden, die die Fehlerinformationen in einem persistenten Protokollierungsanbieter protokolliert.

Im Fall eines Ausnahmefehlers wird die Ausnahme in den im Dienstcontainer konfiguriertenILogger-Instanzen protokolliert. Blazor-Apps protokollieren standardmäßig in die Konsolenausgabe beim Konsolenprotokollierungsanbieter. Sie sollten einen dauerhaften Speicherort auf dem Server für die Protokollierung verwenden, indem Sie Fehlerinformationen an eine Back-End-Web-API senden, die einen Protokollierungsanbieter mit Verwaltung der Protokollgröße und Protokollrotation verwendet. Alternativ kann die Back-End-Web-API-App einen APM-Dienst (Application Performance Management) verwenden, z. B. Azure Application Insights (Azure Monitor)†, um Fehlerinformationen aufzuzeichnen, die von Clients empfangen werden.

Sie müssen entscheiden, welche Vorfälle protokolliert werden sollen. Zudem müssen Sie den Schweregrad für protokollierte Vorfälle festlegen. Feindliche Benutzer können Fehler möglicherweise absichtlich auslöst. Protokollieren Sie beispielsweise keinen Vorfall aus einem Fehler, bei dem eine unbekannte ProductId in der URL einer Komponente angegeben wurde, über die Produktdetails angezeigt werden. Nicht alle Fehler sollten als zu protokollierende Vorfälle behandelt werden.

Weitere Informationen finden Sie in den folgenden Artikeln:

• Blazor-Protokollierung in ASP.NET Core
• Fehlerbehandlung in ASP.NET Core‡
• Erstellen von Web-APIs mit ASP.NET Core

†Native Application Insights-Features für die Unterstützung clientseitiger Apps und die native Unterstützung des Blazor-Frameworks für Google Analytics werden möglicherweise in zukünftigen Releases dieser Technologien zur Verfügung gestellt. Weitere Informationen finden Sie unter Support App Insights in Blazor WASM Client Side (microsoft/ApplicationInsights-dotnet #2143) und Web analytics and diagnostics (enthält Links zu Implementierungen der Community) (dotnet/aspnetcore #5461). In der Zwischenzeit kann eine clientseitige App das Application Insights JavaScript SDK mit JSInterop verwenden, um Fehler aus einer clientseitigen App direkt in Application Insights zu protokollieren.

‡Betrifft serverseitige ASP.NET Core-Apps, die als Web-API-Back-End-Apps für Blazor-Apps dienen. Clientseitige Apps fangen Fehlerinformationen ab und senden sie an eine Web-API, die die Fehlerinformationen in einem persistenten Protokollierungsanbieter protokolliert.

• Komponenteninstanziierung
• Lebenszyklusmethoden
• Renderinglogik
• Ereignishandler
• Beseitigung von Komponenten
• JavaScript-Interoperabilität
• Voarabrendering

• Komponenteninstanziierung
• Lebenszyklusmethoden
• Renderinglogik
• Ereignishandler
• Beseitigung von Komponenten
• JavaScript-Interoperabilität
• Voarabrendering

@page "/product-details/{ProductId:int?}"
@inject ILogger<ProductDetails> Logger
@inject IProductRepository Product

<PageTitle>Product Details</PageTitle>

<h1>Product Details Example</h1>

@if (details != null)
{
    <h2>@details.ProductName</h2>
    <p>
        @details.Description
        <a href="@details.Url">Company Link</a>
    </p>
    
}
else if (loadFailed)
{
    <h1>Sorry, we could not load this product due to an error.</h1>
}
else
{
    <h1>Loading...</h1>
}

@code {
    private ProductDetail? details;
    private bool loadFailed;

    [Parameter]
    public int ProductId { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        try
        {
            loadFailed = false;

            // Reset details to null to display the loading indicator
            details = null;

            details = await Product.GetProductByIdAsync(ProductId);
        }
        catch (Exception ex)
        {
            loadFailed = true;
            Logger.LogWarning(ex, "Failed to load product {ProductId}", ProductId);
        }
    }

    public class ProductDetail
    {
        public string? ProductName { get; set; }
        public string? Description { get; set; }
        public string? Url { get; set; }
    }

    /*
    * Register the service in Program.cs:
    * using static BlazorSample.Components.Pages.ProductDetails;
    * builder.Services.AddScoped<IProductRepository, ProductRepository>();
    */

    public interface IProductRepository
    {
        public Task<ProductDetail> GetProductByIdAsync(int id);
    }

    public class ProductRepository : IProductRepository
    {
        public Task<ProductDetail> GetProductByIdAsync(int id)
        {
            return Task.FromResult(
                new ProductDetail()
                {
                    ProductName = "Flowbee ",
                    Description = "The Revolutionary Haircutting System You've Come to Love!",
                    Url = "https://flowbee.com/"
                });
        }
    }
}

@page "/product-details/{ProductId:int?}"
@inject ILogger<ProductDetails> Logger
@inject IProductRepository Product

<PageTitle>Product Details</PageTitle>

<h1>Product Details Example</h1>

@if (details != null)
{
    <h2>@details.ProductName</h2>
    <p>
        @details.Description
        <a href="@details.Url">Company Link</a>
    </p>
    
}
else if (loadFailed)
{
    <h1>Sorry, we could not load this product due to an error.</h1>
}
else
{
    <h1>Loading...</h1>
}

@code {
    private ProductDetail? details;
    private bool loadFailed;

    [Parameter]
    public int ProductId { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        try
        {
            loadFailed = false;

            // Reset details to null to display the loading indicator
            details = null;

            details = await Product.GetProductByIdAsync(ProductId);
        }
        catch (Exception ex)
        {
            loadFailed = true;
            Logger.LogWarning(ex, "Failed to load product {ProductId}", ProductId);
        }
    }

    public class ProductDetail
    {
        public string? ProductName { get; set; }
        public string? Description { get; set; }
        public string? Url { get; set; }
    }

    /*
    * Register the service in Program.cs:
    * using static BlazorSample.Components.Pages.ProductDetails;
    * builder.Services.AddScoped<IProductRepository, ProductRepository>();
    */

    public interface IProductRepository
    {
        public Task<ProductDetail> GetProductByIdAsync(int id);
    }

    public class ProductRepository : IProductRepository
    {
        public Task<ProductDetail> GetProductByIdAsync(int id)
        {
            return Task.FromResult(
                new ProductDetail()
                {
                    ProductName = "Flowbee ",
                    Description = "The Revolutionary Haircutting System You've Come to Love!",
                    Url = "https://flowbee.com/"
                });
        }
    }
}

@page "/product-details/{ProductId:int}"
@using Microsoft.Extensions.Logging
@inject ILogger<ProductDetails> Logger
@inject IProductRepository ProductRepository

@if (details != null)
{
    <h1>@details.ProductName</h1>
    <p>@details.Description</p>
}
else if (loadFailed)
{
    <h1>Sorry, we could not load this product due to an error.</h1>
}
else
{
    <h1>Loading...</h1>
}

@code {
    private ProductDetail? details;
    private bool loadFailed;

    [Parameter]
    public int ProductId { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        try
        {
            loadFailed = false;

            // Reset details to null to display the loading indicator
            details = null;

            details = await ProductRepository.GetProductByIdAsync(ProductId);
        }
        catch (Exception ex)
        {
            loadFailed = true;
            Logger.LogWarning(ex, "Failed to load product {ProductId}", ProductId);
        }
    }

    public class ProductDetail
    {
        public string? ProductName { get; set; }
        public string? Description { get; set; }
    }

    public interface IProductRepository
    {
        public Task<ProductDetail> GetProductByIdAsync(int id);
    }
}

@page "/product-details/{ProductId:int}"
@using Microsoft.Extensions.Logging
@inject ILogger<ProductDetails> Logger
@inject IProductRepository ProductRepository

@if (details != null)
{
    <h1>@details.ProductName</h1>
    <p>@details.Description</p>
}
else if (loadFailed)
{
    <h1>Sorry, we could not load this product due to an error.</h1>
}
else
{
    <h1>Loading...</h1>
}

@code {
    private ProductDetail? details;
    private bool loadFailed;

    [Parameter]
    public int ProductId { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        try
        {
            loadFailed = false;

            // Reset details to null to display the loading indicator
            details = null;

            details = await ProductRepository.GetProductByIdAsync(ProductId);
        }
        catch (Exception ex)
        {
            loadFailed = true;
            Logger.LogWarning(ex, "Failed to load product {ProductId}", ProductId);
        }
    }

    public class ProductDetail
    {
        public string? ProductName { get; set; }
        public string? Description { get; set; }
    }

    public interface IProductRepository
    {
        public Task<ProductDetail> GetProductByIdAsync(int id);
    }
}

@page "/product-details/{ProductId:int}"
@using Microsoft.Extensions.Logging
@inject ILogger<ProductDetails> Logger
@inject IProductRepository ProductRepository

@if (details != null)
{
    <h1>@details.ProductName</h1>
    <p>@details.Description</p>
}
else if (loadFailed)
{
    <h1>Sorry, we could not load this product due to an error.</h1>
}
else
{
    <h1>Loading...</h1>
}

@code {
    private ProductDetail details;
    private bool loadFailed;

    [Parameter]
    public int ProductId { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        try
        {
            loadFailed = false;

            // Reset details to null to display the loading indicator
            details = null;

            details = await ProductRepository.GetProductByIdAsync(ProductId);
        }
        catch (Exception ex)
        {
            loadFailed = true;
            Logger.LogWarning(ex, "Failed to load product {ProductId}", ProductId);
        }
    }

    public class ProductDetail
    {
        public string ProductName { get; set; }
        public string Description { get; set; }
    }

    public interface IProductRepository
    {
        public Task<ProductDetail> GetProductByIdAsync(int id);
    }
}

@page "/product-details/{ProductId:int}"
@using Microsoft.Extensions.Logging
@inject ILogger<ProductDetails> Logger
@inject IProductRepository ProductRepository

@if (details != null)
{
    <h1>@details.ProductName</h1>
    <p>@details.Description</p>
}
else if (loadFailed)
{
    <h1>Sorry, we could not load this product due to an error.</h1>
}
else
{
    <h1>Loading...</h1>
}

@code {
    private ProductDetail details;
    private bool loadFailed;

    [Parameter]
    public int ProductId { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        try
        {
            loadFailed = false;

            // Reset details to null to display the loading indicator
            details = null;

            details = await ProductRepository.GetProductByIdAsync(ProductId);
        }
        catch (Exception ex)
        {
            loadFailed = true;
            Logger.LogWarning(ex, "Failed to load product {ProductId}", ProductId);
        }
    }

    public class ProductDetail
    {
        public string ProductName { get; set; }
        public string Description { get; set; }
    }

    public interface IProductRepository
    {
        public Task<ProductDetail> GetProductByIdAsync(int id);
    }
}

Voarabrendering

Razor-Komponenten können vorab gerendert werden, sodass das gerenderte HTML-Markup als Teil der ursprünglichen HTTP-Benutzeranforderung zurückgegeben wird.

In einer Blazor-App, die über eine Leitung betrieben wird, funktioniert das Vorabrendering folgendermaßen:

• Erstellen einer neuen Leitung für alle vorab gerenderten Komponenten, die Teil derselben Seite sind
• Generieren des ursprünglichen HTML-Codes
• Behandeln der Leitung als disconnected, bis der Browser des Benutzers eine SignalR-Verbindung zurück zum selben Server einrichtet. Wenn die Verbindung hergestellt wird, wird die Interaktivität in der Leitung fortgesetzt und das HTML-Markup der Komponenten wird aktualisiert.

Bei vorab gerenderten clientseitigen Komponenten funktioniert das Vorabrendering folgendermaßen:

• Generieren des anfänglichen HTML-Codes auf dem Server für alle vorab gerenderten Komponenten, die Teil einer Seite sind.
• Gestalten der Komponente auf dem Client als interaktiv, nachdem der Browser den kompilierten Code der App und die .NET-Runtime (sofern noch nicht geladen) im Hintergrund geladen hat.

Wenn von einer Komponente während des Vorabrenderns ein Ausnahmefehler beispielswiese während einer Lebenszyklusmethode oder in der Renderinglogik ausgelöst wird, gilt Folgendes:

• Bei Blazor-Apps, die über eine Leitung betrieben werden, ist die Ausnahme für die Leitung schwerwiegend. Bei vorab gerenderten clientseitigen Komponenten verhindert die Ausnahme, dass die Komponente gerendert wird.
• Die Ausnahme wird vom ComponentTagHelper in der Aufrufliste weiter oben ausgelöst.

Wenn das Prerendering unter normalen Umständen fehlschlägt, ist es nicht sinnvoll, mit dem Erstellen und Rendern der Komponente fortzufahren, da eine funktionierende Komponente nicht gerendert werden kann.

Wenn während des Prerenderings auftretende Fehler toleriert werden sollen, muss sich die Fehlerbehandlungslogik in einer Komponente befinden, die möglicherweise Ausnahmen auslöst. Verwenden Sie try-catch-Anweisungen mit Fehlerbehandlung und Fehlerprotokollierung. Statt das ComponentTagHelper in einer try-catch-Anweisung zu umschließen, fügen Sie eine Fehlerbehandlungslogik in die vom ComponentTagHelper gerenderte Komponente ein.

• Behandeln abgefangener Ausnahmen außerhalb des Lebenszyklus einer Razor-Komponente
• Blazor-Protokollierung in ASP.NET Core
• Fehlerbehandlung in ASP.NET Core†
• Erstellen von Web-APIs mit ASP.NET Core
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)

• Blazor-Protokollierung in ASP.NET Core
• Fehlerbehandlung in ASP.NET Core†
• Erstellen von Web-APIs mit ASP.NET Core
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)