Getting started with the SDK Connector: implementing the AppInterface

This article guides you through adding the SDK Connector to your Windows application, from setting up your Visual Studio project to implementing the AppInterface, the code that connects the Connector to your model.

💡 Tip: New to the SDK Connector? Read SDK Connector with full GUI: overview and requirements first.

Before you begin

Make sure you have:

The SDK Connector package, with the files unblocked. See Requirements.
Visual Studio with a C# Windows Forms project for .NET Framework 4.8.
A BIMcollab user account on the Playground.
The generic developer token for testing on the Playground:
460C8E9C-20E4-4188-BCA2-8E34F464C026.

Overview of the steps

Step	What you do
1. Prepare your project	Change a build setting and add the AppInterface project.
2. Add the user control to a form	Place the BCF Manager interface in a window of your application.
3. Set your vendor-specific values	Add your app token and other values to the AppInterface.
4. Initialize and save on exit	Start the user control, and let users save their changes when the application closes.
5. Implement the AppInterface	Connect the user control to your model.
6. Copy the redistributable files and run	Build and test your application.
7. Add the installation path to the registry	Allow BIMcollab update installers to find the Connector files.

Prepare your project

Open the properties of your project.
Go to Build > General and clear the Prefer 32-bit checkbox.
Add the AppInterface project to your solution. You can find it in the Source folder of the package (AppInterface.csproj).
In your project, add a reference to the AppInterface project: References > Add Reference > Projects > Solution > AppInterface.
Build the solution.

Add the user control to a form

Open the form where you want to show the BCF Manager in the form designer.
Add the user control to the toolbox:
1. Right-click the toolbox and select Choose Items.
2. In the Choose Toolbox Items dialog, browse to BCFManagerControlLib.dll in the Redistributable folder.
Drag the control from the toolbox (General > DlgMain) to your form.

💡 Tip: If the form designer can't find the AppInterface DLL, restart Visual Studio.

Set your vendor-specific values

When you receive your app token, you also receive a document from BIMcollab with values for your application. Add these values to App_Interface.cs:

Value	What it does
`developersToken`	Your app token. It identifies your application in BIMcollab.
`developersRegValPrefix`	A unique prefix. The user control uses it to store the settings of your application in the Windows registry.
`developersClientID`	Identifies your application as the client that created an issue.

Example:

public static string developersToken = "<your-app-token>";
public static string developersRegValPrefix = "<your-registry-prefix>";
public static string developersClientID = "<your-client-id>";

During development, use the generic developer token as developersToken. It only connects to the Playground.

Initialize and save on exit

Initialize the user control

Call the control's Initialize() method to make the user control ready for use. Until you call it, all controls in the user control are disabled.

Save on exit

When your application closes, call the control's SaveOnExit() method. It gives users the chance to save any changes they made in the user control.

If users can cancel the closing of your application, call SaveOnExit with showCancelButton = true. This adds a Cancel button to the message.

Example:

// After the form with the user control is loaded
bcfManagerControl.Initialize();

// When the application closes
bcfManagerControl.SaveOnExit(showCancelButton: true);

Implement the AppInterface

The AppInterface contains properties, which show or hide features in the user control, and methods, which the user control calls to work with your application. Implement most methods to fully integrate the Connector.

Properties: show or hide features

Property	Set to `true` when your application…
`hasModel`	Works with (IFC) models: it can get and set the camera position, change component visibility, and create snapshots.
`hasButtonBoundingBox`	Supports bounding boxes (also called clipping planes or section planes). Shows a button to create a bounding box around the visible part of the model. See `SetBoundingBox`.
`hasButtonImportIssues`	Can create several issues at once, for example from clash detection, saved viewpoints, or test results. Shows an Import Issues button. Set the button text with `importIssuesToolTip`. See `ImportIssues`.
`hasButtonMinMax`	Should show a button that switches the user control between its normal and a minimal layout.
`hasComponentsInViewpointOptionVisible`	Adds visible components to viewpoints. Adds the Visible option to Components in viewpoint in the Add Issue dialog.
`hasComponentsInViewpointOptionSelected`	Adds selected components to viewpoints. Adds the Selected option to Components in viewpoint in the Add Issue dialog.
`hasSaveSelectionAsSelectedComponentsOption`	Works with selected components. Enables the Save selection as… option in the Add Issue dialog.

Methods: information about your application

Method	What it must do
`GetApplicationName()`	Return the name of your application. The user control uses it in messages.
`GetApplicationMainWindowHandle()`	Return the handle (HWND) of your application's main window.
`GetToken()`	Return your app token.
`GetRegistryValuePrefix()`	Return your registry prefix.
`GetLanguageFilesPath()`	Return the full path to the folder that contains the `languages` folder, including the final backslash. If it returns an empty string, the user control looks in the current working directory.

