RCL(Razor 클래스 라이브러리)에서 ASP.NET Core Razor 구성 요소 사용

프로젝트 간에 RCL(Razor 클래스 라이브러리)의 구성 요소를 공유할 수 있습니다. 다음 위치에서 앱에 구성 요소 및 정적 자산을 포함합니다.

• 솔루션의 다른 프로젝트.
• 참조된 .NET 라이브러리
• NuGet 패키지

구성 요소가 일반적인 .NET 형식인 것처럼, RCL에서 제공하는 구성 요소는 일반적인 .NET 어셈블리입니다.

RCL 만들기

Visual Studio

1. 새 프로젝트를 만듭니다.
2. 새 프로젝트 만들기 대화 상자에서 ASP.NET Core 프로젝트 템플릿 목록으로부터 Razor클래스 라이브러리를 선택합니다. 다음을 선택합니다.
3. 새 프로젝트 구성 대화 상자의 프로젝트 이름 필드에 프로젝트 이름을 입력합니다. 이 항목의 예제에서는 프로젝트 이름으로 ComponentLibrary을 사용합니다. 다음을 선택합니다.
4. 추가 정보 대화 상자에서 지원 페이지 및 보기를 선택하지 마세요. 만들기를 실행합니다.
5. 솔루션에 RCL을 추가합니다.
   1. 솔루션을 엽니다.
   2. 솔루션 탐색기에서 솔루션을 마우스 오른쪽 단추로 클릭합니다. 추가>기존 프로젝트를 선택합니다.
   3. RCL의 프로젝트 파일로 이동합니다.
   4. RCL의 프로젝트 파일(.csproj)을 선택합니다.
6. 앱에서 RCL에 대한 참조를 추가합니다.
   1. 앱 프로젝트를 마우스 오른쪽 단추로 클릭합니다. 을 선택하고 >프로젝트를 추가하고 를 참고합니다.
   2. RCL 프로젝트를 선택합니다. 확인을 선택합니다.

Visual Studio Code / .NET CLI

1. 명령 셸에서 dotnet new 명령을 통해 Razor 클래스 라이브러리 프로젝트 템플릿(razorclasslib)을 사용합니다. 다음 예제에서는 -o|--output 옵션을 사용하여 이름이 ComponentLibrary인 RCL을 만듭니다. 명령을 실행하면 ComponentLibrary을 포함하는 폴더가 자동으로 생성됩니다.

   dotnet new razorclasslib -o ComponentLibrary
   

2. 기존 프로젝트에 라이브러리를 추가하려면 명령 셸에서 dotnet add reference 명령을 사용합니다. 다음 명령에서 {PATH TO LIBRARY}자리 표시자는 라이브러리의 프로젝트 폴더에 대한 경로입니다.

   dotnet add reference {PATH TO LIBRARY}
   

RCL에서 Razor구성 요소 이용

다른 프로젝트에서 RCL의 구성 요소를 이용하려면 다음 방법 중 하나를 사용합니다.

• RCL의 네임스페이스를 포함하는 전체 구성 요소 형식 이름을 사용합니다.
• Razor의 @using 지시문이 RCL의 네임스페이스를 선언하는 경우 RCL의 네임스페이스 없이 개별 구성 요소를 이름으로 추가할 수 있습니다. 다음 방법을 사용합니다.
  • 개별 구성 요소에 @using 지시문을 추가합니다.
  • 최상위 _Imports.razor 파일에 @using 지시문을 포함하여 전체 프로젝트에서 라이브러리 구성 요소를 사용할 수 있게 합니다. 임의 수준의 _Imports.razor 파일에 지시문을 추가하여 폴더 내의 단일 구성 요소 또는 구성 요소 집합에 네임스페이스를 적용합니다. _Imports.razor 파일이 사용되는 경우 개별 구성 요소에는 RCL의 네임스페이스에 대한 @using 지시문이 필요하지 않습니다.

다음 예제에서 ComponentLibrary는 Component1 구성 요소가 포함된 RCL입니다. Component1 구성 요소는 페이지 및 뷰를 지원하기 위해 생성되지 않은 RCL 프로젝트 템플릿에서 생성된 RCL에 자동으로 추가되는 예제 구성 요소입니다.

