TouchPortal-CS-API 1.47.2

.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher. 
dotnet add package TouchPortal-CS-API --version 1.47.2
                    


                    

                
NuGet\Install-Package TouchPortal-CS-API -Version 1.47.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="TouchPortal-CS-API" Version="1.47.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="TouchPortal-CS-API" Version="1.47.2" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="TouchPortal-CS-API" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add TouchPortal-CS-API --version 1.47.2
                    


                    

                
#r "nuget: TouchPortal-CS-API, 1.47.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#addin nuget:?package=TouchPortal-CS-API&version=1.47.2
                    


                            Install TouchPortal-CS-API as a Cake Addin
                        

                    

                
#tool nuget:?package=TouchPortal-CS-API&version=1.47.2
                    


                            Install TouchPortal-CS-API as a Cake Tool

Touch Portal C# and .NET API

Made for Touch Portal Nuget .NET License Discord

Touch Portal API for making plugins with .NET

Built based on documentation at Touch Portal Plugin API.

Current Touch Portal API support level: v10.0 (Touch Portal v4.3)

Originally a fork of https://github.com/oddbear/TouchPortalSDK, optimized for performance, usability, and good behavior.

Download / Install

  • The API is available via a nuget package along with a separate debug symbols package.
  • An equivalent .zip archive is also available for download in 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 and use TouchPortalFactory to create an instance of TouchPortalClient. Then TouchPortalClient.Connect() to Touch Portal before sending or receiving events.

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

    private readonly ITouchPortalClient _client;
    private readonly ILogger<SamplePlugin> _logger;

    public SamplePlugin()
    {
        _client = TouchPortalFactory.CreateClient(this);
        _logger = new Logger<SamplePlugin>(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 of this repository. For more documentation see the original 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<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.

Change Log

See CHANGELOG.md.

Plugins Using This API

Working examples at:

Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.47.2 141 5/19/2025
1.47.1 210 11/26/2024
1.47.0 112 11/25/2024 1.47.0 is deprecated.
1.46.1 107 11/16/2024
1.46.0 319 8/4/2023
1.45.1 542 7/18/2022
1.45.0 491 7/18/2022 1.45.0 is deprecated.
1.44.2 470 7/7/2022
1.44.1 519 7/7/2022 1.44.1 is deprecated.
1.44.0 503 7/7/2022 1.44.0 is deprecated.

# Touch Portal .NET API - Change Log

## v1.47.2 (19-May-24)
* Deprecated usage of `TriggerEventStates` custom type in `TouchPortalClient::TriggerEvent()` and `TriggerEventCommand`:  ([1049c940])
 * Switch `TriggerEventCommand` to use regular `Dictionary<string,string>` type;
 * Updated `TouchPortalClient::TriggerEvent()` method to accept `Dictionary<string,string>`  type for local states argument and added overload which accepts a more generic `IReadOnlyDictionary<string,string>` argument.

[1049c940]: https://github.com/mpaperno/TouchPortal-CS-API/commit/1049c940

---
## v1.47.1 (26-Nov-24)
* Fixed `TriggerEventCommand` not being serialized properly for `TriggerEvent()` method (since v1.47.0). ([@2675613b](https://github.com/mpaperno/TouchPortal-CS-API/commit/2675613b))
* Changed `TriggerEventStates` dictionary type to `<string, string>` because `triggerEvent.states` values must be of string type. ([@dab4d6e0](https://github.com/mpaperno/TouchPortal-CS-API/commit/dab4d6e0))
* All `ITouchPortalEventHandler` method implementations are now optional in plugin code. ([@e6f2385d](https://github.com/mpaperno/TouchPortal-CS-API/commit/e6f2385d))
* Exposed `ICommandHandler.SendCommand()` method as public in `TouchPortalClient`. ([@134268b5](https://github.com/mpaperno/TouchPortal-CS-API/commit/134268b5))
* Actual JSON message being sent is now logged (at Debug level) instead of just success status. ([@0e954f08](https://github.com/mpaperno/TouchPortal-CS-API/commit/0e954f08))

[Full change log...](https://github.com/mpaperno/TouchPortal-CS-API/compare/v1.47.0.0...v1.47.1.0)

---
## v1.47.0 (25-Nov-24)
Updates for Touch Portal API versions 7-10.  ([@69beeb19](https://github.com/mpaperno/TouchPortal-CS-API/commit/69beeb19))
* Added `TriggerEvent(string eventId, Dictionary<string, object> states)` method & `TriggerEventCommand` type.
* Added `StateListUpdate(string stateId, string[] values)` method & `StateListUpdateCommand` type.
* Added `forceUpdate` option to `CreateState()` method and `CreateStateCommand.ForceUpdate` member.
* Added `ListChangeEvent.Values` property for `listChangeEvent` incoming message. This is a `Dictionary<string, string>` type.
* Added `InfoEvent.CurrentPagePathMainDevice` and `InfoIevent.CurrentPagePathSecondaryDevices` properties for `info` incoming message type.
* Added `PreviousPageName`, `DeviceIP`, `DeviceName`, and `DeviceID` to `BroadcastEvent` incoming message type.
* Added & improved some documentation comments.

---
## v1.46.1 (16-Nov-24)
* Updated for .NET8 and dropped .NET5 support.
* Updated dependencies to 8.x versions (also fixes a security issue in the `System.Text.Json` library).

---
## v1.46.0 (4-Aug-23)
* Optimized TP message output by skipping a byte array copy step for appending the terminating newline after each JSON struct.
* Published .NET6 and .NET7 builds.

---
## v1.45.0 (18-Jul-22)
Both changes affect the feature which parses the "Long" connector ID from the short ID notification events into individual key/value fields (see notes for v0.43.0-mp below).
* Connector data key names are now truncated if `TouchPortalOptions.ActionDataIdSeparator` is set, just like action/connector data keys.
* Fix that the "pc_plugin-name_" part wasn't properly stripped from the "actual" connector ID.

---
## v1.44.0 (6-Jul-22)
* 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 (17-Apr-22)
* BREAKING: Convert the action/connector `Data` type into a dictionary of id=value pairs. See the [SamplePllugin.cs changes on this commit](https://github.com/mpaperno/TouchPortal-CS-API/commit/8a918b5a)
* `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).
*  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).
 [@89a81c42](https://github.com/mpaperno/TouchPortal-CS-API/commit/89a81c42)
* `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).
 [@2238db9d](https://github.com/mpaperno/TouchPortal-CS-API/commit/2238db9d)

---
## v0.40.0-mp (3-Mar-22)
Changes since v0.30.0-beta (original @oddbear version [@1f431d05](https://github.com/oddbear/TouchPortalSDK/commit/1f431d05))

### Performance and efficiency improvements:  ([@63e886c0](https://github.com/mpaperno/TouchPortal-CS-API/commit/63e886c0))
* 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.

### New Features
* Added `ConnectorChangeEvent.Data` property to get Connector data members (structure is identical to Actions).
 `ConnectorChangeEvent` and `ActionEvent` now have a common base class `DataContainerEventBase`.
 [commit](https://github.com/mpaperno/TouchPortal-CS-API/commit/ca778ccfdde2ee624198b70abffa356839ead350)
* Added `OnShortConnectorIdNotification` event.  [commit](https://github.com/mpaperno/TouchPortal-CS-API/commit/0fbc8e66)
* Added `ConnectorUpdateShort()` command to send connector updates based on their `shortId` (from the above notification event).
 [commit](https://github.com/mpaperno/TouchPortal-CS-API/commit/0610921d5bc1539638e02a004243bb54a21ee23e)
 [sample](https://github.com/mpaperno/TouchPortal-CS-API/blob/mp/main/TouchPortalSDK.Sample/SamplePlugin.cs#L228)
* Added `TouchPortalClient.IsConnected` property.