클래스 라이브러리에서 ASP.NET Core API 사용

아티클
01/16/2025

이 문서에서는 클래스 라이브러리에서 ASP.NET Core API를 사용하기 위한 지침을 제공합니다. 다른 모든 라이브러리 지침은오픈 소스 라이브러리 지침을 참조하세요.

지원할 ASP.NET Core 버전 결정

ASP.NET Core는 .NET Core 지원 정책준수합니다. 라이브러리에서 지원할 ASP.NET Core 버전을 결정할 때 지원 정책을 참조하세요. 라이브러리는 다음을 수행해야 합니다.

Long-Term LTS(지원)로 분류된 모든 ASP.NET Core 버전을 지원하기 위해 노력합니다.
EOL(수명 종료)으로 분류된 ASP.NET Core 버전을 지원할 의무가 없습니다.

ASP.NET Core의 미리 보기 릴리스를 사용할 수 있게 되면서 aspnet/Announcements GitHub 리포지토리에 주요 변경 내용이 게시됩니다. 프레임워크 기능이 개발될 때 라이브러리의 호환성 테스트를 수행할 수 있습니다.

ASP.NET Core 공유 프레임워크 사용

.NET Core 3.0 릴리스에서는 많은 ASP.NET Core 어셈블리가 더 이상 NuGet에 패키지로 게시되지 않습니다. 대신 어셈블리는 .NET Core SDK 및 런타임 설치 관리자와 함께 설치된 Microsoft.AspNetCore.App 공유 프레임워크에 포함됩니다. 더 이상 게시되지 않는 패키지 목록은 사용되지 않는 패키지 참조 제거를 참조하세요.

.NET Core 3.0을 기준으로 Microsoft.NET.Sdk.Web MSBuild SDK를 사용하는 프로젝트는 공유 프레임워크를 암시적으로 참조합니다. Microsoft.NET.Sdk 또는 Microsoft.NET.Sdk.Razor SDK를 사용하는 프로젝트는 공유 프레임워크에서 ASP.NET Core API를 사용하려면 ASP.NET Core를 참조해야 합니다.

ASP.NET Core를 참조하려면 프로젝트 파일에 다음 <FrameworkReference> 요소를 추가합니다.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

Blazor의 확장성을 포함하십시오

는 서버 및 클라이언트 쪽 앱을 위한 클래스 라이브러리를 생성하는 구성 요소 작성을 지원합니다. 클래스 라이브러리에서 Razor 구성 요소를 지원하려면 클래스 라이브러리는 Microsoft.NET.SdkRazor SDK을 사용해야 합니다.

서버 쪽 및 클라이언트 쪽 앱 지원

단일 라이브러리에서 서버 쪽 및 클라이언트 쪽 앱에서 Razor 구성 요소 사용을 지원하려면 편집기에서 다음 지침을 사용합니다.

Visual Studio
Visual Studio Code/ .NET CLI

Razor 클래스 라이브러리 프로젝트 템플릿을 사용합니다.

메모

지원 페이지 및 보기 확인란을 선택하지 마십시오. 확인란을 선택하면 서버 쪽 앱만 지원하는 클래스 라이브러리가 생성됩니다.

VS Code(통합 터미널) 또는 명령 셸(.NET CLI)에서 다음 명령을 실행합니다.

dotnet new razorclasslib

메모

dotnet new 명령에 -s|--support-pages-and-views 옵션을 추가하지 않습니다. 옵션을 적용하면 서버 쪽 앱만 지원하는 클래스 라이브러리가 생성됩니다.

프로젝트 템플릿에서 생성된 라이브러리:

설치된 SDK를 기반으로 현재 .NET 프레임워크를 대상으로 합니다.
브라우저 호환성 검사를 사용하도록 설정하여 플랫폼 종속성을 확인하기 위해, SupportedPlatform MSBuild 항목에 지원되는 플랫폼으로 browser을 포함시킵니다.
NuGet 패키지 참조를 Microsoft.AspNetCore.Components.Web에 추가합니다.

