NuGet

NuGet은 .NET 에코시스템의 패키지 관리자이며, 개발자가 .NET 오픈 소스 라이브러리를 검색하고 획득할 수 있는 기본 방법입니다. NuGet 패키지를 호스트하기 위해 Microsoft에서 제공하는 무료 서비스인 NuGet.org가 공용 NuGet 패키지의 기본 호스트지만, MyGet 및 Azure Artifacts와 같은 사용자 지정 NuGet 서비스에 게시할 수도 있습니다.

NuGet 패키지 만들기

NuGet 패키지(*.nupkg)는 .NET 어셈블리 및 관련 메타데이터를 포함하는 zip 파일입니다.

NuGet 패키지를 만드는 방법에는 크게 두 가지가 있습니다. 최신 및 권장되는 방법은 SDK 스타일 프로젝트(콘텐츠가 <Project Sdk="Microsoft.NET.Sdk">로 시작하는 프로젝트 파일)에서 패키지를 만드는 것입니다. 어셈블리 및 대상은 패키지에 자동으로 추가되고, 패키지 이름 및 버전 번호와 같은 나머지 메타데이터는 MSBuild 파일에 추가됩니다. dotnet pack 명령을 사용하여 컴파일하면 어셈블리 대신 *.nupkg 파일이 출력됩니다.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <AssemblyName>Contoso.Api</AssemblyName>
    <PackageVersion>1.1.0</PackageVersion>
    <Authors>John Doe</Authors>
  </PropertyGroup>
</Project>

NuGet 패키지를 만드는 이전 방법은 *.nuspec 파일 및 nuget.exe 명령줄 도구를 사용하는 것입니다. nuspec 파일을 사용하면 제어 기능이 향상되지만 최종 NuGet 패키지에 포함할 어셈블리 및 대상을 신중하게 지정해야 합니다. 실수하거나, 다른 사람이 변경할 때 nuspec 업데이트를 잊어버리기 쉽습니다. nuspec의 장점은 아직 SDK 스타일 프로젝트 파일을 지원하지 않는 프레임워크에 대한 NuGet 패키지를 만드는 데 사용할 수 있다는 것입니다.

✔ NuGet 패키지를 만드는 데 SDK 스타일 프로젝트 파일을 사용하는 것을 고려하세요.

패키지 종속성

NuGet 패키지 종속성은 종속성 문서에서 자세히 다룹니다.

중요 NuGet 패키지 메타데이터

NuGet 패키지는 많은 메타데이터 속성을 지원합니다. 다음 표에는 모든 NuGet.org의 패키지에서 제공해야 하는 핵심 메타데이터가 나와 있습니다.

✔️ NuGet 패키지 이름 선택 시 NuGet의 접두사 예약 조건을 충족하는 접두사를 가지도록 하는 것을 고려합니다.

✔️ 패키지 아이콘에 대한 HTTPS href를 사용합니다.

HTTPS를 사용하여 실행되고 HTTPS가 아닌 이미지를 표시하는 NuGet.org 등의 사이트는 혼합 콘텐츠 경고를 만듭니다.

✔️ 보기 결과를 최적화하기 위해 64x64이고 투명한 배경을 가진 패키지 아이콘 이미지를 사용합니다.

✔️ 소스 링크를 설정하여 어셈블리 및 NuGet 패키지에 소스 제어 메타데이터를 추가하세요.

소스 링크는 RepositoryUrl 및 RepositoryType 메타데이터를 NuGet 패키지에 자동으로 추가합니다. 소스 링크는 패키지가 빌드된 정확한 소스 코드에 대한 정보도 추가합니다. 예를 들어 Git 리포지토리에서 만든 패키지에는 메타데이터로 추가된 커밋 해시가 있습니다.

시험판 패키지

버전 접미사가 있는 NuGet 패키지는 시험판으로 간주됩니다. 기본적으로 NuGet 패키지 관리자 UI는 사용자가 시험판 패키지를 옵트인하지 않는 한 안정적인 릴리스를 표시하므로, 시험판 패키지는 제한된 사용자 테스트에 적합합니다.

<PackageVersion>1.0.1-beta1</PackageVersion>

✔️ 테스트, 미리 보기 또는 실험 시에는 시험판 패키지를 게시합니다.

✔️ 준비가 되면 안정적인 패키지를 게시하여 다른 안정적인 패키지가 참조할 수 있도록 합니다.

기호 패키지

기호 파일(*.pdb)은 어셈블리와 함께 .NET 컴파일러에서 생성됩니다. 기호 파일은 실행 위치를 원래 소스 코드에 매핑하므로, 디버거를 사용하여 실행 중인 소스 코드를 한 단계씩 실행할 수 있습니다. NuGet은 .NET 어셈블리를 포함하는 주 패키지와 함께 기호 파일을 포함하는 별도의 기호 패키지(*.snupkg) 생성을 지원합니다. 기호 패키지는 기호 서버에서 호스트되며 요청 시 Visual Studio와 같은 도구에서만 다운로드되도록 설계되었습니다.

NuGet.org는 자체 기호 서버 리포지토리를 호스팅합니다. 개발자는 해당 Visual Studio의 심볼 소스에 https://symbols.nuget.org/download/symbols를 추가하여 NuGet.org 기호 서버에 게시된 기호를 사용할 수 있습니다.

기호 패키지를 만드는 대신 기본 NuGet 패키지에 기호 파일을 포함시킬 수 있습니다. 기본 NuGet 패키지는 더 클 것이지만 포함된 기호 파일은 개발자가 NuGet.org 기호 서버를 구성할 필요가 없음을 의미합니다. SDK 스타일 프로젝트를 사용하여 NuGet 패키지를 빌드하는 경우 AllowedOutputExtensionsInPackageBuildOutputFolder 속성을 설정하여 기호 파일을 포함시킬 수 있습니다.

<Project Sdk="Microsoft.NET.Sdk">
 <PropertyGroup>
    <!-- Include symbol files (*.pdb) in the built .nupkg -->
    <AllowedOutputExtensionsInPackageBuildOutputFolder>$(AllowedOutputExtensionsInPackageBuildOutputFolder);.pdb</AllowedOutputExtensionsInPackageBuildOutputFolder>
  </PropertyGroup>
</Project>

포함된 기호 파일의 단점은 SDK 스타일 프로젝트를 사용하여 컴파일된 .NET 라이브러리의 패키지 크기가 약 30% 증가한다는 것입니다. 패키지 크기가 중요한 경우 기호 패키지에 기호를 게시해야 합니다.

✔️ NuGet.org에 기호 패키지(*.snupkg)로 기호를 게시하는 것을 고려하세요.

기호 패키지(*.snupkg)는 주 패키지 크기를 블로트하지 않고 NuGet 패키지를 디버그할 의도가 없는 개발자에게 복원 성능에 영향을 주지 않으면서 개발자에게 좋은 주문형 디버깅 환경을 제공합니다.

중요한 점은 기호 파일을 가져오기 위해 사용자가 해당 IDE에서 NuGet 기호 서버를 찾아(한 번 설정으로) 구성해야 한다는 것입니다. Visual Studio 2019 버전 16.1은 기본 기호 서버 목록에 NuGet.org의 기호 서버를 추가했습니다.