다음을 통해 공유

ASP.NET Core Blazor 기본 사항

  • 아티클

참고 항목

이 문서의 최신 버전은 아닙니다. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Warning

이 버전의 ASP.NET Core는 더 이상 지원되지 않습니다. 자세한 내용은 .NET 및 .NET Core 지원 정책을 참조 하세요. 현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

Important

이 정보는 상업적으로 출시되기 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적, 또는 묵시적인 보증을 하지 않습니다.

현재 릴리스는 이 문서의 .NET 9 버전을 참조 하세요.

기본 사항 문서는 기본 Blazor 개념에 대한 지침을 제공합니다. 일부 개념은 Razor 구성 요소에 대한 기본적인 이해와 연관되어 있으며, 이 문서의 다음 섹션과 구성 요소 문서에서 자세히 설명합니다.

정적 및 대화형 렌더링 개념

Razor 구성 요소는 정적으로 렌더링되거나 대화형으로 렌더링됩니다.

정적 또는 정적 렌더링 은 구성 요소가 사용자와 .NET/C# 코드 간의 상호 작용 용량 없이 렌더링됨을 의미하는 서버 쪽 시나리오입니다. JavaScript 및 HTML DOM 이벤트는 영향을 받지 않지만 서버에서 실행되는 .NET을 사용하여 클라이언트의 사용자 이벤트를 처리할 수 없습니다.

대화형 또는 대화형 렌더링 은 구성 요소에 C# 코드를 통해 .NET 이벤트를 처리할 수 있는 용량이 있음을 의미합니다. .NET 이벤트는 ASP.NET Core 런타임 또는 WebAssembly 기반 Blazor 런타임에 의해 클라이언트의 브라우저에서 서버에서 처리됩니다.

Important

사용 시 Blazor Web App대부분의 설명서 예제 구성 요소에는 상호 작용이 필요하며 문서에서 다루는 개념을 보여 Blazor 줍니다. 아티클에서 제공하는 예제 구성 요소를 테스트할 때 앱이 전역 대화형 대화형 작업을 채택하거나 구성 요소가 대화형 렌더링 모드를 채택하는지 확인합니다.

이러한 개념 및 정적 및 대화형 렌더링을 제어하는 방법에 대한 자세한 내용은 설명서의 뒷 Blazor 부분에 있는 ASP.NET Core Blazor 렌더링 모드 문서에서 확인할 수 있습니다.

클라이언트 및 서버 렌더링 개념

설명서 전체에서 Blazor 사용자 시스템에서 발생하는 작업은 클라이언트 또는 클라이언트 쪽에서 발생한다고 합니다. 서버에서 발생하는 작업은 서버 또는 서버 쪽에서 발생한다고 합니다.

렌더링이라는 용어는 브라우저에서 표시하는 HTML 태그를 생성하는 것을 의미합니다.

  • CSR(클라이언트 쪽 렌더링) 은 클라이언트의 .NET WebAssembly 런타임에 의해 최종 HTML 태그가 생성됨을 의미합니다. 앱의 클라이언트 생성 UI에 대한 HTML은 이 유형의 렌더링을 위해 서버에서 클라이언트로 전송되지 않습니다. 페이지와의 사용자 대화형 작업이 가정됩니다. 정적 클라이언트 쪽 렌더링과 같은 개념은 없습니다. CSR은 대화형으로 간주되므로 "대화형 클라이언트 쪽 렌더링" 및 "대화형 CSR"은 업계 또는 설명서에서 Blazor 사용되지 않습니다.

  • SSR(서버 쪽 렌더링) 은 최종 HTML 태그가 서버의 ASP.NET Core 런타임에 의해 생성됨을 의미합니다. HTML은 클라이언트의 브라우저에서 표시하기 위해 네트워크를 통해 클라이언트로 전송됩니다. 이 유형의 렌더링을 위해 클라이언트가 앱의 서버 생성 UI에 대한 HTML을 만들지 않습니다. SSR은 다음 두 가지 종류일 수 있습니다.

    • 정적 SSR: 서버는 사용자 대화형 작업 또는 구성 요소 상태 유지 관리를 제공하지 않는 정적 HTML을 Razor 생성합니다.
    • 대화형 SSR: Blazor 이벤트는 사용자 대화형 작업을 허용하고 Razor 구성 요소 상태는 프레임워크에서 Blazor 유지 관리됩니다.

  • 미리 렌더링 은 렌더링된 컨트롤에 대한 이벤트 처리기를 사용하도록 설정하지 않고 서버에서 페이지 콘텐츠를 처음 렌더링하는 프로세스입니다. 서버는 초기 요청에 대한 응답으로 가능한 한 빨리 페이지의 HTML UI를 출력하므로 앱이 사용자에게 더 반응할 수 있습니다. 사전 렌더링은 검색 엔진이 페이지 순위를 계산하는 데 사용하는 초기 HTTP 응답에 대한 콘텐츠를 렌더링하여 SEO(검색 엔진 최적화)를 향상시킬 수도 있습니다. 미리 렌더링 뒤에는 항상 서버 또는 클라이언트에서 최종 렌더링이 수행됩니다.