RazorClassLibrary-CSharp.csproj(참조 원본)

메모

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

여러 프레임워크 버전 지원

라이브러리가 하나 이상의 이전 릴리스를 지원하는 동안 현재 릴리스의 Blazor 추가된 기능을 지원해야 하는 경우 라이브러리를 다중 대상으로 지정합니다. TargetFrameworks MSBuild 속성에 TFM(대상 프레임워크 모니커) 세미콜론으로 구분된 목록을 제공합니다.

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

앞의 예제에서 {TARGET FRAMEWORKS} 자리 표시자는 세미콜론으로 구분된 TFM 목록을 나타냅니다. 예를 들어 netcoreapp3.1;net5.0.

서버 쪽 사용만 지원

클래스 라이브러리는 서버 쪽 앱만 지원하도록 빌드되는 경우가 거의 없습니다. 클래스 라이브러리에 또는 대한 액세스와 같은 서버 쪽 특정 기능만 필요하거나 미들웨어, MVC 컨트롤러 또는 Pages와 같은 ASP.NET Core 관련 기능을 사용하는 경우 다음 방법 중 하나의 사용합니다.

라이브러리를 생성할 때 라이브러리가 페이지 및 보기를 지원하도록 지정하려면 지원 페이지 및 뷰 확인란(Visual Studio)을 선택하거나, dotnet new 명령과 함께 -s|--support-pages-and-views 옵션을 사용하십시오.
```
dotnet new razorclasslib -s
```
다른 필수 MSBuild 속성 외에도 라이브러리의 프로젝트 파일에서 ASP.NET Core에 대한 프레임워크 참조만 제공합니다.
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

Razor 구성 요소가 포함된 라이브러리에 대한 자세한 정보는 RCL(Razor 클래스 라이브러리)에서 ASP.NET Core Razor 구성 요소 사용을 참조하세요.

MVC 확장성 포함

이 섹션에서는 다음을 포함하는 라이브러리에 대한 권장 사항을 간략하게 설명합니다.

Razor 조회 또는 Razor 페이지
태그 도우미
구성 요소 보기

이 섹션에서는 여러 버전의 MVC를 지원하는 다중 대상 지정에 대해 설명하지 않습니다. 여러 ASP.NET Core 버전을 지원하는 방법에 대한 지침은 여러 ASP.NET Core 버전 지원을 참조하세요.

Razor 보기 또는 Razor 페이지

Razor 보기 또는 Razor Pages 포함하는 프로젝트는 Microsoft.NET.Sdk를 사용해야 합니다. SDKRazor.

프로젝트가 .NET Core 3.x를 대상으로 하는 경우 다음이 필요합니다.

AddRazorSupportForMvc MSBuild 속성은 true로 설정되었습니다.
공유 프레임워크의 <FrameworkReference> 요소입니다.

Razor 클래스 라이브러리 프로젝트 템플릿은 .NET Core를 대상으로 하는 프로젝트에 대한 이전 요구 사항을 충족합니다. 편집기에서 다음 지침을 사용합니다.

Visual Studio
Visual Studio Code/ .NET CLI

Razor 클래스 라이브러리 프로젝트 템플릿을 사용합니다. 템플릿의 지원 페이지와 보기 옵션 확인란을 선택해야 합니다.

VS Code(통합 터미널) 또는 명령 셸(.NET CLI)에서 다음 명령을 실행합니다.

dotnet new razorclasslib -s

예를 들어:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <AddRazorSupportForMvc>true</AddRazorSupportForMvc>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

프로젝트가 대신 .NET Standard를 대상으로 하는 경우 Microsoft.AspNetCore.Mvc 패키지 참조가 필요합니다. Microsoft.AspNetCore.Mvc 패키지는 ASP.NET Core 3.0에서 공유 프레임워크로 이동되었으므로 더 이상 게시되지 않습니다. 예를 들어:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

태그 도우미

