ASP.NET Core Blazor 양식 개요

이 문서에서는 .에서 양식을 사용하는 방법을 설명합니다 Blazor.

입력 구성 요소 및 양식

Blazor 프레임워크는 양식을 지원하고 기본 제공 입력 구성 요소를 제공합니다.

• 데이터 주석을 사용할 수 있는 개체 또는 모델에 바인딩됩니다.
  • 요소가 있는 HTML 양식입니다 <form> .
  • EditForm 구성 요소.
• 기본 제공 입력 구성 요소입니다.

참고 항목

지원되지 않는 ASP.NET Core 유효성 검사 기능은 지원되지 않는 유효성 검사 기능 섹션에서 다룹니다.

Microsoft.AspNetCore.Components.Forms 네임스페이스는 다음을 제공합니다.

• 양식 요소, 상태 및 유효성 검사를 관리하기 위한 클래스
• 기본 제공 구성 요소에 Input* 대한 액세스

프로젝트 템플릿에서 Blazor 만든 프로젝트에는 앱의 _Imports.razor 파일에 네임스페이스가 포함되어 있어 앱의 Razor 구성 요소에서 네임스페이스를 사용할 수 있습니다.

표준 HTML 양식이 지원됩니다. 일반 HTML <form> 태그를 사용하여 양식을 만들고 제출된 양식 요청을 처리하기 위한 처리기를 지정 @onsubmit 합니다.

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

위의 StarshipPlainForm 구성 요소에서:

• 요소가 나타나는 위치에 폼이 <form> 렌더링됩니다. 양식의 이름은 프레임워크에 대한 @formname 폼을 고유하게 식별하는 지시문 특성으로 Blazor 지정됩니다.
• 모델은 구성 요소의 @code 블록에서 만들어지고 공용 속성(Model)에 보관됩니다. 특성은 [SupplyParameterFromForm] 연결된 속성의 값을 양식 데이터에서 제공해야 임을 나타냅니다. 속성 이름과 일치하는 요청의 데이터는 속성에 바인딩됩니다.
• InputText 구성 요소는 문자열 값을 편집하기 위한 입력 구성 요소입니다. @bind-Value 지시문 특성은 Model.Id 모델 속성을 InputText 구성 요소의 Value 속성에 바인딩합니다.
• 메서드는 Submit 콜백에 대한 @onsubmit 처리기로 등록됩니다. 사용자가 양식을 제출할 때 처리기가 호출됩니다.

Important

항상 고유한 양식 이름으로 지시문 특성을 사용합니다 @formname .

Blazor 는 기존 DOM에 응답을 적용하기 위해 요청을 가로채서 렌더링된 폼을 최대한 많이 유지하여 페이지 탐색 및 양식 처리를 향상시킵니다. 향상된 기능은 페이지를 완전히 로드할 필요가 없으며 구성 요소가 서버에 렌더링되더라도 SPA(단일 페이지 앱)와 유사하게 훨씬 더 부드러운 사용자 환경을 제공합니다. 자세한 내용은 ASP.NET Core Blazor 라우팅 및 탐색을 참조하세요.

스트리밍 렌더링 은 일반 HTML 양식에 대해 지원됩니다.

참고 항목

