Getting started

Touch Portal Documentation

Touch Portal has several resources available:

• Touch Portal Guides
• Touch Portal Blog
• Touch Portal API Documentation
• Touch Portal Discord

Writing a Plugin

Entry.tp

Before you do anything, you would need to create a entry.tp file, and pick a unique id for your plugin.

1. Create a folder under %appdata%\TouchPortal\plugins\, ex. %appdata%\TouchPortal\plugins\SamplePlugin\
2. Create or copy the entry.tp file here. With the required properties.
   (example: an absolute minimum required on the time of writing)

{
  "sdk": 3,
  "version": 1,
  "name": "Sample Plugin",
  "id": "Plugin.Id",
  "categories": []
}

Categories must be filled inn at some point. But may not be required for simple a hello world example.
Plugin.Id should be changed to some unique id.

3. Restart TouchPortal and Trust the plugin.

It should now show under the plugins dropdown in settings > plug-ins.
No code should be required yet. Actions, events, etc. you must add to categories.

Code Behind

To start the SDK you need to do tree things:

1. Implement the interface ITouchPortalEventHandler

This needs to have the pluginId from the entry.tp file.
It would also be a good idea to remove all throw new NotImplementedException(); if this is generated. Or if logging is configured, it can be filled with garbage (debug loglevel).

2. Get a client from TouchPortalFactory.CreateClient with the interface in step 1. as a parameter.

There are two extra paramteres, one for additional options, and one if you want custom logging. You can use whatever you want, ex. Serilog, but for the SDK, you need to wrap it with the ILogger abstraction interafaces.

3. .Connect(); to the client.

Now you should be good to go, and have received your first (and only of this particular type) info message.

Samples

Simple plugin:

static void Main(string[] args)
{
    var samplePlugin = new SamplePlugin();
    samplePlugin.Run();
}

public class SamplePlugin : ITouchPortalEventHandler
{
    public string PluginId => "Plugin.Id"; //Replace "Plugin.Id" with your unique id.

    private readonly ITouchPortalClient _client;

    public SamplePlugin()
    {
       //Static factory method TouchPortalFactory:CreateClient:
       //Optionally you can also provide a TouchPortalOptions,
       // or a loggerFactory parameter to configure the SDK
        _client = TouchPortalFactory.CreateClient(this);
    }

    public void Run()
    {
        _client.Connect();
    }
    ...

Plugin with ServiceProvider IoC:

static void Main(string[] args)
{
    //Build configuration:
    var configurationRoot = new ConfigurationBuilder()
        .SetBasePath(Directory.GetParent(AppContext.BaseDirectory).FullName)
        .AddJsonFile("appsettings.json")
        .Build();

    //Standard method for build a ServiceProvider in .Net:
    var serviceCollection = new ServiceCollection();
    serviceCollection.AddLogging(configure =>
    {
        configure.AddSimpleConsole(options => options.TimestampFormat = "[yyyy.MM.dd HH:mm:ss] ");
        configure.AddConfiguration(configurationRoot.GetSection("Logging"));
    });

    //Registering the Plugin to the IoC container:
    serviceCollection.AddTouchPortalSdk(configurationRoot);
    serviceCollection.AddSingleton<SamplePlugin>();

    var serviceProvider = serviceCollection.BuildServiceProvider(true);

    //Use your IoC framework to resolve the plugin with it's dependencies,
    // or you can use 'TouchPortalFactory.CreateClient' to get started manually:
    var plugin = serviceProvider.GetRequiredService<SamplePlugin>();
    plugin.Run();
}

public class SamplePlugin : ITouchPortalEventHandler
{
    public string PluginId => "Plugin.Id"; //Replace "Plugin.Id" with your unique id.
    
    private readonly ILogger<SamplePlugin> _logger;
    private readonly ITouchPortalClient _client;

    public SamplePlugin(ITouchPortalClientFactory clientFactory,
                        ILogger<SamplePlugin> logger
                        /* , additional dependencies here */)
    {
        _logger = logger;
        _client = clientFactory.Create(this);
    }

    public void Run()
    {
        _client.Connect();
    }
    ...