diff --git a/documentation/Plugins-System-Preview-Only/Plugins-System-Components-Preview-Only.md b/documentation/Plugins-System-Preview-Only/Plugins-System-Components-Preview-Only.md new file mode 100644 index 00000000..6bd2c3a6 --- /dev/null +++ b/documentation/Plugins-System-Preview-Only/Plugins-System-Components-Preview-Only.md @@ -0,0 +1,108 @@ +## Plugins System Components + +The **Plugins System** is a modular and extensible architecture that provides a flexible way to manage plugins in an application. It consists of several key components, such as the `IPluginsInstaller`, `IPluginsDiscoveryOrchestrator`, `IPluginsSystemResourceLoader`, `IRepository`, `IObsoletePluginsRemover`, and `IInstalledPluginLoader`, that work together to enable the discovery, installation, uninstallation and loading of plugins at runtime. The composition-based design promotes the use of composition over inheritance, allowing for extensible plugin management through the use of loosely-coupled components that can be easily replaced or extended without modifying the core logic of the system. This documentation provides an overview of the key components of the **Plugins System** and its functionalities. + +### Components of the Plugins System +The Plugin System consists of the following components: + +1. **IPluginsInstaller** + + The `IPluginsInstaller` interface is responsible for installing plugins, uninstalling plugins and listing installed plugins. It supports installing from various sources given that a **plugin package** stream is provided. + +2. **IPluginsDiscoveryOrchestrator** + + The `IPluginsDiscoveryOrchestrator` interface is responsible for orchestrating the discovery process of plugins. This component interacts with various **plugin source**s and different discovery mechanisms to discover available plugins. + +3. **IPluginsSystemResourceLoader\** + + The `IPluginsSystemResourceLoader` interface is responsible for loading resources required by the plugin system, such as assemblies, configuration files, or other resources, from different sources. The T type parameter represents the type of resources to be loaded, such as `IPluginDiscovererProvider` or `IPluginFetcher`. + + - **IPluginDiscovererProvider** represents a plugin system resource that creates `IPluginDiscoverer` for supported plugin sources. + - **IPluginDiscoverer** represents a component that discovers available plugins from a *single* plugin source. + + - **IPluginFetcher** represents a plugin system resource that is capable of fetching the plugin package from a discovered plugin. + + For the `IPluginsDiscoveryOrchestrator` to discover plugins, at least one `IPluginDiscovererProvider` and the supporting `IPluginFetcher`(s) need to be loaded into the system. + +4. **IRepository\** + + The `IRepository` interface is responsible for managing plugin sources provided by a plugin consumer. It supports adding and removing sources as well as notifying these changes. + +5. **IObsoletePluginsRemover** + + The `IObsoletePluginsRemover` is responsible for determining which plugins are considered obsolete and removing the binaries from the application. + +6. **IInstalledPluginLoader** + + The `IInstalledPluginLoader` interface is responsible for loading installed plugins into the application. + + +### Usage + +#### Construct a Plugins System +Creating a **Plugins System** requires all the components mentioned above provided. A client can either provide their custom implementation or use the default file system-based implementation provided by `Microsoft.Performance.Toolkit.Plugins.Runtime`. A file system directory is required which will be the root directory of the installed plugins. Additionally, a plugin loading callback and a logger factory need to be provided. + +```CSharp +using Microsoft.Performance.Toolkit.Plugins.Runtime + +var ps = PluginsSystem.CreateFileBasedPluginsSystem( + @"\InstallationRoot", + (pluginDir) => pluginsLoader.LoadPlugin(pluginDir), + (t) => Logger.Create(t)); +``` + +#### Discover Plugins +1. Add a plugin source + +```CSharp +ps.PluginSourceRepository.Add(new PluginSource(new Uri(@"http://fakeazure.com/1"))); +``` + +2. Add a discoverer provider and a fetcher +```CSharp +ps.DiscovererProviderResourceLoader.Add(new AzurePluginDiscovererProvider()); +ps.FetcherResourceLoader.Add(new AzurePluginFetcher()); +``` + +3. Discover all available plugins in their latest version from `"http://fakeazure.com/1"` +```CSharp +var plugins_latest = await ps.Discoverer.GetAvailablePluginsLatestAsync(CancellationToken.None); +``` + +4. Discover all versions of a particular plugin from `"http://fakeazure.com/1"` +```CSharp +var plugins_allVersions = await ps.Discoverer.GetAllVersionsOfPluginAsync( + plugins_latest.First().Info.Identity, CancellationToken.None); +``` + +#### Install and Uninstall Plugins +1. Install a discovered plugin +```CSharp +await ps.InstallAvailablePlugin( + plugins_latest.First(), + CancellationToken.None, + null, + Logger.Create()); +``` + +2. Install a local plugin package +```CSharp +using var stream = File.OpenRead(pluginPackagePath); +var installedPlugin = await ps.Installer.InstallPluginAsync( + stream, + new Uri(pluginPackagePath), + CancellationToken.None, + null +) +``` +3. Uninstall a plugin +```CSharp +await ps.Installer.UninstallPluginAsync( + installedPlugin, + CancellationToken.None) +``` +4. List all installed plugins +```CSharp +var allInstalledPlugins = await ps.Installer.GetAllInstalledPluginsAsync( + CancellationToken.None) +``` \ No newline at end of file