TPSDK C# - go to homepage
TPSDK C# logo

TPSDK C#

C# Facade Integration

This guide explains how to integrate the TPSDK facade into a Visual Studio C# solution.
These steps are intended as a reference—there are often multiple ways to achieve the same result.

.NET MAUI vs Xamarin Forms

Starting with .NET 6, Microsoft® introduced a new toolset for building cross-platform native mobile applications: .NET Multi-platform App UI (.NET MAUI).

This toolset replaces Xamarin® and Xamarin FormsTM.

As a result, TPSDK is provided in two versions:

  • The newer .NET 8 version (recommended for all new development)
  • The older Xamarin version (for projects in transition; will be discontinued in 2025)

.NET MAUI

Create a New Project

Create a new solution in Visual Studio—typically a .NET MAUI App project. The template or app style does not matter for integration.

Adding Project References

After creating the solution, add the CatalystFacade.NET and CatalystFacade.NET.Droid projects to your solution.
This allows you to easily extend or customize the facade interface as needed.

Next, reference both projects in your main project.
To do this, right-click your platform project (e.g., TpsdkDemoXm.Android), select Add > Reference, choose Projects, and check both facade projects.

Configuring NuGet

Both facade projects reference TPSDK packages via NuGet.
Since TPSDK is not hosted on the public NuGet.org repository, you must create a local repository and place the packages there.

The simplest approach is through Visual Studio:
Go to Options → NuGet Package Manager → Package Sources, create a new source, and point it to your TPSDK NuGet folder.

The NuGet package is a zip file containing all native ABI versions (ARM, ARM64, etc.), so no further setup is required.

Xamarin

Create a New Project

Create a new solution in Visual Studio—typically a Mobile App (Xamarin.Forms) or similar.
Cross-platform mobile apps usually have a platform-specific project and a shared project.
In TPSDK, shared code is in the portable project, while platform-specific implementations are in their respective projects.

 

Add Projects and References

Adding the Facade to Your Solution

Add the CatalystFacade.Portable and CatalystFacade.Droid projects to your solution.
This lets you extend the facade interface as needed. Alternatively, you can reference the CatalystFacade.Portable.dll and CatalystFacade.Droid.dll libraries directly.

Reference both in your main project:
Right-click your platform project (e.g., TpsdkDemoXm.Android) and either:

  • Select Add > Reference > Projects and check both facade projects, or
  • Select Add > Reference and browse to the two facade DLLs.

Adding References to Your Solution

ABI Files

After adding the facade and portable projects, add the remaining libraries from the libs folder of TPSDK.

This process can be a bit tedious due to multiple Android binary interfaces (ABIs) with identical file names.

Recommended steps:

  1. Copy all ABI folders from the SDK into a jniLibs folder in your project/solution (create the folder structure as in [Java](\ref GuideAndroidStudio) if not already present).
  2. In Solution Explorer, add a filter called jniLibs or similar.
  3. Right-click the folder, select Add Existing Item, and select all .so files for a single ABI, adding them as links.
  4. Change the Build Action from None to AndroidNativeLibrary. If you are building a DLL (not an app), review the Microsoft documentation for the correct build action.
  5. Close the solution and open the .csproj file.
  6. Adjust the included AndroidNativeLibrary entries as needed. Copy/paste all .so file references and adjust the ABI paths accordingly.

It is important to keep the structure of the libs folder, as the native files expect this layout.

Your <ItemGroup> in the Visual Studio project file should look like:

<ItemGroup>
    <AndroidNativeLibrary Include="..\libs\arm64-v8a\libc++_shared.so" />
    <AndroidNativeLibrary Include="..\libs\arm64-v8a\libDRV_TrimbleCommon.so" />
    ...
    <AndroidNativeLibrary Include="..\libs\armeabi-v7a\libTrimble.Ssi.Interfaces.GNSS.so" />
    ...
</ItemGroup>
DLL References

This step is straightforward:
Reference all required .dll files using the Visual Studio reference importer.

  • All ‘portable’ DLLs go into the portable project (if available).
  • All other DLLs go into the Android-specific project.

You may notice additional DLLs in the folder, such as Trimble.Ssi.Driver.MockGnss.Android.dll.
These are mostly optional or loaded dynamically. For example, the mock driver simulates a receiver for testing.
Other optional libraries, like Trimble.EMPOWER.*.dll, support Trimble EMPOWER modules.
If you are missing a hardware feature, check the lib folder for a corresponding optional library.

 

Using the Facade

At this point, your project should build successfully and be ready to use.

You can initialize the facade like this:

CatalystFacade.Droid.CatalystFacade _catalystFacade = new CatalystFacade.Droid.CatalystFacade(myAppGUID, this);

where myAppGUID is either the GUID from the facade sample or the one provided by Trimble.

Note:
You may need to adjust manifest permissions before deploying your application.
For details, please refer to the documentation.