Übersicht über ASP.NET Core Blazor Formulare

In diesem Artikel wird erläutert, wie Formulare in Blazor verwendet werden können.

Eingabekomponenten und Formulare

Das Blazor-Framework unterstützt Formulare und bietet integrierte Eingabekomponenten:

• Gebunden an ein Objekt oder Modell, das Datenanmerkungen verwenden kann
  • HTML-Formulare mit dem <form>-Element
  • EditForm-Komponenten
• Integrierte Eingabekomponenten

Hinweis

Nicht unterstützte ASP.NET Core-Validierungsfunktionen werden im Abschnitt Nicht unterstützte Validierungsfunktionen behandelt.

Der Namespace Microsoft.AspNetCore.Components.Forms bietet Folgendes:

• Klassen zum Verwalten von Formularelementen, Zustand und Validierung.
• Zugriff auf integrierte Input*-Komponenten.

Ein Projekt, das mit der Blazor-Projektvorlage erstellt wurde, enthält den Namespace in der _Imports.razor-Datei der Anwendung, wodurch der Namespace für die Razor-Komponenten der Anwendung verfügbar wird.

Standard-HTML-Formulare werden unterstützt. Erstellen Sie ein Formular mit dem normalen HTML-Tag <form>, und geben Sie einen @onsubmit-Handler für die Verarbeitung der übermittelten Formularanforderung an.

StarshipPlainForm.razor:

@page "/starship-plain-form"
@inject ILogger<StarshipPlainForm> Logger

<form method="post" @onsubmit="Submit" @formname="starship-plain-form">
    <AntiforgeryToken />
    <div>
        <label>
            Identifier: 
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</form>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        public string? Id { get; set; }
    }
}

In der vorherigen StarshipPlainForm-Komponente:

• Das Formular dort gerendert, wo das <form>-Element erscheint. Das Formular wird mit dem @formname Direktiven-Attribut benannt, das das Formular eindeutig für das Blazor Framework identifiziert.
• Das Modell wird im @code-Block der Komponente erstellt und in einer öffentlichen Eigenschaft (Model) gespeichert. Das Attribut [SupplyParameterFromForm] gibt an, dass der Wert der zugeordneten Eigenschaft aus den Formulardaten bereitgestellt werden soll. Daten in der Anforderung, die dem Namen der Eigenschaft entsprechen, werden an die Eigenschaft gebunden.
• Die InputText-Komponente ist eine Eingabekomponente zum Bearbeiten von Zeichenfolgenwerten. Das @bind-Value-Anweisungsattribut bindet die Model.Id-Modelleigenschaft an die Value-Eigenschaft der InputText-Komponente.
• Die Submit-Methode wird als Handler für den @onsubmit-Rückruf registriert. Der Handler wird aufgerufen, wenn das Formular vom Benutzer übermittelt wird.

Wichtig

Verwenden Sie immer das @formname Direktive-Attribut mit einem eindeutigen Formularnamen.

Blazor verbessert die Seitennavigation und Formularverarbeitung, indem die Anforderung abgefangen wird, um die Antwort auf das vorhandene Dokumentobjektmodell (DOM) anzuwenden, wobei ein möglichst großer Teil des gerenderten Formulars erhalten bleibt. Durch diese Verbesserung entfällt die Notwendigkeit, die Seite vollständig zu laden, was zu einem wesentlich reibungsloseren Benutzererlebnis führt, ähnlich wie eine Single-Page-App (SPA), obwohl die Komponente auf dem Server gerendert wird. Weitere Informationen finden Sie unter ASP.NET Core: Routing und Navigation in Blazor.

Das Streamingrendering wird für einfache HTML-Formulare unterstützt.

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

Das vorstehende Beispiel beinhaltet Unterstützung der Fälschungssicherheit, indem eine AntiforgeryToken-Komponente in das Formular aufgenommen wird. Die Unterstützung der Fälschungssicherheit wird im Abschnitt Unterstützung der Fälschungssicherheit in diesem Artikel näher erläutert.

Verwenden Sie JavaScript, um ein Formular zu übermitteln (submit (MDN-Dokumentation)), das auf den DOM-Ereignissen eines anderen Elements basiert, beispielsweise auf oninput oder onblur.

