nuget的原理_NuGet 跨平台插件

NuGet 跨平台插件NuGet cross platform plugins

07/01/2018

本文内容

已添加 NuGet 4.8 + 跨平台插件支持。In NuGet 4.8+ support for cross platform plugins has been added.

这是通过生成新的插件扩展性模型实现的，该模型必须符合一组严格的操作规则。This was achieved with by building a new plugin extensibility model, that has to conform to a strict set of rules of operation.

这些插件是独立的可执行文件(.NET Core world 中的 runnables)，NuGet 客户端在单独的进程中启动。The plugins are self-contained executables (runnables in the .NET Core world), that the NuGet Clients launch in a separate process.

这是一次真正的写入，可在任何位置运行插件。This is a true write once, run everywhere plugin. 它将适用于所有 NuGet 客户端工具。It will work with all NuGet client tools.

插件可以是 .NET Framework (Nuget.exe、Msbuild.exe 和 Visual Studio)，也可以是 .NET Core (dotnet)。The plugins can be either .NET Framework (NuGet.exe, MSBuild.exe and Visual Studio), or .NET Core (dotnet.exe).

定义 NuGet 客户端与插件之间的版本控制通信协议。A versioned communication protocol between the NuGet Client and the plugin is defined. 在启动握手期间，2个进程会协商协议版本。During the startup handshake, the 2 processes negotiate the protocol version.

为了涵盖所有 NuGet 客户端工具方案，同时需要 .NET Framework 和 .NET Core 插件。In order to cover all NuGet client tools scenarios, one would need both a .NET Framework and a .NET Core plugin.

下面介绍插件的客户端/框架组合。The below describes the client/framework combinations of the plugins.

客户端工具Client tool

框架Framework

Visual StudioVisual Studio

.NET Framework.NET Framework

dotnet.exedotnet.exe

.NET Core.NET Core

Nuget.exeNuGet.exe

.NET Framework.NET Framework

Msbuild.exeMSBuild.exe

.NET Framework.NET Framework

Mono 上的 Nuget.exeNuGet.exe on Mono

.NET Framework.NET Framework

工作原理How does it work

高级别工作流的描述如下所示：The high level workflow can be described as follows:

NuGet 发现可用插件。NuGet discovers available plugins.

如果适用，NuGet 将按优先级顺序循环访问插件，并逐个启动插件。When applicable, NuGet will iterate over the plugins in priority order and starts them one by one.

NuGet 将使用第一个可为请求服务的插件。NuGet will use the first plugin that can service the request.

插件不再需要时将关闭。The plugins will be shut down when they are no longer needed.

一般插件要求General plugin requirements

当前协议版本为2.0.0。The current protocol version is 2.0.0.

在此版本下，要求如下所示：Under this version, the requirements are as follows:

具有有效的受信任 Authenticode 签名程序集，将在 Windows 和 Mono 上运行。Have a valid, trusted Authenticode signature assemblies that will run on Windows and Mono. 尚无对 Linux 和 Mac 上运行的程序集的特殊信任要求。There is no special trust requirement for assemblies run on Linux and Mac yet. 相关问题Relevant issue

支持在 NuGet 客户端工具的当前安全上下文下进行无状态启动。Support stateless launching under the current security context of NuGet client tools. 例如，NuGet 客户端工具不会在稍后所述的插件协议之外执行提升或其他初始化。For example, NuGet client tools will not perform elevation or additional initialization outside of the plugin protocol described later.

除非显式指定，否则为非交互式。Be non interactive, unless explicitly specified.

遵循协商插件协议版本。Adhere to the negotiated plugin protocol version.

在合理的时间段内响应所有请求。Respond to all requests within a reasonable time period.

处理任何正在进行的操作的取消请求。Honor cancellation requests for any in-progress operation.

以下规范更详细地介绍了技术规范：The technical specification is described in more detail in the following specs:

客户端-插件交互Client – Plugin interaction

NuGet 客户端工具和插件通过标准流(stdin、stdout、stderr)与 JSON 通信。NuGet client tools and the plugins communicate with JSON over standard streams (stdin, stdout, stderr). 所有数据必须采用 UTF-8 编码。All data must be UTF-8 encoded.