ComponentLibrary RCL 안의 Component1.razor:

<div class="my-component">
    This component is defined in the <strong>ComponentLibrary</strong> package.
</div>

RCL을 사용하는 앱에서 다음 예제와 같이 네임스페이스를 사용하여 Component1 구성 요소를 참조합니다.

ConsumeComponent1.razor:

@page "/consume-component-1"

<h1>Consume component (full namespace example)</h1>

<ComponentLibrary.Component1 />

또는 @using 지시문을 추가하고 네임스페이스 없이 구성 요소를 사용합니다. 다음 @using 지시문은 현재 폴더의 모든 _Imports.razor파일에 표시될 수도 있습니다.

ConsumeComponent2.razor:

@page "/consume-component-2"
@using ComponentLibrary

<h1>Consume component (<code>@@using</code> example)</h1>

<Component1 />

CSS 격리를 사용하는 라이브러리 구성 요소의 경우 사용하는 앱에서 구성 요소 스타일을 자동으로 사용할 수 있습니다. 라이브러리를 사용하는 앱에서 라이브러리의 개별 구성 요소 스타일시트 또는 번들로 제공된 CSS 파일을 수동으로 연결하거나 가져올 필요가 없습니다. 앱은 CSS 가져오기를 사용하여 RCL의 번들 스타일을 참조합니다. 번들 스타일은 라이브러리를 사용하는 앱의 정적 웹 자산으로 게시되지 않습니다. ClassLib라는 클래스 라이브러리와 BlazorSample.styles.css 스타일시트를 사용하는 Blazor 앱의 경우 빌드 타임에 RCL의 스타일시트를 자동으로 앱 스타일시트 맨 위로 가져옵니다.

@import '_content/ClassLib/ClassLib.bundle.scp.css';

앞의 예제에서는 Component1의 스타일시트(Component1.razor.css)가 자동으로 번들로 묶입니다.

ComponentLibrary RCL 안의 Component1.razor.css:

.my-component {
    border: 2px dashed red;
    padding: 1em;
    margin: 1em 0;
    background-image: url('background.png');
}

배경 이미지는 RCL 프로젝트 템플릿에 포함되며 RCL의 wwwroot폴더에 있습니다.

ComponentLibrary RCL 안의 wwwroot/background.png:

라이브러리 wwwroot 폴더의 스타일시트에서 추가 라이브러리 구성 요소 스타일을 제공하려면 다음 예제와 같이 RCL 소비자에 스타일시트 <link> 태그를 추가합니다.

Important

일반적으로 라이브러리 구성 요소는 CSS 격리를 사용하여 구성 요소 스타일을 번들로 묶고 제공합니다. CSS 격리를 사용하는 구성 요소 스타일은 RCL을 사용하는 앱에서 자동으로 제공됩니다. 라이브러리를 사용하는 앱에서 라이브러리의 개별 구성 요소 스타일시트 또는 번들로 제공된 CSS 파일을 수동으로 연결하거나 가져올 필요가 없습니다. 다음 예제는 일반적으로 RCL을 사용하는 일반적인 앱에 대한 요구 사항이 아닌 CSS 격리 외부에서 전역 스타일시트를 제공하는 것입니다.

다음 배경 이미지는 다음 예제에서 사용됩니다. 이 섹션에 표시된 예제를 구현하는 경우 이미지를 마우스 오른쪽 단추로 클릭하여 로컬로 저장합니다.

ComponentLibrary RCL 안의 wwwroot/extra-background.png:

extra-style 클래스를 사용하여 RCL에 새 스타일시트를 추가합니다.

ComponentLibrary RCL 안의 wwwroot/additionalStyles.css:

.extra-style {
    border: 2px dashed blue;
    padding: 1em;
    margin: 1em 0;
    background-image: url('extra-background.png');
}

extra-style 클래스를 사용하는 구성 요소를 RCL에 추가합니다.

ComponentLibrary RCL 안의 ExtraStyles.razor:

<div class="extra-style">
    <p>
        This component is defined in the <strong>ComponentLibrary</strong> package.
    </p>
</div>

RCL의 ExtraStyles 구성 요소를 사용하는 앱에 페이지를 추가합니다.