태그 도우미 포함하는 프로젝트는 Microsoft.NET.Sdk SDK를 사용해야 합니다. .NET Core 3.x를 대상으로 하는 경우 공유 프레임워크에 대한 <FrameworkReference> 요소를 추가합니다. 예를 들어:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

.NET Standard를 대상으로 하는 경우(ASP.NET Core 3.x 이전 버전을 지원하기 위해) Microsoft.AspNetCore.Mvc에 패키지 참조를 추가합니다.Razor. Microsoft.AspNetCore.Mvc.Razor 패키지는 공유 프레임워크로 이동되었으므로 더 이상 게시되지 않습니다. 예를 들어:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc" Version="2.2.0" />
  </ItemGroup>

</Project>

구성 요소 보기

View 구성 요소를 포함하는 프로젝트는 SDK를 사용해야 합니다. .NET Core 3.x를 대상으로 하는 경우 공유 프레임워크에 대한 <FrameworkReference> 요소를 추가합니다. 예를 들어:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp3.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

</Project>

.NET Standard를 대상으로 하는 경우(ASP.NET Core 3.x 이전 버전을 지원하기 위해) Microsoft.AspNetCore.Mvc.ViewFeatures패키지 참조를 추가합니다. Microsoft.AspNetCore.Mvc.ViewFeatures 패키지는 공유 프레임워크로 이동되었으므로 더 이상 게시되지 않습니다. 예를 들어:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Mvc.ViewFeatures" Version="2.2.0" />
  </ItemGroup>

</Project>

여러 ASP.NET Core 버전 지원

다중 대상 지정은 ASP.NET Core의 여러 변형을 지원하는 라이브러리를 작성하는 데 필요합니다. 태그 도우미 라이브러리가 다음 ASP.NET Core 변형을 지원해야 하는 시나리오를 고려합니다.

.NET Framework 4.6.1을 대상으로 하는 ASP.NET Core 2.1
.NET Core 2.x를 대상으로 하는 ASP.NET Core 2.x
.NET Core 3.x를 대상으로 하는 ASP.NET Core 3.x

다음 프로젝트 파일은 TargetFrameworks 속성을 통해 이러한 변형을 지원합니다.

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1;net461</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

이전 프로젝트 파일을 사용하여 다음을 수행합니다.

Markdig 패키지는 모든 소비자에 대해 추가됩니다.
Microsoft.AspNetCore.Mvc에 대한 참조입니다. .NET Framework 4.6.1 이상 또는 .NET Core 2.x를 대상으로 하는 소비자를 위해Razor 추가됩니다. 패키지 버전 2.1.0은 이전 버전과의 호환성 때문에 ASP.NET Core 2.2에서 작동합니다.
소비자들이 .NET Core 3.x를 대상으로 할 때 공유 프레임워크가 참조됩니다. Microsoft.AspNetCore.Mvc.Razor 패키지는 공유 프레임워크에 포함됩니다.

또는 .NET Core 2.1 및 .NET Framework 4.6.1을 모두 대상으로 지정하는 대신 .NET Standard 2.0을 대상으로 지정할 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netstandard2.0;netcoreapp3.1</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

이전 프로젝트 파일에서는 다음과 같은 주의 사항이 있습니다.

라이브러리에는 태그 도우미만 포함되므로 ASP.NET Core가 실행되는 특정 플랫폼인 .NET Core 및 .NET Framework를 대상으로 지정하는 것이 더 간단합니다. 태그 도우미는 Unity 및 UWP와 같은 다른 .NET Standard 2.0 규격 대상 프레임워크에서 사용할 수 없습니다.
.NET Framework에서 .NET Standard 2.0을 사용하면 .NET Framework 4.7.2에서 해결된 몇 가지 문제가 있습니다. .NET Framework 4.6.1을 대상으로 지정하면 소비자가 .NET Framework 4.6.1부터 4.7.1까지 사용하는 환경을 개선할 수 있습니다.

라이브러리가 플랫폼별 API를 호출해야 하는 경우 .NET Standard 대신 특정 .NET 구현을 대상으로 합니다. 자세한 내용은 다중 대상 지정참조하세요.

