packages.config를 PackageReference로 마이그레이션

  • 아티클

Visual Studio 2017 버전 15.7 이상은 프로젝트를 packages.config 관리 형식에서 PackageReference 형식으로 마이그레이션하도록 지원합니다.

PackageReference 사용 혜택

  • 한 위치에서 모든 프로젝트 종속성 관리: 프로젝트 간 참조나 어셈블리 참조처럼 NuGet 패키지 참조(PackageReference 노드 사용)는 별도의 packages.config 파일을 사용하지 않고 프로젝트 파일 내에서 직접 관리됩니다.
  • 최상위 종속성의 깔끔한 보기: packages.config와 달리 PackageReference는 프로젝트에 직접 설치한 NuGet 패키지만 나열합니다. 따라서 NuGet 패키지 관리자 UI 및 프로젝트 파일은 하위 수준 종속성으로 인해 복잡하게 보이지 않습니다.
  • 성능 개선: PackageReference를 사용하는 경우, 패키지는 솔루션 내 packages 폴더에서보다는 전역 패키지 폴더(전역 패키지 및 캐시 폴더 관리에 대해 설명된 대로)에 유지됩니다. 따라서 PackageReference는 처리 속도가 더 빠르고 디스크 공간을 더 적게 사용합니다.
  • 종속성 및 콘텐츠 흐름에 대한 세밀한 제어: MSBuild의 기존 기능을 사용하면 NuGet 패키지를 조건부로 참조하고 대상 프레임워크, 구성, 플랫폼 또는 기타 피벗별로 패키지 참조를 선택할 수 있습니다.

제한 사항

  • NuGet PackageReference는 Visual Studio 2015 이하에서 사용할 수 없습니다. 마이그레이션된 프로젝트는 Visual Studio 2017 이상에서만 열 수 있습니다.
  • 현재 C++ 및 ASP.NET 프로젝트에는 마이그레이션이 제공되지 않습니다.
  • 일부 패키지는 PackageReference와 완전히 호환되지 않을 수 있습니다. 자세한 내용은 패키지 호환성 문제를 참조하세요.

또한 PackageReferences가 packages.config와 비교하여 작동하는 방식에는 몇 가지 차이점이 있습니다. 예를 들어 업그레이드 버전에 대한 제약 조건은 PackageReference에서 지원되지 않지만 PackageReference는 부동 버전에 대한 지원을 추가합니다.

알려진 문제

  1. Migrate packages.config to PackageReference... 옵션을 오른쪽 클릭 상황에 맞는 메뉴에서 사용할 수 없습니다.

문제

프로젝트를 처음 열면 NuGet 작업이 수행될 때까지 NuGet을 초기화할 수 없습니다. 이로 인해 마이그레이션 옵션이 packages.config 또는 References의 오른쪽 클릭 상황에 맞는 메뉴에 표시되지 않습니다.

해결 방법

다음 NuGet 작업 중 하나를 수행합니다.

  • 패키지 관리자 UI 열기 - References를 마우스 오른쪽 단추로 클릭하고 Manage NuGet Packages...를 선택합니다.
  • 패키지 관리자 콘솔 열기 - Tools > NuGet Package Manager에서 Package Manager Console을 선택합니다.
  • NuGet 복원 실행 - 솔루션 탐색기에서 솔루션 노드를 마우스 오른쪽 단추로 클릭하고 Restore NuGet Packages를 선택합니다.
  • NuGet 복원을 트리거하는 프로젝트 빌드

이제 마이그레이션 옵션이 표시됩니다. 이 옵션은 지원되지 않으며 ASP.NET 및 C++ 프로젝트 형식에 대해 표시되지 않습니다.

마이그레이션 단계

참고 항목

마이그레이션을 시작하기 전에 Microsoft Visual Studio는 필요한 경우 packages.config로 롤백할 수 있도록 프로젝트의 백업을 만듭니다.

  1. packages.config를 사용하여 프로젝트가 포함된 솔루션을 엽니다.

  2. 솔루션 탐색기에서 참조 노드 또는 packages.config 파일을 마우스 오른쪽 단추로 클릭하고 packages.config에서 PackageReference로 마이그레이션을 선택합니다.

  3. 마이그레이터는 프로젝트의 NuGet 패키지 참조를 분석하여 최상위 종속성(직접 설치한 NuGet 패키지) 및 전이적 종속성(최상위 패키지의 종속성으로 설치된 패키지)으로 분류하려고 시도합니다.

    참고 항목

    PackageReference는 전이적 패키지 복원을 지원하고 종속성을 동적으로 확인합니다. 즉, 전이적 종속성을 명시적으로 설치할 필요가 없습니다.

  4. (선택 사항) 패키지의 최상위 레벨 옵션을 선택함으로써 전이적 종속성으로 분류된 NuGet 패키지를 최상위 종속성으로 선택하여 처리할 수 있습니다. 이 옵션은 전이적으로 이동하지 않는 자산(build, buildCrossTargeting, contentFiles 또는 analyzers 폴더의 자산) 및 개발 종속성(developmentDependency = "true")으로 표시된 자산을 포함하는 패키지에 대해 자동으로 설정됩니다.

  5. 모든 패키지 호환성 문제를 검토합니다.

  6. 확인을 선택하여 마이그레이션을 시작합니다.

  7. 마이그레이션이 끝나면 Microsoft Visual Studio는 백업 파일 경로, 설치한 패키지 목록(최상위 종속성), 전이적 종속성으로 참조되는 패키지 목록, 마이그레이션 시작 시 식별되는 호환성 문제 목록이 포함된 보고서를 제공합니다. 보고서는 백업 폴더에 저장됩니다.

  8. 솔루션이 빌드되고 실행되는지 확인합니다. 문제가 발생하는 경우, GitHub에 문제를 보고하세요.

