TXTextControl.DocumentServices.Plugin.Abstractions 4.1.0

TXTextControl.DocumentServices.Plugin.Abstractions

TXTextControl.DocumentServices.Plugin.Abstractions defines the shared interface and plugin lifecycle for building external plugin assemblies that extend the functionality of Text Control DS Server.

This package allows developers to build .dll plugins that:

• Register custom ASP.NET Core API controllers
• Add middleware or route handlers
• Access DS Server configuration and services
• Execute startup/shutdown logic

✨ Features

• Controller-based plugins: Add custom API endpoints
• Lifecycle hooks: Initialize and clean up plugin logic
• Service registration: Register your own services into the DI container
• Middleware support: Add request interceptors, metrics, logging, etc.

📦 NuGet

dotnet add package TXTextControl.DocumentServices.Plugin.Abstractions

📜 Interface Overview

namespace TXTextControl.DocumentServices.Plugin.Abstractions;

public interface IPlugin {
    string Name { get; }
    string Description { get; }
    string Version { get; }

    string UIBasePath => null; // Optional, for plugins with a web UI (e. g. /plugin-ui/config)

    void ConfigureServices(IServiceCollection services, PluginContext context) { }
    void ConfigureMiddleware(WebApplication app, PluginContext context) { }
    void OnStart(IServiceProvider services, PluginContext context) { }
    void OnStop() { }
}

PluginContext provides metadata about the DS Server environment:

public class PluginContext {
    public string DsServerVersion { get; set; } = default!;
    public string BaseDirectory { get; set; } = default!;
    public IConfiguration Configuration { get; set; } = default!;
}

🚀 Getting Started

To create a basic plugin with a controller and custom middleware, follow these steps:

1. Create a new class library project

dotnet new classlib -n MyFirstPlugin
cd MyFirstPlugin

2. Add the abstraction package

dotnet add package TXTextControl.DocumentServices.Plugin.Abstractions

3. Define a service to hold config state

public class GreetingState {
    public string Greeting { get; set; } = "Hello (default)";
}

4. Create a controller

This controller will respond to requests at /plugin/hello:

using Microsoft.AspNetCore.Mvc;

namespace MyFirstPlugin;

[ApiController]
[Route("plugin/[controller]")]
public class HelloController : ControllerBase {
    private readonly GreetingState m_state;

    public HelloController(GreetingState state) {
        m_state = state;
    }

    [HttpGet]
    public string Get() => m_state.Greeting;
}

5. Implement the plugin class

This class implements the IPlugin interface, reads the greeting text from the configuration and registers a middleware to log requests:

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using TXTextControl.DocumentServices.Plugin.Abstractions;

namespace MyFirstPlugin;

public class HelloPlugin : IPlugin {
    public string Name => "MyFirstPlugin";
    public string Description => "Adds a /plugin/hello endpoint and logs requests.";
    public string Version => "1.0.0";

    public void ConfigureServices(IServiceCollection services, PluginContext context) {
        // Retrieve the greeting from the configuration and register it as a singleton service.
        // This is just an example. Implementing ConfigureServices is optional.
        var greeting = context.Configuration["MyFirstPlugin:Greeting"] ?? "Hello (default)";
        services.AddSingleton(new GreetingState { Greeting = greeting });
    }

    public void ConfigureMiddleware(WebApplication app, PluginContext context) {
        // Register a middleware to log requests to the /plugin/hello endpoint.
        // This is also just an example. Implementing ConfigureMiddleware is optional.
        app.Use(async (ctx, next) => {
            if (ctx.Request.Path.StartsWithSegments("/plugin/hello")) {
                var logger = ctx.RequestServices.GetRequiredService<ILogger<HelloPlugin>>();
                logger.LogInformation("MyFirstPlugin intercepted request to /plugin/hello");
            }
            await next();
        });
    }

    public void OnStart(IServiceProvider services, PluginContext context) {
        // This method is called when the plugin is started. You can use this to 
        // initialize resources or perform startup logic. Implementing OnStart is optional.
        var logger = services.GetService<ILogger<HelloPlugin>>();
        var state = services.GetService<GreetingState>();
        logger?.LogInformation("Plugin started. Greeting: {Greeting}", state?.Greeting);
    }

    public void OnStop() {
        // Cleanup logic if needed. This is also optional.
    }
}

🔧 Add optional plugin settings

If your plugin expects config settings, add them to appsettings.json in DS Server:

"MyFirstPlugin": {
    "Greeting": "Howdy from DS Server!"
}

🧪 Deploy and test the plugin

1. Build your plugin:

dotnet build

2. Create a subfolder inside the Plugins/ directory of your DS Server installation (e.g. Plugins/SamplePlugin/)
3. Copy the resulting .dll file (e.g. bin/Debug/net8.0/MyFirstPlugin.dll) into that subfolder:

Plugins/
└── SamplePlugin/
    └── MyFirstPlugin.dll

3. Restart DS Server.
4. Access the plugin endpoint:

GET http://<your-server>/plugin/hello

📝 Notes

• All plugins must contain at least one public class implementing IPlugin
• Controllers must be decorated with [ApiController] and route attributes
• Middleware is registered per plugin via ConfigureMiddleware
• Services are injected using standard ASP.NET Core DI
• DS Server will invoke each lifecycle method (ConfigureServices, ConfigureMiddleware, OnStart, OnStop) at the appropriate phase

🛡 License

This package is provided under the MIT License. See LICENSE.md for details.

📣 About Text Control DS Server

Text Control DS Server is a powerful on-premise backend for generating, viewing, editing, and signing documents — complete with extensive mail merge and reporting capabilities — accessible via REST APIs or integrated custom logic through plugins like this one. Try it out today and see how it can enhance your document processing workflows!