변경되지 않은 API 사용

미들웨어 라이브러리를 .NET Core 2.2에서 3.1로 업그레이드하는 시나리오를 상상해 보십시오. 라이브러리에서 사용되는 ASP.NET Core 미들웨어 API는 ASP.NET Core 2.2와 3.1 간에 변경되지 않았습니다. .NET Core 3.1에서 미들웨어 라이브러리를 계속 지원하려면 다음 단계를 수행합니다.

표준 라이브러리 지침을 따릅니다.
해당 어셈블리가 공유 프레임워크에 없는 경우 각 API의 NuGet 패키지에 대한 패키지 참조를 추가합니다.

변경된 API 사용

라이브러리를 .NET Core 2.2에서 .NET Core 3.1로 업그레이드하는 시나리오를 상상해 보십시오. 라이브러리에서 사용되는 ASP.NET Core API에는 ASP.NET Core 3.1에서 호환성에 영향을 주는 변경 사항 있습니다. 모든 버전에서 끊어진 API를 사용하지 않도록 라이브러리를 다시 작성할 수 있는지 여부를 고려합니다.

라이브러리를 다시 작성할 수 있는 경우 패키지 참조를 사용하여 이전 대상 프레임워크(예: .NET Standard 2.0 또는 .NET Framework 4.6.1)를 계속 대상으로 지정합니다.

라이브러리를 다시 쓸 수 없는 경우 다음 단계를 수행합니다.

.NET Core 3.1에 대한 대상을 추가합니다.
공유 프레임워크에 대한 <FrameworkReference> 요소를 추가합니다.
적절한 대상 프레임워크 기호와 함께 #if 전처리기 지시문 사용하여 코드를 조건부로 컴파일합니다.

예를 들어 HTTP 요청 및 응답 스트림에 대한 동기 읽기 및 쓰기는 기본적으로 ASP.NET Core 3.1에서 사용하지 않도록 설정됩니다. ASP.NET Core 2.2는 기본적으로 동기 동작을 지원합니다. I/O가 발생하는 경우 동기 읽기 및 쓰기를 사용하도록 설정해야 하는 미들웨어 라이브러리를 고려합니다. 라이브러리는 적절한 전처리기 지시문에서 동기 기능을 사용하도록 코드를 묶어야 합니다. 예를 들어:

public async Task Invoke(HttpContext httpContext)
{
    if (httpContext.Request.Path.StartsWithSegments(_path, StringComparison.Ordinal))
    {
        httpContext.Response.StatusCode = (int) HttpStatusCode.OK;
        httpContext.Response.ContentType = "application/json";
        httpContext.Response.ContentLength = _bufferSize;

#if !NETCOREAPP3_1 && !NETCOREAPP5_0
        var syncIOFeature = httpContext.Features.Get<IHttpBodyControlFeature>();
        if (syncIOFeature != null)
        {
            syncIOFeature.AllowSynchronousIO = true;
        }

        using (var sw = new StreamWriter(
            httpContext.Response.Body, _encoding, bufferSize: _bufferSize))
        {
            _json.Serialize(sw, new JsonMessage { message = "Hello, World!" });
        }
#else
        await JsonSerializer.SerializeAsync<JsonMessage>(
            httpContext.Response.Body, new JsonMessage { message = "Hello, World!" });
#endif
        return;
    }

    await _next(httpContext);
}

3.1에 도입된 API 사용

ASP.NET Core 3.1에서 도입된 ASP.NET Core API를 사용하려는 경우를 상상해 보십시오. 다음 질문을 고려합니다.

라이브러리에 새 API가 기능적으로 필요합니까?
라이브러리에서 이 기능을 다른 방식으로 구현할 수 있나요?

라이브러리에 기능적으로 API가 필요하고 하위 수준을 구현할 방법이 없는 경우:

.NET Core 3.x만 대상으로 지정합니다.
공유 프레임워크에 대한 <FrameworkReference> 요소를 추가합니다.

