NuGet 플랫폼 간 플러그 인

아티클
10/18/2023

NuGet 4.8 이상에서 플랫폼 간 플러그 인에 대한 지원이 추가되었습니다. 이러한 지원은 엄격한 작업 규칙 세트를 준수해야 하는 새로운 플러그 인 확장성 모델을 빌드하여 추가되었습니다. NuGet 플랫폼 간 플러그 인은 NuGet 클라이언트가 별도의 프로세스에서 시작되는, 자체 포함 실행 파일(.NET Core 환경에서 실행 가능)입니다. 이 플러그 인은 한 번 작성하여 어디서나 플러그 인을 실행하며, 모든 NuGet 클라이언트 도구에서 작동합니다. 플러그 인은 .NET Framework(NuGet.exe, MSBuild.exe 및 Visual Studio)나 .NET Core(dotnet.exe)일 수 있습니다. NuGet 클라이언트와 플러그 인 간에 버전이 지정된 통신 프로토콜이 정의되어 있습니다. 시작 핸드셰이크 중에 두 프로세스가 프로토콜 버전을 협상합니다.

모든 NuGet 클라이언트 도구 시나리오를 다루려면 .NET Framework와 .NET Core 플러그 인이 모두 필요합니다. 아래에서는 플러그 인의 클라이언트/프레임워크 조합을 설명합니다.

클라이언트 도구	프레임워크
Visual Studio	.NET Framework
dotnet.exe	.NET Core
NuGet.exe	.NET Framework
MSBuild.exe	.NET Framework
Mono의 NuGet.exe	.NET Framework

작동 방식

개략적인 워크플로는 다음과 같이 설명됩니다.

NuGet이 사용 가능한 플러그 인을 검색합니다.
해당하는 경우 NuGet은 우선 순위에 따라 플러그 인을 반복하여 하나씩 시작합니다.
NuGet은 요청을 제공할 수 있는 첫 번째 플러그 인을 사용합니다.
더 이상 필요하지 않으면 플러그 인이 종료됩니다.

일반 플러그 인 요구 사항

현재 프로토콜 버전은 2.0.0입니다. 이 버전에서 요구 사항은 다음과 같습니다.

Windows 및 Mono에서 실행되는 신뢰할 수 있는 유효한 Authenticode 서명 어셈블리가 있어야 합니다. Linux 및 Mac에서 어셈블리 실행에 대한 특별한 신뢰 요구 사항은 아직 없습니다. 관련 문제
NuGet 클라이언트 도구의 현재 보안 컨텍스트에서 상태 비저장 시작을 지원합니다. 예를 들어 NuGet 클라이언트 도구는 나중에 설명하는 플러그 인 프로토콜 외부에서 권한 상승이나 추가 초기화를 수행하지 않습니다.
명시적으로 지정한 경우 외에는 비대화형입니다.
협상된 플러그 인 프로토콜 버전을 준수합니다.
합당한 기간 내에 모든 요청에 응답합니다.
진행 중인 작업에 대한 취소 요청을 수행합니다.

기술 사양은 다음 사양에 자세히 설명되어 있습니다.

클라이언트 - 플러그 인 상호 작용

NuGet 클라이언트 도구 및 플러그 인은 표준 스트림(stdin, stdout, stderr)을 통해 JSON과 통신합니다. 모든 데이터는 UTF-8로 인코딩되어야 합니다. 플러그 인은 “-Plugin” 인수로 시작됩니다. 사용자가 이 인수 없이 플러그 인 실행 파일을 바로 시작하는 경우 플러그 인은 프로토콜 핸드셰이크를 기다리는 대신 정보 메시지를 제공할 수 있습니다. 프로토콜 핸드셰이크 시간 제한은 5초입니다. 플러그 인은 가능한 한 짧은 시간 내에 설치를 완료해야 합니다. NuGet 클라이언트 도구는 NuGet 원본의 서비스 인덱스를 전달하여 플러그 인의 지원되는 작업을 쿼리합니다. 플러그 인은 서비스 인덱스를 사용하여 지원되는 서비스 유형이 있는지 확인할 수 있습니다.

NuGet 클라이언트 도구와 플러그 인 간의 통신은 양방향입니다. 각 요청의 시간 제한은 5초입니다. 작업이 더 오래 걸리는 경우 각 프로세스는 요청 시간이 초과되지 않도록 진행률 메시지를 보내야 합니다. 1분 동안 비활성 상태이면 플러그 인이 유휴 상태로 간주되어 종료됩니다.

플러그 인 설치 및 검색

플러그 인은 규칙 기반 디렉터리 구조를 통해 검색됩니다. CI/CD 시나리오와 고급 사용자는 환경 변수를 사용하여 동작을 재정의할 수 있습니다. 환경 변수를 사용하는 경우 절대 경로만 허용됩니다. NUGET_NETFX_PLUGIN_PATHS 및 NUGET_NETCORE_PLUGIN_PATHS은(는) 5.3 이상 버전의 NuGet 도구에서만 사용할 수 있습니다.

NUGET_NETFX_PLUGIN_PATHS - .NET Framework 기반 도구(NuGet.exe/MSBuild.exe/Visual Studio)에서 사용할 플러그 인을 정의합니다. NUGET_PLUGIN_PATHS보다 우선적으로 적용됩니다. (NuGet 버전 5.3 이상)
NUGET_NETCORE_PLUGIN_PATHS - .NET Core 기반 도구(dotnet.exe)에서 사용할 플러그 인을 정의합니다. NUGET_PLUGIN_PATHS보다 우선적으로 적용됩니다. (NuGet 버전 5.3 이상)
NUGET_PLUGIN_PATHS -해당 NuGet 프로세스에 사용할 플러그 인을 정의합니다. 우선 순위는 유지됩니다. 이 환경 변수가 설정되면 규칙 기반 검색이 재정의됩니다. 프레임워크 관련 변수 중 하나가 지정된 경우 무시됩니다.
%UserProfile%/.nuget/plugins의 NuGet 홈 위치인 사용자 위치입니다. 이 위치는 재정의할 수 없습니다. .NET Core 및 .NET Framework 플러그 인에는 다른 루트 디렉터리가 사용됩니다.

