Interact with Trimble Connect for Windows

The Trimble Connect Windows .NET API lets another Windows application — a third‑party integration or another Trimble product such as Tekla Structures or SketchUp — drive Trimble Connect Desktop (TCD) programmatically. The integration uses the TrimbleConnectDesktopClient class, which talks to a running TCD process over a local WCF channel.

Reference the API library

Add a reference to Trimble.Connect.Desktop.API.dll (and its companion Trimble.Connect.Desktop.API.Common.dll, which carries the shared types). The library targets .NET Framework 4.8 and is built as AnyCPU, so it works from x86, x64, and AnyCPU host processes.

Launch or discover a TCD instance

Before your integration can call any operation, a TCD process must be running and your code must know which instance to connect to. Trimble Connect Desktop registers a custom URI scheme trimbleconnect:/, so you can launch a new instance and tag it with an instance definition in a single call:

var client = new TrimbleConnectDesktopClient();
client.StartApplication(
    connectionNameDefinition: "MyIntegration",
    waitTimeInMilliseconds: 30000);

If TCD is already running, you can enumerate the live instances. The factory uses WCF UDP discovery (UdpDiscoveryEndpoint) to find them on the local machine:

var names = client.GetConnectionNames(instanceSearchTimeoutInSeconds: 1);

Each instance is published with a service identifier of the form Trimble.Connect.Desktop.API or Trimble.Connect.Desktop.API/<instanceDefinition>. When several TCD instances run on the same machine, ConnectAsync also uses the SESSIONNAME environment variable to pick the instance that belongs to the caller’s Windows session.

Establish a Connection

Once you know which instance to use, open a connection:

bool ok = client.Connect(
    connectionName: "MyIntegration",
    instanceSearchTimeoutInSeconds: 1);

Internally the client builds a NetTcpBinding (security mode None, reliable session enabled) wrapped in a CustomBinding that uses binary message encoding with GZip compression. The endpoint URL is net.tcp://<ethernet‑adapter IPv4>:<freePort> (the factory falls back to localhost if no suitable adapter is found). Buffers and MaxReceivedMessageSize are set to 64 MB; the receive timeout is 4 hours and the send timeout is 30 minutes. A ServiceThrottlingBehavior allows up to 100 concurrent calls and 100 concurrent sessions. The connection is duplex, so TCD can call back into your callback handler.

Get the active project and its managers

After connecting, the entry point for everything project‑related is client.ProjectManager:

Project activeProject = client.ProjectManager.GetActiveProject();

// or:

Project activeProject = await client.ProjectManager.GetActiveProjectAsync();

ProjectManager itself is intentionally narrow — GetActiveProject / GetActiveProjectAsync and the ActiveProjectLoaded event are its only public surface. The real working surface lives on the Project instance it returns. A Project exposes five domain managers:

Manager	What it controls
ModelManager	Listing, loading, unloading, and comparing 3D models in the project
ModelObjectManager	Querying and acting on the objects inside the loaded models
AttributeManager	Reading model‑object attributes and attribute sets
ViewManager	Saved views (list, activate, create)
ViewportManager	Camera, picker state, viewport interactions

For example, loading additional models into the 3D view goes through ModelManager, not through ProjectManager directly:

var modelManager = activeProject.ModelManager;
var modelsToLoad = modelManager.GetUnloadedModels();
await modelManager.LoadModelsAsync(modelsToLoad);

SettingsManager (also exposed directly on the client) provides application‑ and project‑level settings.

Subscribe to Events

The API is event‑driven rather than callback‑contract‑driven from the consumer’s perspective. Your integration subscribes to standard C# EventHandler events on the client, the Project, or one of the project’s managers; the SDK takes care of the underlying WCF callback channel internally. The events your integration can listen to include:

Event	Where
TrimbleConnectDesktopClosed	TrimbleConnectDesktopClient — fired when the TCD process exits; the connection is also torn down
ActiveProjectLoaded	ProjectManager — fired after TCD finishes loading a project the user opened
ProjectClosed	Project — fired when the project is closed in TCD
ProjectUpdated	Project — fired when the project identifier or name changes
ModelsChanged	Project.ModelManager — fired when models are added, removed, or updated
ModelLoadingChanged	Project.ModelManager — fired when a model is loaded or unloaded
ModelComparisonCompleted	Project.ModelManager — fired when a StartComparingModelsAsync completes
ModelIdentifierChanged	Project.ModelManager — fired when a locally created model gets its cloud identifier

