Übersicht über ASP.NET Core Blazor Formulare

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

• Eine EditForm-Komponente, die an ein Objekt oder Modell gebunden ist, das Datenanmerkungen verwenden kann
• Integrierte Eingabekomponenten

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

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

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.

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.

Ein Formular wird mithilfe der EditForm-Komponente des Blazor-Frameworks definiert. Die folgende Razor-Komponente veranschaulicht typische Elemente, Komponenten und Razor-Code zum Rendern eines Webformulars mithilfe einer EditForm-Komponente.

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

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

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.

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

<EditForm Model="Model" OnSubmit="Submit">
    <InputText @bind-Value="Model!.Id" />
    <button type="submit">Submit</button>
</EditForm>

@code {
    public Starship? Model { get; set; }

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

    private void Submit()
    {
        Logger.LogInformation("Model.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 Modell wird im @code-Block der Komponente erstellt und in einem privaten Feld (model) gespeichert. Das Feld wird dem Parameter EditForm.Model zugewiesen.
• 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.

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

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

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

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

@code {
    public 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; }
    }
}

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

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

Beispiele verwenden den als Ziel typisierten new-Operator, der mit C# 9.0 und .NET 5 eingeführt wurde. Im folgenden Beispiel wird der Typ für den new-Operator nicht explizit angegeben:

public ShipDescription ShipDescription { get; set; } = new();

Wenn Sie C# 8.0 oder früher (ASP.NET Core 3.1) verwenden, ändern Sie den Beispielcode so, dass er den Typ für den new-Operator angibt:

public ShipDescription ShipDescription { get; set; } = new ShipDescription();

Komponenten verwenden Nullwerte zulassende Verweistypen (Nullable Reference Types, NRTs), und der .NET-Compiler führt statische Nullzustandsanalysen durch. Beides wird in .NET 6 oder höher unterstützt. Weitere Informationen finden Sie unter Migrieren von ASP.NET Core 5.0 zu 6.0.

Wenn Sie C# 9.0 oder früher (.NET 5 oder früher) verwenden, entfernen Sie die NRTs aus den Beispielen. In der Regel müssen Sie lediglich die Fragezeichen (?) und Ausrufezeichen (!) aus den Typen im Beispielcode entfernen.

Das .NET SDK wendet implizite globale using-Anweisungen auf Projekte an, wenn das Ziel.NET 6 oder höher ist. Die Beispiele verwenden eine Protokollierung zum Protokollieren von Informationen zur Formularverarbeitung, es ist jedoch nicht erforderlich, eine @using-Anweisung für den Namespace Microsoft.Extensions.Logging in den Komponentenbeispielen anzugeben. Weitere Informationen finden Sie unter .NET-Projekt-SDKs: implizite using-Anweisungen.

Wenn Sie C# 9.0 oder früher (.NET 5 oder früher) verwenden, fügen Sie @using-Anweisungen am Anfang der Komponente nach der @page-Anweisung für jede API hinzu, die im Beispiel erforderlich ist. Suchen Sie API-Namespaces über Visual Studio (klicken Sie mit der rechten Maustaste auf das Objekt, und wählen Sie Definition einsehen) oder den .NET-API-Browser aus.

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.

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

• Blazor-Dateiuploads in ASP.NET Core
• Sichern einer gehosteten ASP.NET Core Blazor WebAssembly-App mit Microsoft Entera-ID
• Schützen einer gehosteten ASP.NET Core Blazor WebAssembly-App mit Azure Active Directory B2C
• Sichern einer in ASP.NET Core gehosteten Blazor WebAssembly-App mit Identity-Server
• GitHub-Repository mit Blazor-Beispielen (dotnet/blazor-samples) (Informationen zum Herunterladen)
• Testassets für Formulare im ASP.NET Core GitHub-Repository (dotnet/aspnetcore)