프레임워크	루트 검색 위치
.NET Core	`%UserProfile%/.nuget/plugins/netcore`
.NET Framework	`%UserProfile%/.nuget/plugins/netfx`

각 플러그 인은 해당 폴더에 설치되어야 합니다. 플러그 인 진입점은 설치된 폴더의 이름이며, .NET Core의 경우 .dll 확장명, .NET Framework의 경우 .exe 확장명을 사용합니다.

.nuget
    plugins
        netfx
            myPlugin
                myPlugin.exe
                nuget.protocol.dll
                ...
        netcore
            myPlugin
                myPlugin.dll
                nuget.protocol.dll
                ...

참고 항목

현재 플러그 인 설치에 대한 사용자 스토리가 없습니다. 필수 파일을 미리 정해진 위치로 이동하는 것만큼 간단합니다.

지원되는 작업

새 플러그 인 프로토콜에서는 두 가지 작업이 지원됩니다.

작업 이름	최소 프로토콜 버전	최소 NuGet 클라이언트 버전
패키지 다운로드	1.0.0	4.3.0
인증	2.0.0	4.8.0

올바른 런타임 중 플러그 인 실행

dotnet.exe의 NuGet 시나리오의 경우 플러그 인은 dotnet.exe의 특정 런타임 중에 실행할 수 있어야 합니다. 플러그 인 공급자와 소비자는 호환되는 dotnet.exe/플러그 인 조합이 사용되는지 확인해야 합니다. 예를 들어 2.0 런타임의 dotnet.exe가 2.1 런타임에 대해 작성된 플러그 인을 사용하려고 하면 사용자 위치 플러그 인에서 잠재적인 문제가 발생할 수 있습니다.

기능 캐싱

플러그 인의 보안 확인 및 인스턴스화는 비용이 많이 듭니다. 다운로드 작업은 인증 작업보다 더 자주 수행되지만 일반적인 NuGet 사용자에게는 인증 플러그 인만 있을 수 있습니다. 환경을 개선하기 위해 NuGet은 지정된 요청에 대한 작업 클레임을 캐시합니다. 이 캐시는 플러그 인 경로가 되는 플러그 인 키가 포함된 플러그 인을 따르며, 이 기능 캐시는 30일 후 만료됩니다.

캐시는 %LocalAppData%/NuGet/plugins-cache에 있으며 NUGET_PLUGINS_CACHE_PATH 환경 변수를 사용하여 재정의됩니다. 이 캐시를 지우려면 plugins-cache 옵션을 사용하여 로컬 명령을 실행하면 됩니다. 이제 all 로컬 옵션이 플러그 인 캐시도 삭제합니다.

프로토콜 메시지 인덱스

프로토콜 버전 1.0.0 메시지:

닫기
- 요청 방향: NuGet -> 플러그 인
- 요청에 페이로드가 포함되지 않습니다.
- 응답이 필요하지 않습니다. 플러그 인 프로세스를 즉시 종료하려면 적절한 응답이 필요합니다.
패키지의 파일 복사
- 요청 방향: NuGet -> 플러그 인
- 요청에는 다음이 포함됩니다.
  - 패키지 ID 및 버전
  - 패키지 원본 리포지토리 위치
  - 대상 디렉터리 경로
  - 대상 디렉터리 경로에 복사할 패키지의 파일 열거
- 응답에는 다음이 포함됩니다.
  - 작업의 결과를 나타내는 응답 코드
  - 작업이 성공한 경우 대상 디렉터리에 복사된 파일의 전체 경로 열거
패키지 파일 복사(.nupkg)
- 요청 방향: NuGet -> 플러그 인
- 요청에는 다음이 포함됩니다.
  - 패키지 ID 및 버전
  - 패키지 원본 리포지토리 위치
  - 대상 파일 경로
- 응답에는 다음이 포함됩니다.
  - 작업의 결과를 나타내는 응답 코드
자격 증명 가져오기
- 요청 방향: 플러그 인 -> NuGet
- 요청에는 다음이 포함됩니다.
  - 패키지 원본 리포지토리 위치
  - 현재 자격 증명을 사용하여 패키지 원본 리포지토리에서 가져온 HTTP 상태 코드
- 응답에는 다음이 포함됩니다.
  - 작업의 결과를 나타내는 응답 코드
  - 사용자 이름(사용 가능한 경우)
  - 암호(사용 가능한 경우)
패키지의 파일 가져오기
- 요청 방향: NuGet -> 플러그 인
- 요청에는 다음이 포함됩니다.
  - 패키지 ID 및 버전
  - 패키지 원본 리포지토리 위치
- 응답에는 다음이 포함됩니다.
  - 작업의 결과를 나타내는 응답 코드
  - 작업이 성공한 경우 패키지의 파일 경로 열거
작업 클레임 가져오기
- 요청 방향: NuGet -> 플러그 인
- 요청에는 다음이 포함됩니다.
  - 패키지 원본의 서비스 index.json
  - 패키지 원본 리포지토리 위치
- 응답에는 다음이 포함됩니다.
  - 작업의 결과를 나타내는 응답 코드
  - 작업이 성공한 경우 지원되는 작업(예: 패키지 다운로드) 열거 플러그 인에서 패키지 원본을 지원하지 않는 경우 플러그 인은 지원되는 빈 작업 세트를 반환해야 합니다.