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

아티클
11/30/2023

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

지원할 ASP.NET Core 버전 결정

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

LTS(장기 지원)로 분류된 모든 ASP.NET Core 버전을 지원하도록 노력합니다.
EOL(수명 종료)로 분류된 ASP.NET Core 버전을 지원할 의무는 없습니다.

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

.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 확장성 포함

Blazor는 서버 쪽 및 클라이언트 쪽 앱에 대한 구성 요소 클래스 라이브러리 만들기 Razor 를 지원합니다. 클래스 라이브러리의 구성 요소를 지원 Razor 하려면 클래스 라이브러리에서 Microsoft.NET.Sdk를 사용해야 합니다.Razor SDK.

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

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

Visual Studio
Visual Studio Code/.NET Core CLI

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

참고 항목

페이지 및 뷰 지원 확인란을 선택하지 마세요. 검사box를 선택하면 서버 쪽 앱만 지원하는 클래스 라이브러리가 생성됩니다.

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

dotnet new razorclasslib

참고 항목

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

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

설치된 SDK에 따라 현재 .NET Framework를 대상으로 합니다.
SupportedPlatform MSBuild 항목에서 지원되는 플랫폼으로 browser를 포함하여 플랫폼 종속성에 대해 브라우저 호환성 검사를 사용하도록 설정합니다.
Microsoft.AspNetCore.Components.Web에 대한 NuGet 패키지 참조를 추가합니다.

RazorClassLibrary-CSharp.csproj (참조 원본)

참고 항목

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

여러 프레임워크 버전 지원

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

<TargetFrameworks>{TARGET FRAMEWORKS}</TargetFrameworks>

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

서버 쪽 사용만 지원

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

지원 페이지 및 뷰 검사box(Visual Studio) 또는 -s|--support-pages-and-views 명령을 사용하여 옵션을 사용하여 라이브러리를 만들 때 라이브러리가 페이지와 dotnet new 보기를 지원하게 지정합니다.
```
dotnet new razorclasslib -s
```
다른 필수 MS 빌드 속성 외에도 라이브러리의 프로젝트 파일에서 ASP.NET Core에 대한 프레임워크 참조만 제공합니다.
```
<ItemGroup>
  <FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
```

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

MVC 확장성 포함

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

Razor 보기 또는 Razor Pages
태그 도우미
뷰 구성 요소

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

Razor 보기 또는 Razor Pages

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

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

true로 설정된 AddRazorSupportForMvc MSBuild 속성.
공유 프레임워크에 대한 <FrameworkReference> 요소.

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

Visual Studio
Visual Studio Code/.NET Core 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>

뷰 구성 요소

구성 요소 보기를 포함하는 프로젝트는 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.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.Razor에 대한 참조는 .NET Framework 4.6.1 이상 또는 .NET Core 2.x를 대상으로 하는 소비자에게 추가됩니다. 이전 버전과의 호환성으로 인해 패키지의 버전 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, Xamarin 같은 다른 .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가 필요하고 이 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 API 사용

지원할 ASP.NET Core 버전 결정

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

Blazor 확장성 포함

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

여러 프레임워크 버전 지원

서버 쪽 사용만 지원

MVC 확장성 포함

Razor 보기 또는 Razor Pages

태그 도우미

뷰 구성 요소

여러 ASP.NET Core 버전 지원

변경되지 않은 API 사용

변경된 API 사용

3.1에 도입된 API 사용

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

추가 리소스

피드백

추가 리소스