插件用参数 “-插件” 启动。The plugins are launched with the argument “-Plugin”. 如果用户在没有此参数的情况下直接启动了插件可执行文件，则该插件可以提供信息性消息，而不是等待协议握手。In case a user directly launches a plugin executable without this argument, the plugin can give an informative message instead of waiting for a protocol handshake.

协议握手超时值为5秒。The protocol handshake timeout is 5 seconds. 插件应尽可能简短地在中完成设置。The plugin should complete the setup in as short of an amount as possible.

NuGet 客户端工具将通过传入 NuGet 源的服务索引来查询插件支持的操作。NuGet client tools will query a plugin’s supported operations by passing in the service index for a NuGet source. 插件可以使用服务索引来检查是否存在受支持的服务类型。A plugin may use the service index to check for the presence of supported service types.

NuGet 客户端工具与插件之间的通信是双向的。The communication between the NuGet client tools and the plugin is bidirectional. 每个请求的超时为5秒。Each request has a timeout of 5 seconds. 如果操作需要更长的时间，则应发送进度消息，以防止请求超时。1分钟处于非活动状态后，插件将被视为空闲状态并关闭。If operations are supposed to take longer the respective process should send out a progress message to prevent the request from timing out. After 1 minute of inactivity a plugin is considered idle and is shut down.

插件安装和发现Plugin installation and discovery

插件将通过基于约定的目录结构来发现。The plugins will be discovered via a convention based directory structure.

CI/CD 方案和超级用户可以使用环境变量来重写此行为。CI/CD scenarios and power users can use environment variables to override the behavior. 使用环境变量时，只允许使用绝对路径。When using environment variables, only absolute paths are allowed. 请注意，NUGET_NETFX_PLUGIN_PATHS 和 NUGET_NETCORE_PLUGIN_PATHS 仅适用于 5.3 + 版本的 NuGet 工具和更高版本。Note that NUGET_NETFX_PLUGIN_PATHS and NUGET_NETCORE_PLUGIN_PATHS are only available with 5.3+ version of the NuGet tooling and later.

NUGET_NETFX_PLUGIN_PATHS-定义将由基于 .NET Framework 的工具(Nuget.exe/Msbuild.exe/Visual Studio)使用的插件。NUGET_NETFX_PLUGIN_PATHS – defines the plugins that will be used by the .NET Framework based tooling (NuGet.exe/MSBuild.exe/Visual Studio). 优先于 NUGET_PLUGIN_PATHS。Takes precedence over NUGET_PLUGIN_PATHS. (仅 NuGet 版本 5.3 +)(NuGet version 5.3+ only)

NUGET_NETCORE_PLUGIN_PATHS-定义将由基于 .NET Core 的工具(dotnet)使用的插件。NUGET_NETCORE_PLUGIN_PATHS – defines the plugins that will be used by the .NET Core based tooling (dotnet.exe). 优先于 NUGET_PLUGIN_PATHS。Takes precedence over NUGET_PLUGIN_PATHS. (仅 NuGet 版本 5.3 +)(NuGet version 5.3+ only)

NUGET_PLUGIN_PATHS-定义将用于 NuGet 进程的插件，保留优先级。NUGET_PLUGIN_PATHS – defines the plugins that will be used for that NuGet process, priority preserved. 如果设置了此环境变量，它将覆盖基于约定的发现。If this environment variable is set, it overrides the convention based discovery. 如果指定了任何一个框架特定的变量，则忽略。Ignored if either of the framework specific variables is specified.

用户-位置，%UserProfile%/.nuget/plugins中的 NuGet 主页位置。User-location, the NuGet Home location in %UserProfile%/.nuget/plugins. 此位置不能被重写。This location cannot be overriden. .NET Core 和 .NET Framework 插件将使用不同的根目录。A different root directory will be used for .NET Core and .NET Framework plugins.

框架Framework

根发现位置Root discovery location

.NET Core.NET Core

%UserProfile%/.nuget/plugins/netcore

.NET Framework.NET Framework

%UserProfile%/.nuget/plugins/netfx

每个插件都应安装在其自己的文件夹中。Each plugin should be installed in its own folder.

插件入口点将是已安装文件夹的名称，其扩展名为 .NET Core，.exe 扩展名用于 .NET Framework。The plugin entry point will be the name of the installed folder, with the .dll extensions for .NET Core, and .exe extension for .NET Framework.