Methods: views and snapshots

Method	What it must do
`CreateSnapshot(snapshotPath)`	Save a snapshot of the current view as `snapshot.png` in the folder `snapshotPath`. Return `true` when it succeeds.
`OkToSetView(ref message, ref is2D, resetView)`	Return whether the current view can be used for a viewpoint. Set `is2D` to `true` for a 2D view or `false` for a 3D view. `resetView` is `true` when the user updates an existing viewpoint. The `message` parameter is no longer used.
`SetView2D(viewpoint, settings)`	Fill the viewpoint with the information of the current 2D view.
`SetView3D(viewpoint, settings)`	Fill the viewpoint with the information of the current 3D view. Return `true` when it succeeds.
`ZoomTo2D(viewpoint, settings)`	Recreate a 2D view from the viewpoint.
`ZoomTo3D(viewpoint, settings, fullZoom, controlKeyPressed)`	Recreate a 3D view from the viewpoint. When `fullZoom` is `true`, use all viewpoint information. When `false`, only change the camera position. `controlKeyPressed` is `true` when the user held the Ctrl key, so you can offer an alternative zoom, for example another projection mode.

💡 Tip: For details about viewpoints, cameras, components, and settings, see Working with viewpoints, components and clipping planes in the SDK Connector.

Methods: components

Method	What it must do
`CreateComponentCache(viewpoint)`	Add the components of the viewpoint to a cache, to avoid requesting the same component data from your application again. You decide what to cache. Leave it empty if you don't need a cache.
`SelectComponent(ifcGuid)`	Select the component with this IFC GUID in your application. Called when a user selects a component in the Viewpoint info dialog.
`GetComponentIfcType(ifcGuid)`	Return the IFC type of the component with this IFC GUID. Called when a user clicks Check components in the Viewpoint info dialog.

Methods: optional features

Method	What it must do
`SetBoundingBox()`	Create a bounding box around the visible components in the current 3D view. Called when a user clicks Create section box. Needs `hasButtonBoundingBox`.
`ImportIssues()`	Create a list of issues to import, for example from a clash check. Called when a user clicks Import Issues. Needs `hasButtonImportIssues`.

Helper functions you can call

The user control also gives you helper functions. Don't change the Set…Delegate() methods in the AppInterface: the user control uses them to connect these functions.

Helper function	What it does
`AddZoomMessage(message)`	Adds a message that explains why your application couldn't fully recreate a view. Call it once per message.
`ShowZoomMessage()`	Shows the message icon in the user control. Users click it to read the messages.
`AddIssues(issues)`	Sends a list of issues to the user control, for example from `ImportIssues`.
`GetDictionaries(…)`	Returns the values used in the connected BIMcollab project: statuses, types, priorities, labels, assigned users, areas, milestones, visibilities, and custom select fields. Use these values when you create issues.
`GetMandatoryFields(…)`	Returns which fields are mandatory in the connected project.
`GetEnabledFields(…)`	Returns which fields are available in the connected project. Availability depends on the BIMcollab subscription.

Copy the redistributable files and run

Copy all files from the Redistributable folder to the output folder of your project.
Build and run your application.
Sign in with your Playground account, and check that the BCF Manager shows the issues of your Playground project.

Add the installation path to the registry

Your installer must create a registry entry with the full installation path of the Connector files. BIMcollab update installers use it to find and update the files. You find the registry key in the document with your vendor-specific values.

Use the Connector in a modeless dialog

If you show the user control in a modeless dialog, run the dialog in a thread with the single-threaded apartment (STA) state. Otherwise, the user control can't use standard Windows dialogs such as Open, Save, and Select.

Example:

private void button1_Click(object sender, EventArgs e)
{
    Thread modelessThread = new Thread(StartBCFManager);
    modelessThread.IsBackground = true;
    modelessThread.SetApartmentState(ApartmentState.STA);
    modelessThread.Start(this);
}

private static void StartBCFManager(object here)
{
    Form2 form2 = new Form2();
    form2.ShowDialog();
}

Troubleshooting

Problem	Possible cause	Solution
All controls in the BCF Manager are disabled.	`Initialize()` wasn't called.	Call `Initialize()` after the form loads.
The control isn't available in the toolbox, or the designer shows an error.	Visual Studio didn't load the AppInterface DLL.	Build the solution and restart Visual Studio.
The application fails when the control loads.	Redistributable files are missing from the output folder, or they are still blocked.	Copy all redistributable files, and unblock them.
Open or Save dialogs don't work in a modeless dialog.	The thread doesn't use the STA state.	Set the apartment state to STA. See Use the Connector in a modeless dialog.
Users lose changes when the application closes.	`SaveOnExit()` isn't called.	Call `SaveOnExit()` when the application closes.