Skip to content

Connector Project Structure

Overview

Connector code bases need to follow a particular structure. When running xchange connector new our desired structure and names is followed.

An example structure is as follows:

| -> Connector{ConnectorName}/
  | -> Connector/
    | -> App/
        | -> ...
    | -> Client/
    | -> Connections/
    | -> Connector.csproj
    | -> settings.json
    | -> Program.cs
    | -> ...
  | -> Connector.sln
Important Notes

There are some items that should not be renamed or moved. These items are:

  • Connector.sln
  • Connector/
  • Connector/Connector.csproj
  • Connector/settings.json

Re-using Existing CSharp Code

There may be cases where you already have CSharp code written for your domain and may want to re-use this with your Connector project. This can be done in a few ways:

Copy Over Code

If you only want a few items then it may be best to duplicate your code by copying over these classes into the codebase.

This is the preferred method as Connector should should be lightweight and not contain much of your business logic. It should be acting as a proxy to interfacing with your platform.

Project Reference

Project reference support was added on version 1.3.8 of Trimble.Xchange.Connector.CLI

If there are many items you want to re-use then referencing the project on the Connector.csproj can also be done. There are few things to keep in mind

  • The project needs to be added on the Connector.sln file
  • The project directory should be within the directory that houses the Connector.sln file

Take the following example code structure

| -> {CompanyName}SourceCode
    | -> {CompanyName}.sln
    | -> {CompanyName}WebApi.sln
    | -> Connector.sln
    | -> Connector{ConnectorName}/
        | -> App/
            | -> ...
        | -> Client/
        | -> Connections/
        | -> Connector.csproj
        | -> settings.json
        | -> Program.cs
    | -> {CompanyName}DataModels/
        | -> {CompanyName}DataModels.csproj
        | -> ...
    | -> {CompanyName}WebApi/
        | -> ...
    | -> ...

In this case here you may want to leverage your existing data models, {CompanyName}DataModels/. To do so the Connector.sln should have this project added to it and the Connector{ConnectorName}/Connector.csproj should be referencing this project as well.

Important Notes

Like mentioned in the section Copy Over Code, Connector code should be lightweight so consider all ramifications when referencing existing projects as this can lead to a lot of bloat and longer submission review processes.

You may want to inspect what will be sent to Xchange. This can be done by using the --dry-run option in xchange code submit. This will allow you to first review the code being bundled up in the archive.

Binaries and NuGet Packages

We do not accept Connector codebases that have binaries. This also means we do not accept DLLs. This is for security concerns as we want to review all code that could be ran on our platform.

The same reasoning is also applied to NuGet packages. NuGet packages are approved by a case by case basis. It is our goal that the Connector SDK package is all you need to create your Connector. If the Connector SDK is missing tooling needed by your Connector then please contact Product Enablement at xchange_build@trimble.com explaining your situation.