.nuget

plugins

netfx

myPlugin

myPlugin.exe

nuget.protocol.dll

…

netcore

myPlugin

myPlugin.dll

nuget.protocol.dll

…

备注

当前没有用于安装插件的用户情景。There is currently no user story for the installation of the plugins. 只需将所需文件移动到预定位置即可。It’s as simple as moving the required files into the predetermined location.

支持的操作Supported operations

新的插件协议支持两个操作。Two operations are supported under the new plugin protocol.

操作名称Operation name

最低协议版本Minimum protocol version

最小 NuGet 客户端版本Minimum NuGet client version

下载包Download Package

1.0.01.0.0

4.3.04.3.0

2.0.02.0.0

4.8.04.8.0

在正确的运行时下运行插件Running plugins under the correct runtime

对于 dotnet 方案中的 NuGet，插件需要能够在 dotnet 的特定运行时执行。For the NuGet in dotnet.exe scenarios, plugins need to be able to execute under that specific runtime of the dotnet.exe.

它在插件提供程序和使用者上，以确保使用兼容的 dotnet/插件组合。It’s on the plugin provider and the consumer to make sure a compatible dotnet.exe/plugin combination is used.

用户位置插件可能会出现问题，例如，2.0 运行时下的 dotnet 尝试使用为2.1 运行时编写的插件。A potential issue could arise with the user-location plugins when for example, a dotnet.exe under the 2.0 runtime tries to use a plugin written for the 2.1 runtime.

功能缓存Capabilities caching

插件的安全验证和实例化成本高昂。The security verification and instantiation of the plugins is costly. 类似于身份验证操作，下载操作的执行频率更高，但平均 NuGet 用户只可能具有身份验证插件。The download operation happens way more frequently than the authentication operation, however the average NuGet user is only likely to have an authentication plugin.

为了改进体验，NuGet 将缓存给定请求的操作声明。To improve the experience, NuGet will cache the operation claims for the given request. 此缓存是每个插件，其中插件键是插件路径，此功能缓存的过期时间为30天。This cache is per plugin with the plugin key being the plugin path, and the expiration for this capabilities cache is 30 days.

缓存位于 %LocalAppData%/NuGet/plugins-cache 中，并通过环境变量 NUGET_PLUGINS_CACHE_PATH进行重写。The cache is located in %LocalAppData%/NuGet/plugins-cache and be overriden with the environment variable NUGET_PLUGINS_CACHE_PATH. 若要清除此缓存，可以运行带有 plugins-cache 选项的局部变量命令。To clear this cache, one can run the locals command with the plugins-cache option.

现在，all 局部变量 “选项也将删除插件缓存。The all locals option will now also delete the plugins cache.

协议消息索引Protocol messages index

协议版本1.0.0消息：Protocol Version 1.0.0 messages:

关闭Close

请求方向： NuGet > 插件Request direction: NuGet -> plugin

请求不包含有效负载The request will contain no payload

不需要响应。No response is expected. 适当的响应是为了使插件进程及时退出。The proper response is for the plugin process to promptly exit.

复制包中的文件Copy files in package

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包 ID 和版本the package ID and version

包源存储库位置the package source repository location

目标目录路径destination directory path

包中要复制到目标目录路径的文件的可枚举an enumerable of files in the package to be copied to the destination directory path

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

如果操作成功，则为目标目录中复制的文件的完整路径的可枚举an enumerable of full paths for copied files in the destination directory if the operation was successful

复制包文件(. nupkg)Copy package file (.nupkg)

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包 ID 和版本the package ID and version

包源存储库位置the package source repository location

目标文件路径the destination file path

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

获取凭据Get credentials

请求方向：插件-> NuGetRequest direction: plugin -> NuGet

该请求将包含：The request will contain:

包源存储库位置the package source repository location

使用当前凭据从包源存储库获取的 HTTP 状态代码the HTTP status code obtained from the package source repository using current credentials

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

用户名(如果可用)a username, if available

密码(如果可用)a password, if available

获取包中的文件Get files in package

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包 ID 和版本the package ID and version

包源存储库位置the package source repository location

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

如果操作成功，则为包中的文件路径的可枚举an enumerable of file paths in the package if the operation was successful

获取操作声明Get operation claims

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包源的服务索引 jsonthe service index.json for a package source

