Visão geral dos formulários do ASP.NET Core Blazor

• Vinculado a um objeto ou modelo que pode usar anotações de dados .
  • Formulários HTML com o elemento <form>.
  • EditForm componentes.
• Componentes de entrada integrados.

• Um componente EditForm vinculado a um objeto ou modelo que pode usar anotações de dados.
• Componentes de entrada integrados.

Formulários HTML padrão são suportados. Crie um formulário usando a tag HTML <form> normal e especifique um manipulador de @onsubmit para lidar com a solicitação de formulário enviada.

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

No componente StarshipPlainForm anterior:

• O formulário é renderizado onde o elemento <form> aparece. O formulário é nomeado com o atributo de diretiva @formname, que identifica exclusivamente o formulário para a estrutura Blazor.
• O modelo é criado no bloco de @code do componente e mantido em uma propriedade pública (Model). O atributo [SupplyParameterFromForm] indica que o valor da propriedade associada deve ser fornecido a partir dos dados do formulário. Os dados na solicitação que correspondem ao nome da propriedade são vinculados à propriedade.
• O componente InputText é um componente de entrada para edição de valores de cadeia de caracteres. O atributo de diretiva @bind-Value vincula a propriedade de modelo Model.Id à propriedade Value do componente InputText.
• O método Submit é registado como um manipulador para o callback @onsubmit. O manipulador é chamado quando o formulário é enviado pelo usuário.

Blazor melhora a navegação na página e o tratamento de formulários, intercetando a solicitação para aplicar a resposta ao DOM existente, preservando o máximo possível do formulário renderizado. O aprimoramento evita a necessidade de carregar totalmente a página e fornece uma experiência de usuário muito mais suave, semelhante a um aplicativo de página única (SPA), embora o componente seja renderizado no servidor. Para obter mais informações, consulte ASP.NET Core Blazor roteamento e navegação.

de renderização de streaming é suportada para formulários HTML simples.

O exemplo anterior inclui suporte antifalsificação, incluindo um componente AntiforgeryToken no formulário. O suporte antifalsificação é explicado mais detalhadamente na seção Suporte antifalsificação deste artigo.

Para enviar um formulário com base em eventos DOM de outro elemento, por exemplo, oninput ou onblur, use JavaScript para enviar o formulário (submit (documentação MDN)).

Em vez de usar formulários simples em aplicativos Blazor, um formulário normalmente é definido com suporte a formulários internos do Blazorusando o componente EditForm da estrutura. O componente Razor a seguir demonstra elementos, componentes e código Razor típicos para renderizar um formulário da Web usando um componente EditForm.

Um formulário é definido usando o componente EditForm da estrutura Blazor. O componente Razor a seguir demonstra elementos, componentes e código Razor típicos para renderizar um formulário da Web usando um componente EditForm.

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

No componente Starship1 previamente mencionado:

• O componente EditForm é renderizado onde o elemento <EditForm> aparece. O formulário é nomeado com a propriedade FormName, que identifica exclusivamente o formulário para a estrutura Blazor.
• O modelo é criado no bloco de @code do componente e mantido em uma propriedade pública (Model). A propriedade é atribuída ao parâmetro EditForm.Model. O atributo [SupplyParameterFromForm] indica que o valor da propriedade associada deve ser fornecido a partir dos dados do formulário. Os dados na solicitação que correspondem ao nome da propriedade são vinculados à propriedade.
• O componente InputText é um componente de entrada para editar valores de cadeia de caracteres. O atributo de diretiva @bind-Value vincula a propriedade do modelo Model.Id à propriedade Value do componente InputText.
• O método Submit é registado como um gestor para o callback OnSubmit. O manipulador é chamado quando o formulário é enviado pelo usuário.

Blazor melhora a navegação na página e a manipulação de formulários dos componentes EditForm. Para obter mais informações, consulte ASP.NET Core Blazor roteamento e navegação.