Razor 구성 요소

Blazor 앱은 Razor 구성 요소를 기반으로 하며, 이를 구성 요소라고 하는 경우가 많습니다. 구성 요소는 페이지, 대화 상자 또는 데이터 입력 양식과 같은 UI의 요소입니다. 구성 요소는 .NET 어셈블리에 기본 제공되는 .NET C# 클래스입니다.

Razor는 일반적으로 클라이언트 측 UI 논리 및 컴퍼지션에 대한 Razor 표시 페이지의 형태로 구성 요소가 작성되는 방법을 의미합니다. Razor는 개발자 생산성을 위해 설계된 HTML 태그와 C# 코드를 결합하는 구문입니다. Razor 파일은 .razor 파일 이름 확장명을 사용합니다.

일부 Blazor 개발자와 온라인 리소스는 "Blazor 구성 요소"라는 용어를 사용하지만 문서에서는 해당 용어를 피하고 일반적으로 "Razor 구성 요소" 또는 "구성 요소"를 사용합니다.

Blazor 문서는 구성 요소를 표시하고 논의하기 위한 몇 가지 규칙을 채택합니다.

  • 일반적으로 예제는 ASP.NET Core/C# 코딩 규칙 및 엔지니어링 지침을 준수합니다. 자세한 내용은 다음 리소스를 참조하세요.
  • 프로젝트 코드, 파일 경로 및 이름, 프로젝트 템플릿 이름 및 기타 특수 용어는 미국 영어이며, 일반적으로 코드 펜스로 구분됩니다.
  • 구성 요소는 일반적으로 C# 클래스 이름(파스칼식 대/소문자) 뒤에 "component"라는 단어로 참조됩니다. 예를 들어 일반적인 파일 업로드 구성 요소를 "FileUpload component"라고 합니다.
  • 대체로 구성 요소의 C# 클래스 이름은 파일 이름과 동일합니다.
  • 라우팅 가능한 구성 요소는 일반적으로 상대 URL을 kebab-case에서 구성 요소의 클래스 이름으로 설정합니다. 예를 들어 FileUpload 구성 요소에는 상대 URL /file-upload에서 렌더링된 구성 요소에 도달하기 위한 라우팅 구성이 포함됩니다. 라우팅 및 탐색은 ASP.NET Core Blazor 라우팅 및 탐색에서 다룹니다.
  • 구성 요소의 여러 버전을 사용하는 경우 순차적으로 번호가 매겨집니다. 예를 들어 FileUpload3 구성 요소는 .에 /file-upload-3도달합니다.
  • Razor 구성 요소 정의(.razor file)의 맨 위에 있는 지시문은 , @page@rendermode (.NET 8 이상), @using 문, 기타 지시문을 사전순으로 정렬합니다.
  • 멤버에는 private 필요하지 않지만 액세스 한정자는 문서 예제 및 샘플 앱에서 사용됩니다. 예를 들어 private는 maxAllowedFiles 필드를 private int maxAllowedFiles = 3;으로 선언하기 위해 명시되어 있습니다.
  • 구성 요소 매개 변수 값은 예약된 @ 기호로 Razor 이어지지만 필수는 아닙니다. 리터럴(예: 부울 값), 키워드(예 this: 키워드) 및 null 구성 요소 매개 변수 값의 접두사는 @포함되지 않지만 이는 설명서 규칙일 뿐입니다. 원하는 경우 사용자 고유의 코드에서 리터럴 접두사를 지정할 @ 수 있습니다.
  • C# 클래스는 키워드를this 사용하고 ASP.NET Core 프레임워크 엔지니어링 지침과 다른 생성자에 할당된 밑줄(_)이 있는 접두사를 사용하지 않습니다.
  • 기본 생성자(C# 12 이상)를 사용하는 예제에서 기본 생성자 매개 변수는 일반적으로 클래스 멤버에서 직접 사용됩니다.

구성 요소 구문에 대한 Razor 추가 정보는 ASP.NET Core Razor 구성 요소의 구문 섹션에서 제공됩니다Razor.

다음은 예제 카운터 구성 요소이며 Blazor 프로젝트 템플릿에서 만든 앱의 일부입니다. 자세한 구성 요소 관련 설명은 문서 뒷부분에 있는 구성 요소 문서에서 찾을 수 있습니다. 다음 예제에서는 문서의 뒷부분에 있는 구성 요소 문서에 도달하기 전에 기본 사항 문서에 있는 구성 요소 개념을 보여줍니다.

Counter.razor:

구성 요소는 대화형 렌더링 모드가 부모 구성 요소에서 상속되거나 앱에 전역적으로 적용된다고 가정합니다.

@page "/counter"

<PageTitle>Counter</PageTitle>

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

구성 요소는 대화형 렌더링 모드가 부모 구성 요소에서 상속되거나 앱에 전역적으로 적용된다고 가정합니다.

@page "/counter"

<PageTitle>Counter</PageTitle>

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

@page "/counter"

<PageTitle>Counter</PageTitle>

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

@page "/counter"

<PageTitle>Counter</PageTitle>

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

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}