ConsumeComponent3.razor:

@page "/consume-component-3"
@using ComponentLibrary

<h1>Consume component (<code>additionalStyles.css</code> example)</h1>

<ExtraStyles />

앱의 태그(콘텐츠 위치<head>)에서 라이브러리의 <head> 스타일시트에 연결합니다.

<link href="_content/ComponentLibrary/additionalStyles.css" rel="stylesheet">

RCL에서 라우팅 가능한 구성 요소를 사용할 수 있도록 만들기

RCL의 라우팅 가능한 구성 요소를 직접 요청에 사용할 수 있도록 하려면 RCL의 어셈블리를 앱의 라우터에 공개해야 합니다.

앱의 App 구성 요소(App.razor)를 엽니다. Assembly RCL의 어셈블리를 AdditionalAssemblies 포함하도록 구성 요소의 Router 매개 변수에 컬렉션을 할당합니다. 다음 예제 ComponentLibrary.Component1 에서는 구성 요소를 사용하여 RCL의 어셈블리를 검색합니다.

AdditionalAssemblies="new[] { typeof(ComponentLibrary.Component1).Assembly }"

자세한 내용은 ASP.NET Core Blazor 라우팅 및 탐색을 참조하세요.

wwwroot 폴더에서 정적 자산을 사용하여 RCL 만들기

RCL의 정적 자산은 라이브러리를 사용하는 모든 앱에서 제공됩니다.

정적 자산을 RCL의 wwwroot 폴더에 넣고 앱에서 _content/{PACKAGE ID}/{PATH AND FILE NAME} 경로를 사용하 여 정적 자산을 참조합니다. {PACKAGE ID} 자리 표시자는 라이브러리의 패키지 ID입니다. <PackageId>가 프로젝트 파일에 지정되지 않은 경우 패키지 ID는 기본적으로 프로젝트의 어셈블리 이름으로 설정됩니다. {PATH AND FILE NAME} 자리 표시자는 wwwroot 아래의 경로 및 파일 이름입니다. 이 경로 형식은 RCL에 추가된 NuGet 패키지에서 제공하는 정적 자산에 대해서도 앱에서 사용됩니다.

다음 예제에서는 ComponentLibrary이라고 불리는 RCL로 RCL 정적 자산을 사용하는 것과 RCL을 사용하는 Blazor애플리케이션을 보여줍니다. 앱에는 ComponentLibrary RCL에 대한 프로젝트 참조가 있습니다.

다음 Jeep® 이미지는 이 섹션의 예제에서 사용됩니다. 이 섹션에 표시된 예제를 구현하는 경우 이미지를 마우스 오른쪽 단추로 클릭하여 로컬로 저장합니다.

ComponentLibrary RCL 안의 wwwroot/jeep-yj.png:

RCL에 다음 JeepYJ 구성 요소를 추가합니다.

ComponentLibrary RCL 안의 JeepYJ.razor:

<h3>ComponentLibrary.JeepYJ</h3>

<p>
    <img alt="Jeep YJ&reg;" src="_content/ComponentLibrary/jeep-yj.png" />
</p>

ComponentLibrary RCL을 사용하는 애플리케이션에 다음 Jeep구성 요소를 추가합니다. Jeep 구성 요소는 다음을 사용합니다.

• wwwroot RCL의 ComponentLibrary 폴더에 있는 Jeep YJ® 이미지입니다.
• RCL의 JeepYJ 구성 요소입니다.

Jeep.razor:

@page "/jeep"
@using ComponentLibrary

<div style="float:left;margin-right:10px">
    <h3>Direct use</h3>

    <p>
        <img alt="Jeep YJ&reg;" src="_content/ComponentLibrary/jeep-yj.png" />
    </p>
</div>

<JeepYJ />

<p>
    <em>Jeep</em> and <em>Jeep YJ</em> are registered trademarks of 
    <a href="https://www.stellantis.com">FCA US LLC (Stellantis NV)</a>.
</p>

렌더링된 Jeep 구성 요소:

자세한 내용은 ASP.NET Core를 사용하여 클래스 라이브러리에서 재사용 가능한 Razor UI를 참조하세요.

구성 요소와 함께 배치된 JavaScript 파일을 사용하여 RCL 만들기