de renderização de streaming é suportado para EditForm.

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

No componente Starship1 anterior:

• O componente EditForm é renderizado onde o elemento <EditForm> aparece.
• O modelo é criado no bloco de @code do componente e mantido em um campo privado (model). O campo é atribuído ao parâmetro EditForm.Model.
• O componente InputText é um componente de entrada para edição de valores de cadeia de caracteres. O atributo de diretiva @bind-Value vincula a propriedade de modelo Model.Id à propriedade Value do componente InputText†.
• O método Submit é registado como um manipulador para o callback OnSubmit. O manipulador é chamado quando o formulário é enviado pelo usuário.

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

Suporte antifalsificação

Os serviços antifalsificação são automaticamente adicionados às aplicações Blazor quando AddRazorComponents é chamado no ficheiro Program.

A aplicação usa o Antiforgery Middleware ao chamar UseAntiforgery no seu pipeline de processamento de pedidos no ficheiro Program. UseAntiforgery é chamado após a chamada para UseRouting. Se houver chamadas para UseRouting e UseEndpoints, a chamada para UseAntiforgery deve ir entre eles. Uma chamada para UseAntiforgery deve ser feita após chamadas para UseAuthentication e UseAuthorization.

O componente AntiforgeryToken renderiza um token antifalsificação como um campo oculto e o atributo [RequireAntiforgeryToken] habilita a proteção antifalsificação. Se uma verificação antifalsificação falhar, uma resposta 400 - Bad Request será lançada e o formulário não será processado.

Para formulários baseados em EditForm, o componente AntiforgeryToken e o atributo [RequireAntiforgeryToken] são adicionados automaticamente para fornecer proteção antifalsificação.

Para formulários baseados no elemento HTML <form>, adicione manualmente o componente AntiforgeryToken ao formulário:

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

Para obter mais informações, consulte ASP.NET Core Blazor authentication and authorization.

Atenuar os ataques de sobrepostagem

Formulários do lado do servidor renderizados estaticamente, como aqueles normalmente usados em componentes que criam e editam registros em um banco de dados com um modelo de formulário, podem ser vulneráveis a um ataque de de sobrepostagem , também conhecido como ataque de de atribuição em massa de . Um ataque de sobrepostagem ocorre quando um usuário mal-intencionado emite um formulário HTML POST para o servidor que processa dados para propriedades que não fazem parte do formulário renderizado e que o desenvolvedor não deseja permitir que os usuários modifiquem. O termo "overposting" significa literalmente que o utilizador mal-intencionado realizou um "POST" em excesso com o formulário sobre.

A sobrepostagem não é uma preocupação quando o modelo não inclui propriedades restritas para operações de criação e atualização. No entanto, é importante ter em mente a sobrepostagem ao trabalhar com formulários Blazor estáticos baseados em SSR que você mantém.

Para reduzir a sobrepostagem, recomendamos o uso de um modelo de exibição/objeto de transferência de dados (DTO) separado para o formulário e o banco de dados com operações de criação (inserção) e atualização. Quando o formulário é enviado, somente as propriedades do modelo de exibição/DTO são usadas pelo componente e pelo código C# para modificar o banco de dados. Todos os dados adicionais incluídos por um usuário mal-intencionado são descartados, para que o usuário mal-intencionado seja impedido de realizar um ataque de superpostagem.

Tratamento de formulários aprimorado

Aprimore o de navegação para solicitações POST de formulário com o parâmetro Enhance para formulários EditForm ou o atributo data-enhance para formulários HTML (<form>):

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

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

❌ Sem suporte: Não é possível definir a navegação aprimorada no elemento ancestral de um formulário para habilitar o tratamento aprimorado de formulários.

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

As publicações de formulário aprimoradas apenas funcionam com endpoints Blazor. A publicação de um formulário avançado em um ponto de extremidade nãoBlazor resulta em um erro.

Para desativar o tratamento avançado de formulários:

• Para um EditForm, remova o parâmetro Enhance do elemento de formulário (ou defina-o como false: Enhance="false").
• Para um HTML <form>, remova o atributo data-enhance do elemento de formulário (ou configurá-lo para false: data-enhance="false").

A navegação e o manuseamento de formulários melhorados do Blazorpodem reverter alterações dinâmicas no DOM se o conteúdo atualizado não fizer parte da renderização do servidor. Para preservar o conteúdo de um elemento, use o atributo data-permanent.

No exemplo a seguir, o conteúdo do elemento <div> é atualizado dinamicamente por um script quando a página é carregada:

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

Para desativar a navegação aprimorada e a manipulação de formulários globalmente, consulte ASP.NET Core Blazor startup.

Para obter orientação sobre como usar o evento enhancedload para ouvir atualizações de página aprimoradas, consulte ASP.NET Core Blazor roteamento e navegação.

Os exemplos não adotam o tratamento aprimorado de formulários para solicitações POST, mas todos os exemplos podem ser atualizados para adotar os recursos aprimorados seguindo as orientações na seção Tratamento de formulário aprimorado.

Os exemplos usam o operador tipificado por destino new, que foi introduzido com C# 9.0 e .NET 5. No exemplo a seguir, o tipo não é explicitamente declarado para o operador new:

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

Se estiver usando C# 8.0 ou anterior (ASP.NET Core 3.1), modifique o código de exemplo para indicar o tipo para o operador new:

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

Os componentes usam tipos de referência anuláveis (NRTs) e o compilador .NET executa a análise estática de estado nulo, ambos suportados no .NET 6 ou posterior. Para mais informações, consulte a secção sobre a migração do ASP.NET Core 5.0 para o 6.0.

Se estiver usando C# 9.0 ou anterior (.NET 5 ou anterior), remova as NRTs dos exemplos. Normalmente, isso envolve apenas a remoção dos pontos de interrogação (?) e pontos de exclamação (!) dos tipos no código de exemplo.

O SDK do .NET aplica diretivas globais using implícitas a projetos quando o alvo é .NET 6 ou posterior. Os exemplos usam um registrador para registrar informações sobre o processamento de formulários, mas não é necessário especificar uma diretiva @using para o namespace Microsoft.Extensions.Logging nos exemplos de componentes. Para mais informações, consulte os SDKs de projeto .NET: Diretivas de utilização implícitas.

Se estiver usando C# 9.0 ou anterior (.NET 5 ou anterior), adicione diretivas @using à parte superior do componente após a diretiva @page para qualquer API exigida pelo exemplo. Encontre namespaces de API por meio do Visual Studio (clique com o botão direito do mouse no objeto e selecione Peek Definition) ou do navegador de API .NET .

A validação do lado do cliente requer um circuito

Em Blazor Web Apps, a validação no lado do cliente requer um circuito de BlazorSignalR ativo. A validação do lado do cliente não está disponível para formulários em componentes que adotaram renderização estática do lado do servidor (SSR estático). Os formulários que adotam SSR estático são validados no servidor após o envio do formulário.

• ASP.NET Core Blazor carregamento de ficheiros
• Blazor exemplos de repositório GitHub (dotnet/blazor-samples) (como fazer o download)
• ASP.NET repositório GitHub principal (dotnet/aspnetcore) forma ativos de teste

• Upload de ficheiros ASP.NET Core Blazor
• Proteja um aplicativo ASP.NET Core Blazor WebAssembly hospedado com o Microsoft Entra ID
• Proteja um aplicativo ASP.NET Core Blazor WebAssembly hospedado com o Azure Ative Directory B2C
• Proteja um aplicativo ASP.NET Core Blazor WebAssembly hospedado com o Identity Server
• Blazor exemplos de repositório GitHub (dotnet/blazor-samples) (como fazer o download)
• Repositório do GitHub do ASP.NET Core (dotnet/aspnetcore) contém recursos de teste