Anstatt einfache Formulare in Blazor-Apps zu verwenden, wird ein Formular in der Regel mit der integrierten Formularunterstützung von Blazor mithilfe der Frameworkkomponente EditForm definiert. Die folgende Razor-Komponente veranschaulicht typische Elemente, Komponenten und Razor-Code zum Rendern eines Webformulars mithilfe einer EditForm-Komponente.

Starship1.razor:

@page "/starship-1"
@inject ILogger<Starship1> Logger

<EditForm Model="Model" OnSubmit="Submit" FormName="Starship1">
    <div>
        <label>
            Identifier:
            <InputText @bind-Value="Model!.Id" />
        </label>
    </div>
    <div>
        <button type="submit">Submit</button>
    </div>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        public string? Id { get; set; }
    }
}

In der vorherigen Starship1-Komponente:

• Die EditForm-Komponente dort gerendert, wo das <EditForm>-Element steht. Das Formular wird mit dem @formname Direktiven-Attribut benannt, das das Formular eindeutig für das Blazor Framework identifiziert.
• Das Modell wird im @code-Block der Komponente erstellt und in einer öffentlichen Eigenschaft (Model) gespeichert. Die Eigenschaft wird dem EditForm.Model-Parameter zugewiesen. Das Attribut [SupplyParameterFromForm] gibt an, dass der Wert der zugeordneten Eigenschaft aus den Formulardaten bereitgestellt werden soll. Daten in der Anforderung, die dem Namen der Eigenschaft entsprechen, werden an die Eigenschaft gebunden.
• Die InputText-Komponente ist eine Eingabekomponente zum Bearbeiten von Zeichenfolgenwerten. Das @bind-Value-Anweisungsattribut bindet die Model.Id-Modelleigenschaft an die Value-Eigenschaft der InputText-Komponente.
• Die Methode Submit wird als Handler für den OnSubmit-Rückruf registriert. Der Handler wird aufgerufen, wenn das Formular vom Benutzer übermittelt wird.

Wichtig

Verwenden Sie immer das @formname Direktive-Attribut mit einem eindeutigen Formularnamen.

Blazor verbessert die Seitennavigation und die Handhabung von Formularen für EditForm-Komponenten. Weitere Informationen finden Sie unter ASP.NET Core: Routing und Navigation in Blazor.

Das Streamingrendering wird für EditForm unterstützt.

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 zur Eigenschaftenbindung finden Sie unter Blazor-Datenbindung in ASP.NET Core.

Im nächsten Beispiel wird die vorherige Komponente so geändert, dass das Formular in der Starship2-Komponente erstellt wird:

• OnSubmit wird durch OnValidSubmit ersetzt. Dadurch wird der zugewiesene Ereignishandler verarbeitet, wenn das Formular bei Übermittlung durch den Benutzer gültig ist.
• Eine ValidationSummary-Komponente wird hinzugefügt, um Validierungsmeldungen anzuzeigen, wenn das Formular bei der Formularübermittlung ungültig ist.
• Das Datenanmerkungs-Validierungssteuerelement (DataAnnotationsValidator-Komponente†) fügt Validierungsunterstützung mithilfe von Datenkommentaren hinzu:
  • Wenn das Formularfeld <input> leer gelassen wird, wenn die Schaltfläche Submit ausgewählt ist, wird in der Validierungszusammenfassung (ValidationSummary-Komponente‡) ein Fehler angezeigt („The Id field is required.“), und Submit wird nicht aufgerufen.
  • Wenn das Formularfeld <input> bei ausgewählter Schaltfläche Submit mehr als 10 Zeichen enthält, wird in der Validierungszusammenfassung ein Fehler angezeigt („Id is too long.“). Submit wird nicht aufgerufen.
  • Wenn das Formularfeld <input> bei ausgewählter Schaltfläche Submit einen gültigen Wert enthält, wird Submit aufgerufen.

