NuGet 서버 구현 가이드

경우에 따라 고유한 NuGet 패키지 피드를 구현할 수 있습니다. 다양한 방식으로 자체 피드를 호스트할 수 있는 많은 기존 구현 이 있지만 공식 NuGet 클라이언트 소프트웨어와 패키지 피드 간의 프로토콜을 문서화하여 자체 피드 구현을 처음부터 빌드할 수 있습니다.

프로토콜은 시간이 지남에 따라 진화하며 이 가이드는 NuGet 패키지 서버를 구현하려고 하거나 이미 구현한 프로토콜을 대상으로 합니다.

2015년 NuGet V3 프로토콜의 초기 릴리스 이후 NuGet은 개발자에게 더 풍부한 환경을 제공하기 위해 발전해 왔으며, 이를 위해서는 패키지 리포지토리가 호스트된 패키지의 메타데이터를 정확하게 지정하고 다양한 형식으로 메타데이터를 반환하는 것 외에도 패키지 소비자에게 추가적인 가치를 제공하기 위해 추가 작업을 수행해야 합니다. 예를 들어 검색 및 패키지 메타데이터 엔드포인트에는 nupkg의 nuspec 파일에 있는 메타데이터 이상이 포함됩니다.

이 가이드는 V2 프로토콜이 기본적으로 문서화되지 않았기 때문에 NuGet V3 프로토콜에 중점을 두며, 2015년부터 NuGet 클라이언트 및 서버 통신에 권장되는 프로토콜은 V3 프로토콜입니다. 자세한 내용은 프로토콜 버전 관리 방법에 대해 읽어보세요.

연대기

기존 NuGet 리포지토리의 작성자가 NuGet의 최신 기능을 최신 상태로 유지할 수 있도록 지원하기 위해, 다음은 문서의 다시 기본더에 멘션 관련 기능의 연대기입니다.

소유자 필드

패키지 매니페스트 파일(.nuspec) 필드 <authors> 와 <owners>. 타사 콘텐츠를 패키징하는 패키지 작성자는 종종 타사 이름을 필드에 배치합니다 <authors> . 이 <owners> 필드는 리포지토리에 패키지를 게시한 사용자와 압축 문제 또는 질문의 경우 연락해야 하는 사용자를 나타내기 위한 것이었습니다.

이는 2013년 블로그 게시물에서 설명되었으므로 <owners> 이 필드는 파일에서 .nuspec 더 이상 사용되지 않는 것으로 간주됩니다. 패키지의 매니페스트에 이 메타데이터가 포함되어 있으면 무시해야 합니다. 검색 리소스 또는 패키지 메타데이터 리소스 JSON 응답의 <owners> 속성에 있는 owners파일 필드 값을 .nuspec 반환하지 마세요.

리포지토리에 패키지별 권한이 있는 경우 검색 및 패키지 메타데이터 리소스 JSON 응답을 위해 메타데이터에 새 버전을 게시할 수 있는 권한이 있는 owner 계정을 보고하는 것이 좋습니다.

verified 검색 응답 필드

Visual Studio의 패키지 관리자 UI는 새 필드 verified 가 설정된 경우 검색 서비스 결과의 패키지 옆에 파란색 검사 표시를 표시합니다true.

NuGet.org 패키지 접두사 데이터(NuGet API의 일부가 아닌 서버 쪽 데이터)와 함께 사용하므로 패키지를 소유한 계정이 패키지를 업로드한 경우에만 이 검사 표시가 고객에게 표시됩니다. 예를 들어 접두사를 microsoft.* 가진 패키지는 nuget.org Microsoft 계정에서 패키지를 소유하는 경우에만 확인됩니다. 예약된 접두사를 구현하기 전에 패키지 ID가 microsoft. 있는 패키지를 업로드한 사람은 이 확인 검사mark가 없습니다. 또한 NuGet.org 접두사를 배타적이지 않도록 허용하므로 누구나 패키지를 Contoso.ToolWithPlugins.Community.*업로드할 수 있지만 확인된 검사 표시를 얻지 않습니다.

의미 체계 버전 관리 2.0.0 지원

NuGet은 의미 체계 버전 간 System.Version 하이브리드를 지원하지만 의미 체계 버전 2.0.0에 대한 지원은 2017년에 추가되었습니다. 따라서 3.6.0보다 낮은 클라이언트 버전으로 버전을 반환하는 NuGet API 리소스는 의미 체계 버전 1.0.0과 호환되지 않는 의미 체계 2.0.0 기능을 사용하는 패키지를 반환해서는 안 됩니다.