앞선 Counter 구성 요소:

  • 첫 번째 줄에 @page 지시문을 사용하여 경로를 설정합니다.
  • 페이지 제목을 설정합니다.
  • @currentCount를 사용하여 현재 수를 렌더링합니다. currentCount는 @code 블록의 C# 코드에 정의된 정수 변수입니다.
  • @code 블록에 있고 currentCount 변수 값을 높이는 IncrementCount 트리거 단추를 표시합니다.

렌더링 모드

기본 사항 노드의 문서는 렌더링 모드의 개념을 참조합니다. 이 주체는 아티클의 기본 노드 뒤 나타나는 구성 요소 노드의 ASP.NET Core Blazor 렌더링 모드 문서에서 자세히 설명합니다.

이 문서 노드의 초기 참조에서 모드 개념을 렌더링하려면 이 시점에서 다음 사항에 유의하기만 하면 됩니다.

렌더링 모드의 Blazor Web App 모든 구성 요소는 렌더링 모드를 채택하여 사용하는 호스팅 모델, 렌더링되는 위치 및 서버에서 정적으로 렌더링되는지, 서버에서 사용자 대화형 작업을 위해 렌더링되는지, 클라이언트에서 사용자 대화형 작업을 위해 렌더링되는지(일반적으로 서버에서 미리 렌더링됨) 여부를 결정합니다.

Blazor Server.Blazor WebAssemblyNET 8 이전의 ASP.NET Core 릴리스용 앱은 렌더링 모드가 아닌 호스팅 모델 개념에 고정되어 있습니다. 렌더링 모드는 .NET 8 이상에서 개념적으로 적용 Blazor Web App됩니다.

다음 표에서는 구성 요소를 렌더링하는 데 사용할 수 있는 렌더링 모드를 Razor 보여 Blazor Web App줍니다. 렌더링 모드는 구성 요소 인스턴스 또는 구성 요소 정의에 @rendermode 대한 지시문을 사용하여 구성 요소에 적용됩니다. 전체 앱에 대한 렌더링 모드를 설정할 수도 있습니다.

속성 설명 렌더링 위치 대화형
정적 서버 정적 서버 쪽 렌더링(정적 SSR) 서버
대화형 서버 를 사용한 대화형 서버 쪽 렌더링(대화형 SSR) Blazor Server 서버
Interactive WebAssembly † 사용하는 Blazor WebAssemblyCSR(클라이언트 쪽 렌더링) 클라이언트
대화형 자동 번들이 다운로드된 후 후속 방문 시 처음 및 CSR을 Blazor 사용하는 Blazor Server 대화형 SSR 서버, 클라이언트

†CSR(Client side rendering)은 대화형으로 간주됩니다. "대화형 클라이언트 쪽 렌더링" 및 "대화형 CSR"은 업계 또는 설명서에서 Blazor 사용되지 않습니다.

렌더링 모드에 대한 이전 정보는 기본 사항 노드 문서를 이해하기 위해 알아야 할 사항입니다. 목차를 순서대로 읽고 있는 경우 Blazor Blazor 구성 요소 노드의 ASP.NET Core Blazor 렌더링 모드 문서에 도달할 때까지 렌더링 모드에 대한 자세한 정보 사용이 지연될 수 있습니다.

DOM(문서 개체 모델)

문서 개체 모델에 대한 참조는 약어 DOM을 사용합니다.

자세한 내용은 다음 리소스를 참조하세요.

앱용 Blazor WebAssembly .NET API의 하위 집합

브라우저 Blazor WebAssembly 에서 지원되는 특정 .NET API의 큐레이팅된 목록은 사용할 수 없습니다. 그러나 주석이 추가된 [UnsupportedOSPlatform("browser")] .NET API 목록을 수동으로 검색하여 WebAssembly에서 지원되지 않는 .NET API를 검색할 수 있습니다.

참고 항목

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