†Die DataAnnotationsValidator-Komponente wird im Abschnitt Validierungssteuerelement-Komponente behandelt. ‡Die ValidationSummary-Komponente wird im Abschnitt Komponenten der Validierungszusammenfassung und der Validierungsnachricht behandelt.

Starship2.razor:

@page "/starship-2"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship2> Logger

<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship2">
    <DataAnnotationsValidator />
    <ValidationSummary />
    <label>
        Identifier: 
        <InputText @bind-Value="Model!.Id" />
    </label>
    <button type="submit">Submit</button>
</EditForm>

@code {
    [SupplyParameterFromForm]
    private Starship? Model { get; set; }

    protected override void OnInitialized() => Model ??= new();

    private void Submit() => Logger.LogInformation("Id = {Id}", Model?.Id);

    public class Starship
    {
        [Required]
        [StringLength(10, ErrorMessage = "Id is too long.")]
        public string? Id { get; set; }
    }
}

Behandeln von Formularübermittlungen

Das EditForm stellt die folgenden Rückrufe für die Behandlung der Formularübermittlung bereit:

• Verwenden Sie OnValidSubmit, um einen Ereignishandler zuzuweisen, der ausgeführt wird, wenn ein Formular mit gültigen Feldern übermittelt wird.
• Verwenden Sie OnInvalidSubmit, um einen Ereignishandler zuzuweisen, der ausgeführt wird, wenn ein Formular mit ungültigen Feldern übermittelt wird.
• Verwenden Sie OnSubmit, um einen Ereignishandler zuzuweisen, der unabhängig vom Validierungsstatus der Formularfelder ausgeführt wird. Das Formular wird überprüft, indem EditContext.Validate in der Ereignishandlermethode aufgerufen wird. Wenn Validatetrue zurückgibt, ist das Formular gültig.

Löschen eines Formulars oder Felds

Setzen Sie ein Formular zurück, indem Sie das Modell wieder auf den Standardzustand zurücksetzen. Dies ist innerhalb oder außerhalb des Markups von EditForm möglich:

<button @onclick="ClearForm">Clear form</button>

...

private void ClearForm() => Model = new();

Verwenden Sie alternativ einen expliziten Razor-Ausdruck:

<button @onclick="@(() => Model = new())">Clear form</button>

Setzen Sie ein Feld zurück, indem Sie den Modellwert auf den Standardzustand zurücksetzen:

<button @onclick="ResetId">Reset Identifier</button>

...

private void ResetId() => Model!.Id = string.Empty;

Verwenden Sie alternativ einen expliziten Razor-Ausdruck:

<button @onclick="@(() => Model!.Id = string.Empty)">Reset Identifier</button>

Es ist nicht erforderlich, in den vorherigen Beispielen StateHasChanged aufzurufen, da StateHasChanged automatisch vom Blazor-Framework aufgerufen wird, um die Komponente erneut zu rendern, nachdem ein Ereignishandler aufgerufen wurde. Wenn zum Aufrufen der Methoden für das Leeren eines Formulars oder Felds kein Ereignishandler verwendet wird, sollte im Code StateHasChanged aufgerufen werden, um die Komponente erneut zu rendern.

Unterstützung des Schutzes vor Fälschung

Antiforgery-Dienste werden Blazor-Apps automatisch hinzugefügt, wenn AddRazorComponents in der Datei Program aufgerufen wird.

Die App verwendet Antiforgery-Middleware, indem UseAntiforgery in der Datei Program innerhalb der Pipeline zur Anforderungsverarbeitung aufgerufen wird. UseAntiforgery wird nach dem Aufruf von UseRouting aufgerufen. Wenn Anrufe von UseRouting und UseEndpoints vorhanden, muss der Aufruf von UseAntiforgery zwischen diesen liegen. Der Aufruf von UseAntiforgery muss nach den Aufrufen von UseAuthentication und UseAuthorization erfolgen.

Die AntiforgeryToken-Komponente rendert ein Token für den Fälschungsschutz als verborgenes Feld, und das [RequireAntiforgeryToken]-Attribut aktiviert den Schutz. Wenn eine Überprüfung des Fälschungsschutzes einen Fehler zurückgibt, wird eine 400 - Bad Request-Antwort ausgelöst, und das Formular wird nicht verarbeitet.