두 버전 간의 가장 중요한 차이점은 시험판 레이블과 메타데이터 문자열입니다. 의미 체계 버전 관리 1.0.0 사양은 시험판 레이블의 일부로 허용되는 유일한 문자에 대한 샘플 정규식 문자열로 제공 [0-9A-Za-z-] 되며 메타데이터 문자열을 지원하지 않습니다. 의미 체계 버전 관리 2.0.0 사양을 사용하면 시험판 식별자를 문자로 . 구분하고 숫자 식별자가 선행 0이 없도록 할 수 있으며, 또한 다음에 빌드 메타데이터를 추가할 +수 있습니다.

패키지 메타데이터 리소스(RegistrationsBaseUrl)에서 3.6.0 미만의 리소스 버전은 준수 패키지만 반환해야 합니다. NET 또는 System.Version 의미 체계 버전 관리 1.0.0. 즉, 버전이 의미 체계 버전 2.0.0만 준수하는 패키지는 이러한 클라이언트 버전에 표시되지 않습니다.

마찬가지로 검색 쿼리 서비스(SearchQueryService) 및 자동 완성 서비스()가 쿼리 매개 변수를SearchAutocompleteService 추가 &semVerLevel={version} 했습니다. 누락된 경우 semVerLevel 값을 가정합니다 1.0.0. 패키지 메타데이터 리소스와 마찬가지로 버전이 의미 체계 버전 2.0.0과만 호환되는 패키지는 값이 2.0.0 미만일 때 semVerLevel 반환되지 않아야 합니다.

포함된 파일

패키지 아이콘, 라이선스 및 추가 정보 파일은 패키지에 포함될 수 있으며 권장됩니다. 이러한 파일에는 정적 파일 서버에서 추출하여 배치하는 URL 엔드포인트 또는 요청에서 .nupkg 파일을 동적으로 추출하여 전체 nupkg파일을 다운로드하지 않고 볼 수 있는 URL이 필요합니다. 패키지 리포지토리에서 패키지 검색 및 패키지 세부 정보 보기를 제공하는 경우 URL을 사용하여 웹 사이트에 포함된 콘텐츠를 고객에게 표시할 수 있습니다.

마지막으로 패키지 메타데이터 리소스 및 검색 리소스는 JSON 응답의 , licenseUrl및/또는 readmeUrl 속성에 iconUrl호스트된 URL을 포함해야 합니다. 클라이언트 기능(잠금 파일 및 서명된 패키지)은 패키지가 변조된 대로 수정을 검색하므로 패키지(.nupkg 파일)를 수정해서는 안 됩니다.

라이선스는 SPDX 식 또는 포함된 파일(둘 다 아님)일 수 있습니다. 라이선스 식을 사용하는 패키지는 검색 및 패키지 메타데이터 결과에 표시될 때 라이선스 식, URL 인코딩 및 끝에 https://licenses.nuget.org/추가할 수 있습니다licenseUrl. 예들 들어 https://licenses.nuget.org/Apache-2.0입니다. NuGet.org 서버 팀에는 licenses.nuget.org 대한 추가 설명서가 있습니다.

알려진 취약성 및 사용 중단 데이터

패키지 메타데이터 리소스(RegistrationsBaseUrl)

패키지 메타데이터 리소스에는 사용 중단 및 취약성 정보가 포함될 수 있습니다. 이렇게 하면 Visual Studio의 패키지 관리자 사용자 인터페이스 또는 다른 IDE에 해당하는 패키지를 검색하는 고객이 중요한 보안 또는 기본 테넌트 문제에 대한 알림을 받을 수 있습니다.

패키지 리포지토리가 다른 리포지토리에서 패키지를 "업 소싱"하는 경우 사용자 고유의 피드에 패키지를 미러 위해 사용 중단 또는 취약성 데이터가 있는 경우 원본 원본을 주기적으로 검사 해당 메타데이터를 사용자 고유의 리포지토리에 미러 것이 좋습니다. 패키지 리포지토리가 nuget.org 특히 검사 마지막 시간("커서")의 상태를 유지하여 리소스를 사용하여 Catalog 업스트림 피드에서 많은 수의 패키지 메타데이터 JSON 파일을 다운로드하지 않고도 미러 패키지에 대한 패키지 업데이트가 있는 경우 효율적으로 검사 수 있습니다. 시작하는 데 도움이 되는 샘플 코드와 함께 카탈로그 리소스를 사용하는 방법에 대한 가이드가 있습니다.