A typical subscription looks like:

client.ProjectManager.ActiveProjectLoaded += (sender, args) =>
{
    Project activeProject = args.Project;
    activeProject.ModelManager.ModelsChanged += OnModelsChanged;
};

Note

Event handlers are not guaranteed to run on the thread that registered them. If you mutate UI from a handler, marshal back to your UI thread yourself.

Disconnect and handle host shutdown

When your integration is done, call Disconnect:

client.Disconnect();

After Disconnect, any further operation on the client throws InvalidOperationException. If TCD itself closes first, the SDK raises TrimbleConnectDesktopClosed and tears the connection down for you, so you do not need to call Disconnect again in that case.

How the API is built

The API is made up of three projects under Source/, all targeting .NET Framework 4.8:

• Trimble.Connect.Desktop.API — the public client SDK (TrimbleConnectDesktopClient, ProjectManager, SettingsManager, Project, ModelManager, AttributeManager, ViewManager, ViewportManager, ModelObjectManager, etc.).
• Trimble.Connect.Desktop.API.Common — shared, lightweight types referenced from both sides of the wire (Camera, Vector3, ObjectSelectionMode, ProjectionType, VisualState, HierarchyLevel, ModelReference, etc.).
• Trimble.Connect.Desktop.ExternalInterface.Services — the WCF service contracts (ITrimbleConnectDesktopService, ITrimbleConnectDesktopCallbackService), the DTOs, the host factory (TrimbleConnectDesktopWcfServiceFactory), and the service implementation TCD hosts at runtime. These contracts are internal — consumers only interact with the higher‑level managers in the API project.

All three assemblies are strong‑named with the shared key Source/TCShared.snk and are built via dotnet build Source/TrimbleConnect.sln, which the top‑level build.msbuild script orchestrates. The same script then invokes al.exe (the .NET Framework Assembly Linker) six times to produce publisher‑policy DLLs for the legacy 1.0, 1.1, and 1.2 versions of both Trimble.Connect.Desktop.API and Trimble.Connect.Desktop.API.Common. Each policy DLL redirects older callers to the current 1.x release at load time, so an integration that was compiled against an older API can pick up the version shipped with the user’s TCD install.

On GitHub Actions, the ci.yml workflow on windows-latest authenticates to the private Trimble Artifactory NuGet feeds, runs dotnet restore, builds via msbuild build.msbuild, runs the unit and spec test DLLs from AutomatedTestsBin/, and uploads the resulting bin/ folder as a build artifact.

How the API is deployed

The API is distributed in two complementary ways:

• Inside the TCD installer. The InstallShield project at Installer/TrimbleConnect.ism ships Trimble.Connect.Desktop.API.dll, Trimble.Connect.Desktop.API.Common.dll, Trimble.Connect.Desktop.ExternalInterface.Services.dll, and the publisher‑policy DLLs next to TrimbleConnect.exe, so the API surface is always present on any machine that has TCD installed.
• As a NuGet package. Source/Nuget/Trimble.Connect.Desktop.API.nuspec defines a package with id Trimble.Connect.Desktop.API (currently version 1.3.1) that references Trimble.Connect.Desktop.API.dll and Trimble.Connect.Desktop.API.Common.dll under lib/net451 — usable from any .NET Framework 4.5.1+ consumer, including .NET 4.8.

For developers who want the assemblies in the Global Assembly Cache (GAC) on their own machine without running the installer, the repo ships a GAC/install_API.bat script that calls gacutil /i for each of the three API DLLs plus the six publisher‑policy DLLs (and a matching GAC/uninstall_API.bat).

At runtime, the WCF host is started when TCD launches (by ExternalInterfaceFeature in the desktop app) and torn down when TCD exits. There is no separate server to deploy — the API surface is hosted inside each TCD process, so a client just needs the API assembly resolvable at load time and a running TCD instance on the same machine.