구성 요소에 대한 Razor JavaScript(JS) 파일의 배치는 앱에서 스크립트를 구성하는 편리한 방법입니다.

Razor앱의 Blazor 구성 요소는 확장 프로그램을 .razor.js 사용하여 파일을 정렬 JS 하고 프로젝트의 파일 경로를 사용하여 공개적으로 주소를 지정합니다.

{PATH}/{COMPONENT}.razor.js

• {PATH} 자리 표시자는 구성 요소의 경로입니다.
• {COMPONENT} 자리 표시자가 구성 요소입니다.

앱이 게시되면 프레임워크는 자동으로 스크립트를 웹 루트로 이동합니다. 스크립트는 자리 표시자가 있는 위치로 이동 bin/Release/{TARGET FRAMEWORK MONIKER}/publish/wwwroot/{PATH}/{COMPONENT}.razor.js됩니다.

• {TARGET FRAMEWORK MONIKER} 는 TFM(대상 프레임워크 모니커)입니다.
• {PATH} 는 구성 요소의 경로입니다.
• {COMPONENT} 는 구성 요소 이름입니다.

게시된 정적 자산에 파일을 배치 JS 하기 때문에 Blazor 스크립트의 상대 URL을 변경할 필요가 없습니다.

이 섹션과 다음 예제는 주로 파일 배치를 설명하는 데 JS 중점을 줍니다. 첫 번째 예제에서는 일반 JS 함수를 사용하여 정렬된 JS 파일을 보여 줍니다. 두 번째 예제에서는 모듈을 사용하여 함수를 로드하는 방법을 보여 줍니다. 이 방법은 대부분의 프로덕션 앱에 권장되는 방법입니다. .NET에서의 호출 JS 은 ASP.NET CoreBlazor의 .NET 메서드에서 JavaScript 호출 함수에서 완전히 다룹니다. 여기서 추가 예제와 함께 API에 BlazorJS 대한 추가 설명이 있습니다. 두 번째 예제에 있는 구성 요소 삭제는 ASP.NET Core Razor 구성 요소 수명 주기에서 다룹니다.

다음 JsCollocation1 구성 요소는 구성 요소를 통해 스크립트를HeadContent 로드하고 다음을 사용하여 함수IJSRuntime.InvokeAsync를 JS 호출합니다. {PATH} 자리 표시자는 구성 요소의 경로입니다.

Important

테스트 앱에서 데모에 다음 코드를 사용하는 경우 자리 표시자를 구성 요소의 경로(예: Components/Pages .NET 8 이상 또는 Pages .NET 7 이하)로 변경 {PATH} 합니다. Blazor Web App (.NET 8 이상)에서 구성 요소에는 앱 또는 구성 요소 정의에 전역적으로 적용된 대화형 렌더링 모드가 필요합니다.

스크립트(시작 스크립트의 위치) 다음에 Blazor 다음 스크립트를 Blazor 추가합니다.

<script src="{PATH}/JsCollocation1.razor.js"></script>

JsCollocation1 구성 요소({PATH}/JsCollocation1.razor):

@page "/js-collocation-1"
@inject IJSRuntime JS

<PageTitle>JS Collocation 1</PageTitle>

<h1>JS Collocation Example 1</h1>

<button @onclick="ShowPrompt">Call showPrompt1</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private string? result;

    public async void ShowPrompt()
    {
        result = await JS.InvokeAsync<string>(
            "showPrompt1", "What's your name?");
        StateHasChanged();
    }
}

정렬된 JS 파일은 파일 이름을 JsCollocation1.razor.js가진 JsCollocation1 구성 요소 파일 옆에 배치됩니다. 구성 요소에서 JsCollocation1 스크립트는 데이터 정렬된 파일의 경로에서 참조됩니다. 다음 예제에서 함수는 showPrompt1 a Window prompt() 에서 사용자의 이름을 수락하고 표시할 구성 요소로 JsCollocation1 반환합니다.

{PATH}/JsCollocation1.razor.js:

function showPrompt1(message) {
  return prompt(message, 'Type your name here');
}

