https://github.com/mpaperno/touchportal-cs-api
Touch Portal API for C# and .NET
https://github.com/mpaperno/touchportal-cs-api
api api-client csharp dotnet plugin touch-portal touch-portal-api touch-portal-plugin touchportal touchportalapi
Last synced: about 2 months ago
JSON representation
Touch Portal API for C# and .NET
- Host: GitHub
- URL: https://github.com/mpaperno/touchportal-cs-api
- Owner: mpaperno
- License: mit
- Created: 2022-02-18T21:45:29.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-11-26T06:08:05.000Z (6 months ago)
- Last Synced: 2025-04-17T09:00:44.307Z (about 2 months ago)
- Topics: api, api-client, csharp, dotnet, plugin, touch-portal, touch-portal-api, touch-portal-plugin, touchportal, touchportalapi
- Language: C#
- Homepage:
- Size: 218 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Touch Portal C# and .NET API
[](https://www.touch-portal.com/)
[](https://www.nuget.org/packages/TouchPortal-CS-API)
[](https://github.com/mpaperno/TouchPortal-CS-API/actions/workflows/dotnet.yml)
[](LICENSE)
[](https://discord.gg/hMU9tjCG2s)
----------------------
## Touch Portal API for making plugins with .NET
Built based on documentation at [Touch Portal Plugin API](https://www.touch-portal.com/api/).
Current Touch Portal API support level: **v10.0** (Touch Portal **v4.3**)
Originally a fork of [https://github.com/oddbear/TouchPortalSDK](https://github.com/oddbear/TouchPortalSDK), optimized for performance, usability, and good behavior.
### Download / Install
- The API is available via a [nuget package](https://www.nuget.org/packages/TouchPortal-CS-API) along with a separate debug symbols package.
- An equivalent .zip archive is also available for download in [Releases](https://github.com/mpaperno/TouchPortal-CS-API/releases). This includes debug symbols in external .pdb files.
- Pre-built libraries are available for .NET versions 6, 7, and 8 via both delivery methods and include generated documentation XML.
### Getting started:
The simplest way of getting started, is to implement
[`ITouchPortalEventHandler`](https://github.com/mpaperno/TouchPortal-CS-API/blob/main/TouchPortalSDK/ITouchPortalEventHandler.cs)
and use [`TouchPortalFactory`](https://github.com/mpaperno/TouchPortal-CS-API/blob/main/TouchPortalSDK/TouchPortalFactory.cs) to create an instance of
[`TouchPortalClient`](https://github.com/mpaperno/TouchPortal-CS-API/blob/main/TouchPortalSDK/Clients/TouchPortalClient.cs).
Then `TouchPortalClient.Connect()` to Touch Portal before sending or receiving events.
```csharp
public class SamplePlugin : ITouchPortalEventHandler
{
// Replace "Plugin.Id" with your unique id.
public string PluginId => "Plugin.Id";
private readonly ITouchPortalClient _client;
private readonly ILogger _logger;
public SamplePlugin()
{
_client = TouchPortalFactory.CreateClient(this);
_logger = new Logger(default);
}
public void Run()
{
// Connect to Touch Portal on startup.
_client.Connect();
}
// Event received when plugin connects to Touch Portal.
public void OnInfoEvent(InfoEvent message)
{
_logger.LogInformation(
"[InfoEvent] VersionCode: '{TpVersionCode}', VersionString: '{TpVersionString}', SDK: '{SdkVersion}', PluginVersion: '{PluginVersion}', Status: '{Status}'",
message.TpVersionCode, message.TpVersionString, message.SdkVersion, message.PluginVersion, message.Status
);
// Update a static state defined in entry.tp
_client.StateUpdate($"{PluginId}.staticState1", "Connected!");
// Add a dynamic state
_client.CreateState($"{PluginId}.dynamicState1", "Test dynamic state 1", "Test 123");
}
// Event triggered when one of this plugin's actions, defined in entry.tp, is triggered.
public void OnActionEvent(ActionEvent message) {
_logger.LogInformation("{@message}", message);_
// Handle the action....
}
// ...
}
```
More complete example in the [Sample project](https://github.com/mpaperno/TouchPortal-CS-API/blob/main/TouchPortalSDK.Sample/SamplePlugin.cs) of this repository.
For more documentation see the original [Wiki](https://github.com/oddbear/TouchPortalSDK/wiki).
### 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`
with each data ID mapped to its corresponding value.
See the [SamplePllugin.cs changes on this commit](https://github.com/mpaperno/TouchPortal-CS-API/commit/8a918b5ad1e82f01b459c233447465a9c6157de0#diff-cb35f57a6de34300ca9fce15af2bada215b8c92a45456f671b02b78923a5b083)
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.
### Change Log
See [CHANGELOG.md](https://github.com/mpaperno/TouchPortal-CS-API/blob/main/CHANGELOG.md).
### Plugins Using This API
Working examples at:
* https://github.com/mpaperno/MSFSTouchPortalPlugin
* https://github.com/mpaperno/TJoy