라이브러리가 다른 방식으로 기능을 구현할 수 있는 경우:

.NET Core 3.x를 대상 프레임워크로 추가합니다.
공유 프레임워크에 대한 <FrameworkReference> 요소를 추가합니다.
적절한 대상 프레임워크 기호와 함께 #if 전처리기 지시문 사용하여 코드를 조건부로 컴파일합니다.

예를 들어 다음 태그 도우미는 ASP.NET Core 3.1에 도입된 IWebHostEnvironment 인터페이스를 사용합니다. .NET Core 3.1을 대상으로 하는 소비자는 NETCOREAPP3_1 대상 프레임워크 기호로 정의된 코드 경로를 실행합니다. 태그 도우미의 생성자 매개변수 형식이 .NET Core 2.1 및 .NET Framework 4.6.1 사용자에게 IHostingEnvironment로 변경됩니다. 이 변경은 ASP.NET Core 3.1이 IHostingEnvironment 사용되지 않는 것으로 표시하고 대체로 IWebHostEnvironment 권장했기 때문에 필요했습니다.

[HtmlTargetElement("script", Attributes = "asp-inline")]
public class ScriptInliningTagHelper : TagHelper
{
    private readonly IFileProvider _wwwroot;

#if NETCOREAPP3_1
    public ScriptInliningTagHelper(IWebHostEnvironment env)
#else
    public ScriptInliningTagHelper(IHostingEnvironment env)
#endif
    {
        _wwwroot = env.WebRootFileProvider;
    }

    // code omitted for brevity
}

다음 다중 대상 프로젝트 파일은 이 태그 도우미 시나리오를 지원합니다.

<Project Sdk="Microsoft.NET.Sdk">
  
  <PropertyGroup>
    <TargetFrameworks>netcoreapp2.1;netcoreapp3.1;net461</TargetFrameworks>
  </PropertyGroup>
  
  <ItemGroup>
    <PackageReference Include="Markdig" Version="0.16.0" />
  </ItemGroup>
  
  <ItemGroup Condition="'$(TargetFramework)' != 'netcoreapp3.1'">
    <PackageReference Include="Microsoft.AspNetCore.Mvc.Razor" Version="2.1.0" />
  </ItemGroup>

  <ItemGroup Condition="'$(TargetFramework)' == 'netcoreapp3.1'">
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>
</Project>

공유 프레임워크에서 제거된 API 사용

공유 프레임워크에서 제거된 ASP.NET Core 어셈블리를 사용하려면 적절한 패키지 참조를 추가합니다. ASP.NET Core 3.1의 공유 프레임워크에서 제거된 패키지 목록은 사용되지 않는 패키지 참조제거를 참조하세요.

예를 들어 웹 API 클라이언트를 추가하려면 다음을 수행합니다.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <FrameworkReference Include="Microsoft.AspNetCore.App" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNet.WebApi.Client" Version="5.2.7" />
  </ItemGroup>

</Project>

추가 리소스

ASP.NET Core 사용하여 클래스 라이브러리에서 재사용 가능한 UI
ASP.NET Core Razor 구성 요소를 Razor 클래스 라이브러리(RCL) 에서 사용하기
.NET 구현 지원
.NET 지원 정책

다음을 통해 공유

클래스 라이브러리에서 ASP.NET Core API 사용

지원할 ASP.NET Core 버전 결정

ASP.NET Core 공유 프레임워크 사용

Blazor의 확장성을 포함하십시오

서버 쪽 및 클라이언트 쪽 앱 지원

여러 프레임워크 버전 지원

서버 쪽 사용만 지원

MVC 확장성 포함

Razor 보기 또는 Razor 페이지

태그 도우미

구성 요소 보기

여러 ASP.NET Core 버전 지원

변경되지 않은 API 사용

변경된 API 사용

3.1에 도입된 API 사용

공유 프레임워크에서 제거된 API 사용

추가 리소스

추가 리소스