.NET 참조 원본의 설명서 링크는 일반적으로 다음 릴리스의 .NET을 위한 현재 개발을 나타내는 리포지토리의 기본 분기를 로드합니다. 특정 릴리스를 위한 태그를 선택하려면 Switch branches or tags(분기 또는 태그 전환) 드롭다운 목록을 사용합니다. 자세한 내용은 ASP.NET Core 소스 코드(dotnet/AspNetCore.Docs #26205)의 버전 태그를 선택하는 방법을 참조하세요.

앞의 예제에서는 폼에 구성 요소를 포함하여 AntiforgeryToken 위조 방지 지원을 포함합니다. 위조 방지 지원은 이 문서의 위조 방지 지원 섹션에서 자세히 설명합니다.

예를 들어 oninput onblur다른 요소의 DOM 이벤트를 기반으로 양식을 제출하려면 JavaScript를 사용하여 양식(submit MDN 설명서)을 제출합니다.

앱에서 Blazor 일반 양식을 사용하는 대신 양식은 일반적으로 프레임워크 EditForm 구성 요소를 사용하여 기본 제공 양식 지원으로 Blazor정의됩니다. 다음 Razor 구성 요소는 구성 요소를 사용하여 EditForm 웹 폼을 렌더링하는 일반적인 요소, 구성 요소 및 Razor 코드를 보여 줍니다.

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

위의 Starship1 구성 요소에서:

• EditForm 구성 요소는 <EditForm> 요소가 나타나는 곳에서 렌더링됩니다. 양식의 이름은 프레임워크에 대한 @formname 폼을 고유하게 식별하는 지시문 특성으로 Blazor 지정됩니다.
• 모델은 구성 요소의 @code 블록에서 만들어지고 공용 속성(Model)에 보관됩니다. 속성이 매개 변수에 EditForm.Model 할당됩니다. 특성은 [SupplyParameterFromForm] 연결된 속성의 값을 양식 데이터에서 제공해야 임을 나타냅니다. 속성 이름과 일치하는 요청의 데이터는 속성에 바인딩됩니다.
• InputText 구성 요소는 문자열 값을 편집하기 위한 입력 구성 요소입니다. @bind-Value 지시문 특성은 Model.Id 모델 속성을 InputText 구성 요소의 Value 속성에 바인딩합니다.
• Submit 메서드는 OnSubmit 콜백에 대한 처리기로 등록됩니다. 사용자가 양식을 제출할 때 처리기가 호출됩니다.

Important

항상 고유한 양식 이름으로 지시문 특성을 사용합니다 @formname .

Blazor 은 구성 요소에 대한 EditForm 페이지 탐색 및 양식 처리를 향상시킵니다. 자세한 내용은 ASP.NET Core Blazor 라우팅 및 탐색을 참조하세요.

스트리밍 렌더링 은 .에 대해 EditForm지원됩니다.

참고 항목

.NET 참조 원본의 설명서 링크는 일반적으로 다음 릴리스의 .NET을 위한 현재 개발을 나타내는 리포지토리의 기본 분기를 로드합니다. 특정 릴리스를 위한 태그를 선택하려면 Switch branches or tags(분기 또는 태그 전환) 드롭다운 목록을 사용합니다. 자세한 내용은 ASP.NET Core 소스 코드(dotnet/AspNetCore.Docs #26205)의 버전 태그를 선택하는 방법을 참조하세요.

† 속성 바인딩에 대한 자세한 내용은 ASP.NET Core Blazor 데이터 바인딩을 참조하세요.

다음 예제에서는 이전 구성 요소가 구성 요소에 Starship2 폼을 만들도록 수정됩니다.

• OnSubmit 는 사용자가 제출할 때 양식이 유효한 경우 할당된 이벤트 처리기를 처리하는 OnValidSubmit로 대체됩니다.
• 양식 제출 시 양식이 유효하지 않은 경우 유효성 검사 메시지를 표시하기 위해 ValidationSummary 구성 요소가 추가됩니다.
• 데이터 주석 유효성 검사기(DataAnnotationsValidator 구성 요소†)는 데이터 주석을 사용하여 유효성 검사 지원을 연결합니다.
  • Submit 단추를 선택할 때 <input> 양식 필드가 비어 있으면 유효성 검사 요약(ValidationSummary 구성 요소‡)(“The Id field is required.”)에 오류가 표시되고 Submit이 호출되지 않습니다.
  • <input> 단추를 선택할 때 Submit 양식 필드에 10자 이상이 포함된 경우 유효성 검사 요약(""Id is too long.)에 오류가 나타납니다. Submit 가 호출되지 않았습니다 .
  • Submit 단추를 선택할 때 <input> 양식 필드에 유효한 값이 포함되면 Submit이 호출됩니다.

†DataAnnotationsValidator 구성 요소가 유효성 검사기 구성 요소 섹션에서 검사됩니다. ‡ValidationSummary 구성 요소가 유효성 검사 요약 및 유효성 검사 메시지 구성 요소 섹션에서 검사됩니다.

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

양식 제출 처리

EditForm은 양식 제출을 처리하기 위해 다음 콜백을 제공합니다.

• OnValidSubmit은 유효한 필드가 있는 양식이 제출될 때 실행할 이벤트 처리기를 할당하는 데 사용합니다.
• OnInvalidSubmit은 유효하지 않은 필드가 있는 양식이 제출될 때 실행할 이벤트 처리기를 할당하는 데 사용합니다.
• OnSubmit은 양식 필드의 유효성 검사 상태와 관계없이 실행할 이벤트 처리기를 할당하는 데 사용합니다. 이벤트 처리기 메서드에서 EditContext.Validate을 호출하여 양식의 유효성을 검사합니다. Validate가 true를 반환하면 양식이 유효한 것입니다.

폼 또는 필드 지우기

모델에서 기본 상태를 다시 지워 폼을 다시 설정합니다. 이 상태는 '태그 내부 EditForm또는 외부에서 수행할 수 있습니다.

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

...

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

또는 명시적 Razor 식을 사용합니다.

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

모델 값을 기본 상태로 다시 지워 필드를 다시 설정합니다.

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

...

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

또는 명시적 Razor 식을 사용합니다.

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

이벤트 처리기가 호출된 후 구성 요소를 다시 렌더링하기 위해 프레임워크에서 자동으로 호출 Blazor 되므로 이전 예제 StateHasChanged 에서는 호출 StateHasChanged 할 필요가 없습니다. 이벤트 처리기를 사용하여 폼이나 필드를 지우는 메서드를 호출하지 않는 경우 개발자 코드는 구성 요소를 다시 렌더링하기 위해 호출 StateHasChanged 해야 합니다.

위조 방지 지원

위조 방지 서비스는 파일에서 호출되면 앱 AddRazorComponents 에 Program 자동으로 추가 Blazor 됩니다.

앱은 파일의 요청 처리 파이프라인에서 호출 UseAntiforgery 하여 위조 방지 미들웨어를 Program 사용합니다. UseAntiforgery 는 호출 후 호출됩니다 UseRouting. 호출 UseRouting UseEndpoints이 있는 경우 호출은 해당 호출 UseAntiforgery 간에 이동해야 합니다. 호출 후 UseAntiforgery 호출해야 UseAuthentication 합니다.UseAuthorization

구성 AntiforgeryToken 요소는 위조 방지 토큰을 숨겨진 필드로 렌더링하고 특성은 [RequireAntiforgeryToken] 위조 방지 보호를 사용하도록 설정합니다. 위조 방지 검사가 실패 400 - Bad Request 하면 응답이 throw되고 양식이 처리되지 않습니다.

기반 EditForm양식의 AntiforgeryToken 경우 구성 요소 및 [RequireAntiforgeryToken] 특성이 자동으로 추가되어 위조 방지 보호를 제공합니다.

HTML <form> 요소를 기반으로 하는 양식의 경우 구성 요소를 양식에 AntiforgeryToken 수동으로 추가합니다.

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

Warning

HTML EditForm 요소 또는 HTML <form> 요소를 기반으로 하는 양식의 경우 특성에 전달 required: false [RequireAntiforgeryToken] 하여 위조 방지 보호를 사용하지 않도록 설정할 수 있습니다. 다음 예제에서는 위조 방지를 사용하지 않도록 설정하며 공용 앱에는 권장 되지 않습니다.

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

자세한 내용은 ASP.NET Core Blazor 인증 및 권한 부여를 참조하세요.

오버포스트 공격 완화

양식 모델을 사용하여 데이터베이스에서 레코드를 만들고 편집하는 구성 요소에서 일반적으로 사용되는 것과 같이 정적으로 렌더링된 서버 쪽 양식은 대량 할당 공격이라고도 하는 오버포스트 공격에 취약할 수 있습니다. 악의적인 사용자가 렌더링된 양식의 일부가 아닌 속성에 대한 데이터를 처리하는 서버에 HTML 양식 POST를 발급하고 개발자가 사용자가 수정하도록 허용하지 않으려는 경우 오버포스트 공격이 발생합니다. "overposting"이라는 용어는 말 그대로 악의적인 사용자가 양식에 과도하게 POSTed되었음을 의미합니다.

모델에 만들기 및 업데이트 작업에 대한 제한된 속성이 포함되지 않은 경우 오버포스트는 문제가 되지 않습니다. 그러나 유지 관리하는 정적 SSR 기반 Blazor 양식을 사용할 때는 오버포스트를 염두에 두어야 합니다.

오버포스트를 완화하려면 만들기(삽입) 및 업데이트 작업을 사용하여 폼 및 데이터베이스에 별도의 뷰 DTO(모델/데이터 전송 개체)를 사용하는 것이 좋습니다. 양식을 제출하면 뷰 모델/DTO의 속성만 구성 요소와 C# 코드에서 데이터베이스를 수정하는 데 사용됩니다. 악의적인 사용자가 포함하는 추가 데이터는 삭제되므로 악의적인 사용자가 오버포스트 공격을 수행할 수 없습니다.

향상된 양식 처리

양식에 대한 매개 변수 EditForm 또는 data-enhance HTML 양식의 특성(<form>)을 Enhance 사용하여 양식 POST 요청에 대한 탐색을 향상시킵니다.

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

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

❌지원되지 않음: 양식의 상위 요소에 대해 향상된 탐색을 설정하여 향상된 양식 처리를 사용하도록 설정할 수 없습니다.

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

향상된 양식 게시물은 엔드포인트에서 Blazor 만 작동합니다. 향상된 양식을 비 엔드Blazor 포인트에 게시하면 오류가 발생합니다.

향상된 양식 처리를 사용하지 않도록 설정하려면 다음을 수행합니다.

• 의 EditForm경우 폼 요소에서 매개 변수를 제거 Enhance 하거나 다음Enhance="false"으로 false설정합니다.
• HTML<form>의 경우 양식 요소에서 특성을 제거 data-enhance 하거나 다음data-enhance="false"으로 false설정합니다.

Blazor업데이트된 콘텐츠가 서버 렌더링의 일부가 아닌 경우 향상된 탐색 및 양식 전달을 통해 DOM에 대한 동적 변경 내용을 실행 취소할 수 있습니다. 요소의 콘텐츠를 유지하려면 특성을 사용합니다 data-permanent .

다음 예제에서는 페이지가 로드되면 요소의 <div> 콘텐츠가 스크립트에 의해 동적으로 업데이트됩니다.

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

향상된 탐색 및 양식 처리를 전역적으로 사용하지 않도록 설정하려면 ASP.NET Core Blazor 시작을 참조하세요.

이벤트를 사용하여 enhancedload 향상된 페이지 업데이트를 수신 대기하는 방법에 대한 지침은 ASP.NET Core Blazor 라우팅 및 탐색을 참조하세요.

예제

예제에서는 양식 POST 요청에 대해 향상된 양식 처리를 채택하지 않지만 향상된 양식 처리 섹션의 지침 에 따라 향상된 기능을 채택하도록 모든 예제를 업데이트할 수 있습니다.

양식이 데이터 주석 유효성 검사와 함께 작동하는 방식을 보여 주려면 예제 구성 요소는 API를 사용합니다System.ComponentModel.DataAnnotations. 데이터 주석을 사용하는 구성 요소에서 추가 코드 줄을 사용하지 않으려는 경우 가져오기 파일(_Imports.razor)을 사용하여 앱의 구성 요소 전체에서 네임스페이스를 사용할 수 있도록 합니다.

@using System.ComponentModel.DataAnnotations

양식 예제는 스타 트렉 우주의 측면을 참조합니다. 스타 트렉은 CBS 스튜디오와 파라마운트의 저작권 ©1966-2023입니다.

클라이언트 쪽 유효성 검사에는 회로가 필요합니다.

즉 Blazor Web App, 클라이언트 쪽 유효성 검사에는 활성 BlazorSignalR 회로가 필요합니다. 정적 서버 쪽 렌더링(정적 SSR)을 채택한 구성 요소의 양식에는 클라이언트 쪽 유효성 검사를 사용할 수 없습니다. 정적 SSR을 채택하는 양식은 양식이 제출된 후 서버에서 유효성을 검사합니다.

지원되지 않는 유효성 검사 기능

유효성 검사 특성을 제외한[Remote] 모든 데이터 주석 기본 제공 유효성 검사기가 지원 Blazor 됩니다.

jQuery 유효성 검사는 구성 요소에서 Razor 지원되지 않습니다. 다음 방법 중 어느 것이든 권장됩니다.

• ASP.NET Core Blazor 양식 유효성 검사의 지침을 따릅니다.
  • 대화형 렌더링 모드를 Blazor Web App 채택하는 서버 쪽 유효성 검사입니다.
  • 독립 실행형 Blazor 웹 어셈블리 앱의 클라이언트 쪽 유효성 검사입니다.
• 네이티브 HTML 유효성 검사 특성을 사용합니다( MDN 설명서(클라이언트 쪽 양식 유효성 검사 참조).
• 타사 유효성 검사 JavaScript 라이브러리를 채택합니다.

서버에서 정적으로 렌더링된 양식의 경우 2025년 말에 .NET 10에 대해 클라이언트 쪽 유효성 검사를 위한 새로운 메커니즘을 고려 중입니다. 자세한 내용은 회로 없이 클라이언트 유효성 검사를 사용하여 Blazor 서버 렌더링 양식 만들기(dotnet/aspnetcore #51040)를 참조하세요.

추가 리소스

• ASP.NET Core Blazor 파일 업로드
• Blazor샘플 GitHub 리포지토리()(dotnet/blazor-samples다운로드 방법)
• ASP.NET Core GitHub 리포지토리()는dotnet/aspnetcore 테스트 자산을 형성합니다.