包源存储库位置the package source repository location

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

如果操作成功，则为支持的操作(如包下载)的可枚举。an enumerable of supported operations (e.g.: package download) if the operation was successful. 如果插件不支持包源，则该插件必须返回一组支持操作的空集。If a plugin does not support the package source, the plugin must return an empty set of supported operations.

备注

此消息已在版本2.0.0中更新。This message has been updated in version 2.0.0. 它在客户端上，用于保留向后兼容性。It is on the client to preserve backward compatibility.

获取包哈希Get package hash

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包 ID 和版本the package ID and version

包源存储库位置the package source repository location

哈希算法the hash algorithm

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

如果操作成功，则使用所请求的哈希算法的包文件哈希a package file hash using the requested hash algorithm if the operation was successful

获取包的版本Get package versions

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包 IDthe package ID

包源存储库位置the package source repository location

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

如果操作成功，则为包版本的可枚举an enumerable of package versions if the operation was successful

获取服务索引Get service index

请求方向：插件-> NuGetRequest direction: plugin -> NuGet

该请求将包含：The request will contain:

包源存储库位置the package source repository location

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

如果操作成功，则为服务索引the service index if the operation was successful

握手Handshake

请求方向： NuGet < > 插件Request direction: NuGet plugin

该请求将包含：The request will contain:

当前插件协议版本the current plugin protocol version

支持的最低插件协议版本the minimum supported plugin protocol version

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

如果操作成功，则协商协议版本。the negotiated protocol version if the operation was successful. 失败将导致插件终止。A failure will result in termination of the plugin.

InitializeInitialize

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

NuGet 客户端工具版本the NuGet client tool version

NuGet 客户端工具的有效语言。the NuGet client tool effective language. 如果使用，此操作将考虑 ForceEnglishOutput 设置。This takes into consideration the ForceEnglishOutput setting, if used.

默认请求超时值，它取代协议默认值。the default request timeout, which supersedes the protocol default.

响应将包含：A response will contain:

指示操作结果的响应代码。a response code indicating the outcome of the operation. 失败将导致插件终止。A failure will result in termination of the plugin.

日志Log

请求方向：插件-> NuGetRequest direction: plugin -> NuGet

该请求将包含：The request will contain:

请求的日志级别the log level for the request

要记录的消息a message to log

响应将包含：A response will contain:

指示操作结果的响应代码。a response code indicating the outcome of the operation.

监视 NuGet 进程退出Monitor NuGet process exit

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

NuGet 进程 IDthe NuGet process ID

响应将包含：A response will contain:

指示操作结果的响应代码。a response code indicating the outcome of the operation.

预提取包Prefetch package

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包 ID 和版本the package ID and version

包源存储库位置the package source repository location

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

设置凭据Set credentials

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包源存储库位置the package source repository location

最后一个已知包源用户名(如果可用)the last known package source username, if available

最后一个已知包源密码(如果可用)the last known package source password, if available

最后一个已知代理用户名(如果可用)the last known proxy username, if available

最后一个已知代理密码(如果可用)the last known proxy password, if available

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

设置日志级别Set log level

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

默认日志级别the default log level

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

协议版本2.0.0消息Protocol Version 2.0.0 messages

获取操作声明Get Operation Claims

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

包源的服务索引 jsonthe service index.json for a package source

包源存储库位置the package source repository location

响应将包含：A response will contain:

指示操作结果的响应代码a response code indicating the outcome of the operation

如果操作成功，则为支持的操作的可枚举。an enumerable of supported operations if the operation was successful. 如果插件不支持包源，则该插件必须返回一组支持操作的空集。If a plugin does not support the package source, the plugin must return an empty set of supported operations.

如果服务索引和包源为 null，则该插件可以通过身份验证进行应答。If the service index and package source are null, then the plugin can answer with authentication.

获取身份验证凭据Get Authentication Credentials

请求方向： NuGet > 插件Request direction: NuGet -> plugin

该请求将包含：The request will contain:

URIUri

isRetryisRetry

NonInteractiveNonInteractive

CanShowDialogCanShowDialog

响应将包含A response will contain

用户名Username

PasswordPassword

MessageMessage

身份验证类型列表List of Auth Types

MessageResponseCodeMessageResponseCode