자세한 내용은 다음 리소스를 참조하세요.

샘플 앱

문서 샘플 앱은 검사와 다운로드에 사용할 수 있습니다.

Blazor 샘플 LibMan GitHub 리포지토리(dotnet/blazor-samples)

작업 중인 .NET 버전과 일치하는 버전 폴더를 먼저 선택하여 샘플 앱을 찾습니다.

리포지토리의 샘플 앱:

샘플 리포지토리에는 다음 두 가지 유형의 샘플이 포함되어 있습니다.

  • 코드 조각 샘플 앱은 문서에 표시되는 코드 예제를 제공합니다. 이러한 앱은 컴파일되지만 반드시 실행 가능한 앱은 아닙니다. 이러한 앱은 문서에 표시되는 예제 코드만 가져오는 데 유용합니다.
  • 다음과 같은 시나리오에 Blazor 대해 문서를 컴파일하고 실행할 앱을 샘플링합니다.
    • Blazor Server(EF Core 사용)
    • SignalR 사용 Blazor Server 및 Blazor WebAssembly
    • Blazor WebAssembly 범위 적용 로깅

자세한 내용과 리포지토리의 샘플 목록은 GitHub 리포지토리 README.md 파일 샘플을 참조 Blazor 하세요.

ASP.NET Core 리포지토리의 기본 테스트 앱은 다양한 Blazor 시나리오에 유용한 샘플 집합이기도 합니다.

ASP.NET Core 참조 원본의 BasicTestApp(dotnet/aspnetcore)

참고 항목

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

샘플 앱을 다운로드하려면 다음을 수행합니다.

바이트 배수

.NET 바이트 크기는 1024의 파워에 따라 10진수가 아닌 바이트 배수에 메트릭 접두사를 사용합니다.

이름(약어) 크기 예시
킬로바이트(KB) 1,024바이트 1KB = 1,024바이트
메가바이트(MB) 1,0242 바이트 1MB = 1,048,576바이트
기가바이트(GB) 1,0243 바이트 1GB = 1,073,741,824바이트

지원 요청

문서 관련 문제만 dotnet/AspNetCore.Docs 리포지토리에 적합합니다. 제품 지원의 경우 문서 문제를 열지 마세요.다음 지원 채널 중 하나 이상을 통해 지원을 요청하세요.

프레임워크 또는 제품 피드백의 잠재적인 버그의 경우 dotnet/aspnetcore 문제에서 ASP.NET Core 제품 단위에 대한 문제를 엽니다. 대체로 버그 보고서에는 다음이 필요합니다.

  • 문제에 대한 명확한 설명: 문제를 열 때 제품 단위에서 제공하는 GitHub 문제 템플릿의 지침을 따릅니다.
  • 최소 재현 프로젝트: 제품 단위 엔지니어가 다운로드 및 실행할 수 있도록 GitHub에 프로젝트를 배치합니다. 프로젝트를 문제의 열려 있는 설명에 교차 연결합니다.

Blazor 문서에 문제가 발생할 수 있는 경우 문서 문제를 엽니다. 설명서 문제를 열려면 문서 맨 아래에 있는 설명서 문제 열기 피드백 링크를 사용합니다. 문제에 추가된 메타데이터는 추적 데이터를 제공하고 문서의 작성자를 자동으로 ping합니다. 설명서 문제를 열기 전에 제품 단위와 주제가 논의된 경우 문서 문제의 오프닝 주석에 엔지니어링 문제에 대한 교차 링크를 배치합니다.

Visual Studio에서 문제 또는 피드백의 경우 Visual Studio 내에서 문제 보고 또는 기능 제스처를 제안하여 Visual Studio에 대한 내부 문제를 엽니다. 자세한 내용은 Visual Studio 피드백을 참조하세요.

Visual Studio Code 관련 문제는 커뮤니티 지원 포럼에서 지원을 요청하세요. 버그 신고 및 제품 피드백의 경우 microsoft/vscode GitHub 리포지토리에 대한 문제를 엽니다.

Blazor 문서에 대한 GitHub 문제는 Blazor.Docs 프로젝트(dotnet/AspNetCore.Docs GitHub 리포지토리)에서 자동으로 심사 표시됩니다. 특히 주말과 휴일에는 응답을 위해 잠시 기다려 주세요. 대체로 문서 작성자는 평일 24시간 이내에 응답합니다.

커뮤니티에서 유지 관리하는 Blazor 리소스에 대한 링크 모음은 Awesome Blazor를 방문하세요.

참고 항목

Microsoft는 Awesome Blazor와 여기에 설명 및 링크된 대부분의 커뮤니티 제품 및 서비스를 소유, 유지 관리 또는 지원하지 않습니다.