이 접근 방식은 클라이언트를 전역 함수로 오염하기 때문에 프로덕션 앱에서 일반적으로 사용하지 않는 것이 좋습니다. 프로덕션 앱에 대한 더 나은 방법은 모듈을 사용하는 JS 것입니다. 다음 예제와 같이 정렬된 JS 파일에서 모듈을 로드하는 JS 데도 동일한 일반적인 원칙이 적용됩니다.

다음 JsCollocation2 구성 요소의 OnAfterRenderAsync 메서드는 구성 요소 클래스의 모듈을 moduleIJSObjectReference 로드 JS 합니다. module 는 함수를 호출 showPrompt2 하는 데 사용됩니다. {PATH} 자리 표시자는 구성 요소의 경로입니다.

Important

테스트 앱에서 데모에 다음 코드를 사용하는 경우 자리 표시자를 구성 요소의 경로로 변경 {PATH} 합니다. Blazor Web App (.NET 8 이상)에서 구성 요소에는 앱 또는 구성 요소 정의에 전역적으로 적용된 대화형 렌더링 모드가 필요합니다.

JsCollocation2 구성 요소({PATH}/JsCollocation2.razor):

@page "/js-collocation-2"
@implements IAsyncDisposable
@inject IJSRuntime JS

<PageTitle>JS Collocation 2</PageTitle>

<h1>JS Collocation Example 2</h1>

<button @onclick="ShowPrompt">Call showPrompt2</button>

@if (!string.IsNullOrEmpty(result))
{
    <p>
        Hello @result!
    </p>
}

@code {
    private IJSObjectReference? module;
    private string? result;

    protected async override Task OnAfterRenderAsync(bool firstRender)
    {
        if (firstRender)
        {
            /*
                Change the {PATH} placeholder in the next line to the path of
                the collocated JS file in the app. Examples:

                ./Components/Pages/JsCollocation2.razor.js (.NET 8 or later)
                ./Pages/JsCollocation2.razor.js (.NET 7 or earlier)
            */
            module = await JS.InvokeAsync<IJSObjectReference>("import",
                "./{PATH}/JsCollocation2.razor.js");
        }
    }

    public async void ShowPrompt()
    {
        if (module is not null)
        {
            result = await module.InvokeAsync<string>(
                "showPrompt2", "What's your name?");
            StateHasChanged();
        }
    }

    async ValueTask IAsyncDisposable.DisposeAsync()
    {
        if (module is not null)
        {
            await module.DisposeAsync();
        }
    }
}

{PATH}/JsCollocation2.razor.js:

export function showPrompt2(message) {
  return prompt(message, 'Type your name here');
}

RCL(클래스 라이브러리)에서 배치할 JS 스크립트 및 모듈의 사용은 인터페이스를 기반으로 IJSRuntime 하는 Blazor'interop 메커니즘'JS에 대해서만 지원 Razor 됩니다. JavaScript[JSExport]/[JSImport] interop를 구현하는 경우 ASP.NET CoreBlazor와 JavaScript JSImport/JSExport interop를 참조하세요.

-based JS interop를 사용하여 IJSRuntimeRCL(클래스 라이브러리)에서 제공하는 Razor 스크립트 또는 모듈의 경우 다음 경로가 사용됩니다.

./_content/{PACKAGE ID}/{PATH}/{COMPONENT}.{EXTENSION}.js

• JS 파일의 올바른 정적 자산 경로를 만들려면 현재 디렉터리의 패스 세그먼트(./)가 필요합니다.
• {PACKAGE ID} 자리 표시자는 RCL의 패키지 식별자(또는 앱에서 참조하는 클래스 라이브러리의 라이브러리 이름)입니다.
• {PATH} 자리 표시자는 구성 요소의 경로입니다. Razor 구성 요소가 RCL의 루트에 있으면 경로 세그먼트가 포함되지 않습니다.
• {COMPONENT} 자리 표시자는 구성 요소 이름입니다.
• {EXTENSION} 자리 표시자는 구성 요소 razor 의 확장과 일치합니다cshtml.

다음 Blazor 앱 예제에서:

• RCL의 패키지 식별자는 AppJS입니다.
• 모듈의 스크립트는 JsCollocation3 구성 요소(JsCollocation3.razor)에 대해 로드됩니다.
• JsCollocation3 구성 요소는 RCL의 Components/Pages 폴더에 있습니다.

