Restore & Resolve Plugins

[Cryptoc1]

Enable restoration and resolution of plugin assemblies from ThunderDependency items.

To support restore, additional Sdk properties have been added:

Property	Description
PluginManager1	The mod manager in use, intended for use with PluginStagingProfile. Possible values: r2modman, '' (implies Thunderstore)
PluginManagerDataDir1	The directory of the mod manager's game data folder, e.g. $(AppData)\Thunderstore Mod Manager\DataFolder\LethalCompany\. Default value is determined based on $(PluginManager). Must end in a trailing slash.
PluginCacheDir	The directory plugins are restored to. Defaults to $(PluginManagerDataDir)cache\ if the PLUGIN_SDK_CACHE2 is not defined. Must end in a trailing slash
PluginInfoTypeModifiers	Renamed PluginInfoTypeAccessModifier (backwards compatible)
RestorePluginsWithLockFile	Indicates whether a plugins.lock.json file should be used for restore. Defaults to $(RestorePackagesWithLockFile).
PluginLockFile	Intended for internal use. The absolute path to the plugins.lock.json file. Defaults to $(MSBuildProjectDirectory)\plugins.lock.json if $(RestorePluginsWithLockFile) evaluates to true, empty otherwise
PluginAssetsFile	Intended for internal use. The absolute path to the plugin.assets.json file. Defaults to $(BaseIntermediateOutputPath)plugin.assets.json
PluginRestoreOutputs	Intended for internal use. A semi-colon delimited list of files touched by the RestorePlugins Target.

¹ Addresses #1.
² The PLUGIN_SDK_CACHE Environmental Variable can be used in CI along with <RestorePluginWithLockFile /> to enable caching, e.g. with actions/cache.

Plugin Restoration & Assembly Resolution

A RestorePlugins MSBuild Target has been added that runs before the default Restore which executes the RestorePluginDependencies Task, which evaluates the provided @(ThunderDependency) items, resolving a dependency graph of direct and transitive plugins, and restoring (download+extract) them to the $(PluginCacheDir). The implemention of RestorePluginDependencies is intended to be similar to NuGet restore functionality.

If $(RestorePluginsWithLockFile) evaluates to true, a plugins.lock.json file is generated in the project root representing the resolved dependency graph; this file is used for speeding up and ensuring consistency across restores.

If $(RestoreLockedMode) (e.g. dotnet restore --locked-mode) evaluates to true, the Sdk expects a plugins.lock.json file to exist in the project root, which is used rather than resolving a dependency graph.

When the RestorePlugins target succeeds, a plugin.assets.json file is generated containing a listing of assets for each restored plugin.

The plugin.assets.json file is evaluated by the ResolvePluginAssemblies task, prior to the Compile and ResolveReferences targets, via the ResolvePluginReferences target. Upon evaluation of the assets file, the ResolvePluginReferences target adds Reference items for the resolved plugin assemblies.

The listing of assets contained in plugin.assets.json is evaluated based on the ExcludeAssets/IncludeAssets metadata of the ThunderDependency item of a plugin. For example if the plugin ExampleTeam-ExamplePlugin contained assemblies in a plugins\ignored\ directory that are unwanted, they may be excluded with the glob pattern plugins\ignored\*.dll:

<ThunderDependency Include="ExampleTeam-ExamplePlugin" Version="1.0.0">
  <ExludeAssets>plugins\ignore\*.dll</ExcludeAssets>
</ThunderDependency>

The default IncludeAssets patterns are: *.dll, plugins\**\*.dll, BepInEx\core\**\*.dll, BepInEx\plugins\**\*.dll

Manifest & PluginInfo Generation

PluginInfo code and Thunderstore manifest generation have been re-implemented as MSBuild Tasks as well. With this, manifest generation now includes validation of generated values, such as the name.