Prise Plugin Framework

To create a plugin that the Host can discover, follow these requirements:

1. Project Setup: Create a class library (e.g., netcoreapp3.1 or higher) and add the Prise.Plugin NuGet package and a reference to your shared Contract.

   dotnet add package Prise.Plugin
   dotnet add reference ../Your.Contract

2. Implement the Contract: Create a class that implements the interface defined in your Contract.

3. Decorate with [Plugin] attribute: You must annotate your plugin class with the [Plugin] attribute, specifying the PluginType (the interface from your Contract). This makes the plugin discoverable by Prise.

Note: Implementation of the interface methods is optional as long as the class exposes the correct method signature (name, parameters, and return type) that matches the Contract, as Prise can invoke plugins via reflection.

[Plugin(PluginType = typeof(IWeatherPlugin))]
public class OpenWeatherPlugin : IWeatherPlugin
{
    public async Task<IEnumerable<WeatherForecast>> GetWeatherFor(string location)
    {
        // Implementation logic
    }
}

To unit test a plugin, use the Prise.Testing package to simulate the Prise environment. The CreateTestPluginInstance<T> method allows you to instantiate a plugin and automatically inject mock or real services into its [PluginService] fields.

Setup:

1. Create an MSTest project.
2. Add Prise.Testing and Moq packages.
3. Reference your Plugin project.
4. Use CreateTestPluginInstance<T>(params object[] services) to create the test instance.

// Example test using Moq and Prise.Testing
var openWeatherServiceMock = new Mock<IOpenWeatherService>(MockBehavior.Strict);
var converterService = new ConverterService();

// Mock setup...
openWeatherServiceMock.Setup(w => w.GetForecastsFor(city)).ReturnsAsync(responseModel);

// Prise.Testing injects the mocks into the plugin fields
var plugin = Prise.Testing.CreateTestPluginInstance<OpenWeatherPlugin>(openWeatherServiceMock.Object, converterService);

var results = await plugin.GetWeatherFor(city);
Assert.AreEqual(description, results.First().Summary);

Plugins often need access to Host-level data or configuration. To share a service from the Host to a Plugin, follow these steps:

1. Define an interface in the Contract: The interface must be part of the shared contract project.
2. Implement the service in the Host: Register the implementation in the Host's IServiceCollection.
3. Configure the Load Context: When calling IPluginLoader.LoadPlugin<T>(), use the configure parameter to add the host service to the plugin's load context using loadContext.AddHostService<T>(instance).
4. Use a ReverseProxy in the Plugin: To maintain compatibility and allow the plugin to call back into the host, implement the interface in the plugin using a class that inherits from Prise.ReverseProxy.

// In the Host: Loading the plugin and sharing a service
var plugin = await this.weatherPluginLoader.LoadPlugin<IWeatherPlugin>(scanResult, configure: (loadContext) =>
{
    loadContext.AddHostService<IConfigurationService>(this.configurationService);
});

// In the Plugin: Implementing the proxy
public class ConfigurationServiceProxy : ReverseProxy, IConfigurationService
{
    public ConfigurationServiceProxy(object hostService) : base(hostService) { }

    public string GetConfigurationValueForKey(string key)
    {
        return this.InvokeOnHostService<string>(key);
    }
}

To use Prise in an ASP.NET Core application, follow these steps:

1. Install the NuGet package:

   dotnet add package Prise

2. Add the Contract reference: Add a project reference to your shared Contract library.

   dotnet add reference ../Your.Contract

3. Register Prise services: In your Startup.cs (or Program.cs for newer templates), call AddPrise() within the ConfigureServices method:

   public void ConfigureServices(IServiceCollection services)
   {
       services.AddControllers();
       services.AddPrise();
   }

4. Inject IPluginLoader: Inject the IPluginLoader into your controllers or services to find and load plugins at runtime.

public class WeatherForecastController : ControllerBase
{
    private readonly IPluginLoader weatherPluginLoader;

    public WeatherForecastController(ILogger<WeatherForecastController> logger, IPluginLoader weatherPluginLoader)
    {
        this.weatherPluginLoader = weatherPluginLoader;
    }
}