module = await JS.InvokeAsync<IJSObjectReference>("import", 
    "./_content/AppJS/Components/Pages/JsCollocation3.razor.js");

클라이언트 쪽 브라우저 호환성 분석기

클라이언트 쪽 앱은 전체 .NET API 노출 영역을 대상으로 하지만 브라우저 샌드박스 제약 조건으로 인해 WebAssembly에서 모든 .NET API가 지원되지는 않습니다. 지원되지 않는 API는 WebAssembly에서 실행될 때 PlatformNotSupportedException을 throw합니다. 플랫폼 호환성 분석기는 앱이 앱의 대상 플랫폼에서 지원하지 않는 API를 사용하는 경우 개발자에게 경고합니다. 클라이언트 쪽 앱의 경우 이는 API가 브라우저에서 지원되는지 확인하는 것을 의미합니다. 호환성 분석기용 .NET Framework API에 주석 달기는 지속적인 프로세스이므로 일부 .NET Framework API에는 현재 주석이 달려 있지 않습니다.

Blazor Web App대화형 WebAssembly 구성 요소, Blazor WebAssembly 앱 및 RCL 프로젝트를 사용하도록 설정하면 MSBuild 항목에서 지원되는 플랫폼 SupportedPlatform 으로 추가하여 browser 브라우저 호환성 검사를 자동으로 사용하도록 설정합니다. 라이브러리 개발자는 라이브러리의 프로젝트 파일에 SupportedPlatform 항목을 수동으로 추가하여 기능을 사용하도록 설정할 수 있습니다.

<ItemGroup>
  <SupportedPlatform Include="browser" />
</ItemGroup>

라이브러리를 작성할 때 browser를 UnsupportedOSPlatformAttribute로 지정하여 특정 API가 브라우저에서 지원되지 않음을 나타냅니다.

using System.Runtime.Versioning;

...

[UnsupportedOSPlatform("browser")]
private static string GetLoggingDirectory()
{
    ...
}

자세한 내용은 특정 플랫폼에서 지원되지 않는 API 주석 지정(GitHub 리포지토리)dotnet/designs 을 참조하세요.

JavaScript 모듈에서의 JavaScript 격리

Blazor에서는 표준 JavaScript 모듈에서 JavaScript 격리를 사용하도록 설정합니다. JavaScript 격리는 다음과 같은 이점을 제공합니다.

• 가져온 JavaScript는 전역 네임스페이스를 더 이상 오염시키지 않습니다.
• 라이브러리 및 구성 요소의 소비자는 관련 JavaScript를 수동으로 가져올 필요가 없습니다.

자세한 내용은 ASP.NET Core Blazor의 .NET 메서드에서 JavaScript 함수 호출을 참조하세요.

JavaScript 호출 가능한 .NET 메서드를 트리밍하지 않습니다.

런타임 다시 연결은 명시적으로 유지되지 않는 한 클래스 인스턴스 JavaScript 호출 가능한 .NET 메서드를 트리밍합니다. 자세한 내용은 ASP.NET Core의 JavaScript 함수에서 .NET 메서드 호출을 참조하세요 Blazor.

빌드, 패키지 및 NuGet에 제공

Razor 구성 요소를 포함하는 Razor 클래스 라이브러리는 표준 .NET 라이브러리이기 때문에 구성 요소를 압축하여 NuGet에 제공하는 과정이 라이브러리를 압축하여 NuGet에 제공하는 과정과 다르지 않습니다. 명령 셸에서 dotnet pack 명령을 사용하여 압축합니다.

dotnet pack

명령 셸에서 dotnet nuget push 명령을 사용하여 패키지를 NuGet에 업로드합니다.

상표

Jeep 및 Jeep YJ는 FCA US LLC(Stellantis NV)의 상표로 등록되어 있습니다.

추가 리소스

• ASP.NET Core를 사용하여 클래스 라이브러리에서 재사용 가능한 Razor UI
• 클래스 라이브러리에서 ASP.NET Core API 사용
• 라이브러리에 XML IL(중간 언어) 트리머 구성 파일 추가
• Razor 클래스 라이브러리를 사용한 CSS 격리 지원