packages.config로 롤백하는 방법

  1. 마이그레이션된 프로젝트를 닫습니다.

  2. 백업한 프로젝트 파일과 packages.config(일반적으로 <solution_root>\MigrationBackup\<unique_guid>\<project_name>\에 위치)를 프로젝트 폴더에 복사합니다. obj 폴더가 프로젝트 루트 디렉터리에 있으면 삭제합니다.

  3. 프로젝트를 엽니다.

  4. 도구 > NuGet 패키지 관리자 > 패키지 관리자 콘솔 메뉴 명령을 사용하여 패키지 관리자 콘솔을 엽니다.

  5. 콘솔에서 다음 명령을 실행합니다.

    update-package -reinstall

마이그레이션 후 패키지 만들기

마이그레이션이 완료되면 nuget.build.tasks.pack NuGet 패키지에 대한 참조를 추가한 다음 msbuild -t:pack을 사용하여 패키지를 만드는 것이 좋습니다. 일부 시나리오에서는 msbuild -t:pack 대신 dotnet.exe pack을 사용할 수 있지만, 이는 권장하지 않습니다.

패키지 호환성 문제

packages.config에서 지원되던 일부 요소가 PackageReference에서는 지원되지 않습니다. 마이그레이터는 이러한 문제를 분석하고 검색합니다. 다음 중 하나 이상의 문제가 있는 패키지는 마이그레이션 후 예상대로 작동하지 않을 수 있습니다.

패키지가 마이그레이션 후에 설치되면 "install.ps1" 스크립트가 무시됩니다.

  • 설명: PackageReference를 사용하면 패키지를 설치하거나 제거하는 동안 install.ps1 및 uninstall.ps1 PowerShell 스크립트가 실행되지 않습니다.

  • 잠재적 영향: 대상 프로젝트에서 일부 동작을 구성하기 위해 이러한 스크립트에 의존하는 패키지가 예상대로 작동하지 않을 수 있습니다.

패키지가 마이그레이션 후에 설치되면 "콘텐츠" 자산을 사용할 수 없습니다.

  • 설명: 패키지의 content 폴더에 있는 자산이 PackageReference에서 지원되지 않고 무시됩니다. PackageReference는 contentFiles에 대한 지원을 추가하여 더 나은 전이적 지원 및 공유 콘텐츠를 제공합니다.

  • 잠재적 영향: content의 자산이 프로젝트 폴더에 복사되지 않으며 해당 자산의 존재에 영향을 받는 프로젝트 코드는 리팩터링해야 합니다.

패키지가 업그레이드 후에 설치되면 XDT 변환이 적용되지 않습니다.

  • 설명: XDT 변환이 PackageReference에서 지원되지 않으며 패키지를 설치하거나 제거할 때 .xdt 파일이 무시됩니다.

  • 잠재적 영향: XDT 변환은 프로젝트 XML 파일에 적용되지 않으며, 가장 일반적으로 web.config.install.xdtweb.config.uninstall.xdt패키지가 설치되거나 제거될 때 프로젝트의 web.config 파일이 업데이트되지 않음을 의미합니다.

패키지가 마이그레이션 후에 설치되면 lib 루트의 어셈블리가 무시됩니다.

  • 설명: PackageReference를 사용하면 대상 프레임워크 관련 하위 폴더가 없는 lib 폴더의 루트에 있는 어셈블리가 무시됩니다. NuGet은 프로젝트의 대상 프레임워크에 해당하는 TFM(대상 프레임워크 모니커)과 일치하는 하위 폴더를 찾은 다음, 프로젝트에 일치하는 어셈블리를 설치합니다.

  • 잠재적 영향: 프로젝트의 대상 프레임워크에 해당하는 TFM(대상 프레임워크 모니커)과 일치하는 하위 폴더가 없는 패키지는 전환 후 예상대로 작동하지 않거나 마이그레이션 도중 설치에 실패할 수 있습니다.

문제를 발견했나요? 그렇다면 보고해주세요.

마이그레이션 환경에 문제가 발생하는 경우 NuGet GitHub 리포지토리에 문제를 보고하세요.