TouchPortal-CS-API 1.44.2

Touch Portal C# API

Originally a fork of https://github.com/oddbear/TouchPortalSDK, optimized for performance, usability, and good behavior (eg. not crashing on exit). See further details below.

Touch Portal API for making plugins with C#

Built based on documentation at Touch Portal Plugin API.

Getting started:

The simplest way of getting started, is to implement the ITouchPortalEventHandler and use TouchPortalFactory to create a client. And then Connect to Touch Portal before sending or receiving events.

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

    private readonly ITouchPortalClient _client;

    public SamplePlugin()
    {
        _client = TouchPortalFactory.CreateClient(this);
    }

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

More information on the original Wiki, or see the Sample project in this repository.

Compatibility With Original

Drop-in replacement for oddbear's TouchPortalSDK as of his v0.30.0-beta2, except:

• The ActionEvent.Data property, which was an array or key-value pairs, is now a Dictionary<string, string> with each data ID mapped to its corresponding value. See the SamplePllugin.cs changes on this commit for how to update (but now you can also message.Data.TryGetValue("myDataId", out string value), for example).

Since oddbear's TouchPortalSDK v 0.30.0 release version, the paths have diverged further, most notably in the handling of TP Connectors.

New Features

v 1.44.0

• Add TP API v6 parentGroup parameter for dynamic state creation.
• Add static TouchPortalOptions.ValidateCommandParameters setting to bypass all parameter validation when creating new Command types.

v0.43.0-mp

• Add ConnectorChangeEvent.Data property to get Connector data members (structure is identical to Actions). ConnectorChangeEvent and ActionEvent now have a common base class DataContainerEventBase. commit
• Add ShortConnectorIdNotification event. commit
• Add ConnectorUpdateShort() command to send connector updates based on their shortId (from the above notification event).
  commit sample
• Add TouchPortalClient.IsConnected property.
• TouchPortalClient now sends the OnCloseEvent() to the plugin before disconnecting, so the plugin can send any final data updates, etc (unless TP just crashed or quit, of course).
• ShortConnectorIdNotificationEvent.Data property will parse all the |setting1=testvalue|setting2=anothervalue action data pairs from the long connectorId string into a Dictionary<string, string>. Also the ActualConnectorId property is available to get the actual connector ID part (before any data=value pairs).
  commit
• Add static TouchPortalOptions.ActionDataIdSeparator option to split action data IDs on a character and only store the last part in the dictionary key (eg. for IDs like <plugin>.<category>.<action>.<data1> one could split on the period and have much shorter/simpler key lookups). commit

Some other changes:

• Does not crash on shutdown. Your plugin code can clean up and shut down properly.
• Benchmarked at around 30-50% better performance/throughput in several areas like JSON de-serialization and actual socket efficiency (removes 2 layers of buffers and reads/writes UTF8 JSON bytes directly).
• Log verbosity at the Info level greatly reduced. Logging in general improved and made more consistent, especially at Debug level.

Plugins Using This API

Working examples at:

• https://github.com/mpaperno/MSFSTouchPortalPlugin
• https://github.com/mpaperno/TJoy