Bei Formularen, die auf EditForm basieren, werden die Komponente AntiforgeryToken und das Attribut [RequireAntiforgeryToken] automatisch hinzugefügt, um einen Fälschungsschutz zu gewährleisten.

Fügen Sie Formularen, die auf dem HTML-Element <form> basieren, die AntiforgeryToken-Komponente manuell hinzu:

<form method="post" @onsubmit="Submit" @formname="starshipForm">
    <AntiforgeryToken />
    <input id="send" type="submit" value="Send" />
</form>

@if (submitted)
{
    <p>Form submitted!</p>
}

@code{
    private bool submitted = false;

    private void Submit() => submitted = true;
}

Warnung

Bei Formularen, die auf EditForm oder dem HTML-Element <form> basieren, kann der Fälschungsschutz deaktiviert werden, indem required: false an das Attribut [RequireAntiforgeryToken] übergeben wird. Das folgende Beispiel deaktiviert den Fälschungsschutz und wird für öffentliche Apps nicht empfohlen:

@using Microsoft.AspNetCore.Antiforgery
@attribute [RequireAntiforgeryToken(required: false)]

Weitere Informationen hierzu finden Sie unter Authentifizierung und Autorisierung in ASP.NET Core Blazor.

Abschwächen von Overpostingangriffen

Statisch gerenderte serverseitige Formulare können anfällig gegenüber Angriffen mit Overposting sein, die ebenfalls als Angriffe mit Massenzuweisungen bezeichnet werden. Hierzu zählen die Formulare, die normalerweise in Komponenten verwendet werden, die Datensätze in einer Datenbank mit einem Formularmodell erstellen und bearbeiten. Ein Overpostingangriff tritt auf, wenn ein böswilliger Benutzer eine POST-Anweisung für ein HTML-Formular an den Server ausgibt, der Daten für Eigenschaften verarbeitet, die nicht Teil des gerenderten Formulars sind und für die der Entwickler Benutzern keine Berechtigung zum Ändern gewähren möchte. Der Begriff „Overposting“ bedeutet, dass der böswillige Benutzer den Server mit dem Formular buchstäblich überladen hat.

Das Overposting stellt kein Problem dar, sofern das Modell keine eingeschränkten Eigenschaften für Vorgänge zur Erstellung und Aktualisierung enthält. Es ist jedoch wichtig, das Overposting beim Arbeiten mit statischen SSR-basierten Blazor-Formularen zu beachten, die Sie verwalten.

Zur Abschwächung des Overpostings wird für das Formular und die Datenbank mit Vorgängen zur Erstellung (einfügen) und Aktualisierung die Verwendung eines separaten Ansichtsmodells bzw. Datenübertragungsobjekts (DTO) empfohlen. Bei der Übermittlung des Formulars werden lediglich Eigenschaften des Ansichtsmodells bzw. des DTO durch die Komponente und den C#-Code verwendet, um die Datenbank zu ändern. Alle zusätzlichen Daten, die von einem böswilligen Benutzer eingeschlossen wurden, werden verworfen. Dadurch wird der böswillige Benutzer daran gehindert, einen Overpostingangriff durchzuführen.

Erweiterte Formularverarbeitung

Erweiterte Navigation für POST-Anforderungen von Formularen mit dem Enhance-Parameter für EditForm-Formulare oder dem data-enhance-Attribut für HTML-Formulare (<form>):

<EditForm ... Enhance ...>
    ...
</EditForm>

<form ... data-enhance ...>
    ...
</form>

❌Nicht unterstützt: Sie können die erweiterte Navigation im Vorgängerelement eines Formulars nicht festlegen, um die erweiterte Formularverarbeitung zu aktivieren.

<div ... data-enhance ...>
    <form ...>
        <!-- NOT enhanced -->
    </form>
</div>

Erweiterte Formularbeiträge funktionieren nur mit Blazor-Endpunkten. Das Bereitstellen eines erweiterten Formulars an einen Nicht-Blazor-Endpunkt führt zu einem Fehler.

So deaktivieren Sie die erweiterte Formularverarbeitung:

• Entfernen Sie für ein EditForm-Formular den Parameter Enhance aus dem Formularelement (oder legen Sie diesen auf false fest: Enhance="false").
• Entfernen Sie für einen <form>-HTML-Element den Parameter data-enhance aus dem Formularelement (oder legen Sie diesen auf false fest: data-enhance="false").

Die erweiterte Navigation und Formularverarbeitung von Blazor können dynamische Änderungen am Dokumentobjektmodell (DOM) rückgängig machen, wenn der aktualisierte Inhalt nicht Teil des Serverrenderings ist. Verwenden Sie das data-permanent-Attribut, um den Inhalt eines Elements beizubehalten.

Im folgenden Beispiel wird der Inhalt des <div>-Elements dynamisch durch ein Skript aktualisiert, wenn die Seite geladen wird:

<div data-permanent>
    ...
</div>

Informationen zum globalen Deaktivieren der erweiterten Navigation und Formularverarbeitung finden Sie unter ASP.NET Core Blazor-Start.

Einen Leitfaden zur Verwendung des enhancedload-Ereignisses, um nach erweiterter Seitenupdates zu lauschen, finden Sie unter Routing und Navigation in ASP.NET Core Blazor.

Beispiele

Beispiele übernehmen keine erweiterte Formularverarbeitung für POST-Anforderungen von Formularen, jedoch können alle Beispiele aktualisiert werden, um die erweiterten Features zu übernehmen. Befolgen Sie hierzu den Leitfaden im Abschnitt Erweiterte Formularverarbeitung.

Um zu veranschaulichen, wie Formulare mit Überprüfung von Datenanmerkungen funktionieren, verwenden die Beispielkomponenten die System.ComponentModel.DataAnnotations-API. Wenn Sie eine zusätzliche Codezeile in Komponenten vermeiden möchten, die Datenanmerkungen verwenden, stellen Sie den Namespace in den Komponenten der App mit der Importdatei zur Verfügung (_Imports.razor):

@using System.ComponentModel.DataAnnotations

Die Formularbeispiele beziehen sich auf Aspekte des Star Trek-Universums. Star Trek ist eine Marke von CBS Studios und Paramount mit Copyright ©1966-2023.

Für die clientseitige Überprüfung ist ein Schaltkreis erforderlich.

In Blazor Web Apps erfordert die clientseitige Überprüfung eine aktive BlazorSignalR-Leitung. Die clientseitige Überprüfung ist für Formulare in Komponenten, die statisches serverseitiges Rendering (statisches SSR) übernommen haben, nicht verfügbar. Formulare, die statisches SSR übernehmen, werden auf dem Server überprüft, nachdem das Formular gesendet wurde.

Nicht unterstützte Validierungsfunktionen

Alle in Datenanmerkungen integrierten Validatoren werden in Blazor unterstützt, außer dem Validierungsattribut [Remote].

die jQuery-Überprüfung wird in Razor Komponenten nicht unterstützt. Wir empfehlen eine der folgenden Ansätze:

• Befolgen Sie die Anleitungen in ASP.NET Core Blazor Forms Validation für eine der folgenden:
  • Serverseitige Überprüfung in einem Blazor Web App Modus, der einen interaktiven Rendermodus verwendet.
  • Clientseitige Überprüfung in einer eigenständigen Blazor Webassembly-App.
• Verwenden von nativen HTML-Validierungsattributen (siehe clientseitige Formularüberprüfung (MDN-Dokumentation)).
• Übernehmen Sie eine JavaScript-Überprüfungsbibliothek von Drittanbietern.

Bei statisch gerenderten Formularen auf dem Server wird ende 2025 ein neuer Mechanismus für die clientseitige Überprüfung für .NET 10 berücksichtigt. Weitere Informationen finden Sie unter Erstellen von gerenderten Serverformularen mit Clientüberprüfung Blazor ohne Schaltkreis (dotnet/aspnetcore #51040).

Zusätzliche Ressourcen

• Blazor-Dateiuploads in ASP.NET Core
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)
• Testassets für Formulare im ASP.NET Core GitHub-Repository (dotnet/aspnetcore)