알려진 취약성 데이터베이스(VulnerabilityInfo)

패키지 복원 중에 고성능 취약성 검사를 제공하기 위해 NuGet은 리소스에서 VulnerabilityInfo 알려진 취약성의 전체 목록을 다운로드합니다. Nuget.org gitHub Advisories 데이터베이스에서 검토된 모든 GitHub 권고에 대한 취약성 데이터를 제공합니다. 여기에는 nuget.org 호스트되지 않는 패키지가 포함됩니다.

패키지 리포지토리가 자사 패키지를 호스팅하고 있으며 사용자 고유의 피드를 사용하여 고객에게 취약성 정보를 제공하려고 하지만 아직 공개된 패키지 취약성이 없는 경우 콘텐츠가 빈 JSON 배열([])인 하나 이상의 취약성 페이지로 취약성 인덱스를 제공해야 합니다.

패키지 리포지토리가 앱에서 기본 리포지토리로 사용되는 경우(nuget.org 대신) nuget.org의 취약성 데이터를 사용할 수 있습니다. 한 가지 옵션은 서비스 인덱스에서 nuget.org의 취약성 인덱스 URL을 사용하는 것입니다. 또 다른 옵션은 nuget.org의 VulnerabilityInfo 인덱스 주기적으로 검사 변경된 페이지를 다운로드하여 로컬로 미러 것입니다.

packageTypes 검색 쿼리

.NET CLI를 사용하면 명령을 사용하여 .NET 도구 패키지를 검색할 dotnet tool search 수 있습니다. 이는 패키지의 .nuspec 파일 <packageTypes> 필드에서 값을 읽는 쿼리 매개 변수를 검색 쿼리 리소스에 추가하여 &packageTypes={value} 구현됩니다.

인증된 피드의 URL 구조

NuGet API 개요에 설명된 대로 모든 NuGet 서버 통신의 시작 URL은 서비스 인덱스입니다. 이 문서에는 NuGet 클라이언트가 쿼리할 다른 모든 리소스에 대한 URL이 포함되어 있습니다. NuGet 6.7(Visual Studio 및 MSBuild 17.7 및 .NET SDK 7.0.400)을 기준으로 NuGet에서 사용합니다 . NET은 후속 URL이 이전에 인증된 URL의 HttpClientHandler.PreAuthenticate동일한 가상 디렉터리 또는 하위 디렉터리에 있는 경우에만 익명 HTTP 요청을 방지합니다. 이렇게 하면 서버로 전송되는 인증되지 않은 HTTP 요청 수가 크게 감소하므로 서버 워크로드가 줄어듭니다.

다음 몇 가지 예를 참조하세요.

마지막 예제에서 서버에 정식(이 예제에서는 guid) 이름이 있고 하나 이상의 별칭이 있을 수 있습니다. 서비스 인덱스 요청이 정식이 아닌 URL(이 예제feed의 "친숙한" 이름)에서 인증된 경우 정식 URL 아래의 리소스에 대한 PreAuthenticate모든 요청이 '의 규칙과 일치하지 HttpClientHandler않습니다. 그러나 정식 URL이 아닌 URL이 정식 URL에 대한 HTTP 리디렉션인 경우 이 URL https://pkgs.contoso.com/nuget/v3/{guid}/index.json은 '의 자격 증명 캐시에 HttpClientHandler사용됩니다. 이 경우 서비스 인덱스로의 모든 요청에는 리디렉션으로 인해 추가 대기 시간이 있습니다.

NuGet의 V3 API는 정적 파일 서버에서 작동하도록 설계되었지만 검색 리소스는 항상 동적 웹 서비스가 요청을 처리해야 하는 예외입니다. 다른 서버에서 HttpClientHandlerPreAuthenticate검색 또는 실제로 다른 NuGet API 리소스를 호스트하려는 경우 역방향 프록시를 사용하여 서비스 인덱스의 모든 고객 연결 URL이 "동일하거나 하위 디렉터리" 규칙을 충족하도록 해야 합니다.