The following provides a step-by-step on how to build a class library project (.dll) in Visual Studio which will enable interaction between a third-party application and the IDEA Checkbot application.

The following example will reference the open-source BIM Link Project created by IDEA StatiCa for RSTAB. The source code can be viewed here.

Create a new project in Visual Studio. For the purposes of this document, Visual Studio 2019 is being used.

The base project will be a Class Library Project targeting the .Net Framework 4.8.

You can provide a Name for the project, typically in line with the desired Project Namespace. In this instance, we will select IdeaRstabPlugIn

Required IDEA StatiCa packages can be installed through the NuGet package manager. Search IdeaStatiCa in the Nuget Browser window and Install the following:

• IdeaRS.OpenModel
• IdeaStatiCa.Plugin
• IdeaStatiCa.BimApi
• IdeaStatiCa.BimImporter

Note: Some packages have additional dependencies which will be installed as a part of the installation of the Nuget Package.

• MathNet.Spatial
• System.Text.Json
• Serilog packages - Used for logging.
  • Serilog
  • Serilog.Sinks.Debug
  • Serilog.Sinks.File
  • Serilog.Enrichers.Thread
  • Serilog.Enrichers.Process

The Rstab .dll libraries can be retrieved from the Rstab program files on your computer.

• Dlubal.RSTAB6.dll
• Dlubal.RSTAB8.dll

Below provides the base outline of the Rstab project and different folders/files that make it up. A short description is provided for each.

1. Project Dependencies as required above.
2. BimApi Folder which holds BimApi Implementations of Idea Open Model Object interfaces from the BimApi package. **
3. Factories Folder which holds Factory classes for creation and storage of objects including results.
4. Geometry Folder which holds the RstabGeometry class and RstabGeometryProvider class.
5. Model Folder which holds axillary classes required for the further implementation of the BimApi specific to Rstab.
6. Provider Folder which holds provider classes such as Loads, Results, and ModelData Providers.
7. Utilities Folder which holds specific type Extensions and other specific classes specific to Rstab.
8. BimApiApplication.cs provides the class which implements the ApplicationBIM from the IdeaStatiCa.Plugin Package.
9. CheckbotCommand.cs provides the External Command to Rstab and initiates the Plugin from within Rstab.
10. ImportSession.cs a class that provides code information and other third-party app info required to define IOM Model objects correctly.
11. LicenseLock.cs a Rstab specific file that provides methods to handle the Rstab model locking through the API when performing operations.
12. LoggerProvider.cs a singleton class that provides the Logger to the Rstab plugin classes that support logging.
13. ObjectRestorer.cs a class that restores persistent geometry Members and Nodes which have been saved from a previous session.
14. PersistenceToken.cs a class that implements the abstract PersistanceToken from the BimImporter and defines how persistent objects will be handled. In Rstabs case by element and node No.
15. PluginFactory.cs the primary class which creates the RstabApplication
16. RstabApplication.cs holds the RstabApplication class which inherits from the BimApiApplication class and holds the BimApi RstabModel.
17. SerialFacade.cs holds a generic class that allows the use of Serilog as IPluginLogger.
18. Utils.cs holds misc class which helps with parsing of Rstab text data.

The primary namespace for this project will be the same as the project name IdeaRstabPlugin.

Logging of the checkbot commands and sequences is paramount. Most classes will provide some type of logging that can be viewed from the IDEA StatiCa log files.

To enable logging in to the Rstab Plugin, two files are created in the project.

• SerilogFacade.cs
• LoggerProvider.cs

The SerilogFacade file provides typical code which creates the logging for the plug-in and will be similar across different plug-ins. The primary update required is to ensure the method GetDefaultLogFileName() returns the log file path to match the plug-in name. This file requires the use of several Serilog packages which can be installed through NuGet.

The LoggerProvider class provides the logger to the plug-in.

Learn more about logging and log files here

The IdeaStatiCa.Plugin package provides an abstract class ApplicationBIM that is required to be implemented by Checkbot plugins.

The following page explains in further detail how to implement the application BIM.

• Implement ApplicationBIM and Rstab Application

After creating the RstabApplication class, you will notice some additional requirements such as the IDataCache, RstabModel, Import Session, and ResultsProvider. We can remove the IDataCache error by adding the simple IDataCache.cs to the project.

namespace IdeaRstabPlugin
{
	internal interface IDataCache
	{
		void Clear();
	}
}

The ImportSession class allows us to get information from the third-party app required for the generation of the IOM or Open model. This typically includes the model itself plus other setting information which may alter the conversion. For instance, with Rstab the Vertical Axis can be set in either the global Y or Z direction. As IOM only uses only Z we need to inform our generation methods how to translate.

The following page explains in further detail how to implement the Import Session:

• Rstab Import Session

The PluginFactory defines the working directory of the project. It is also responsible for creating the instance of the IApplicationBIM.

The following page explains in further detail the setting up of the Plugin Factory.

• Rstab PluginFactory

The CheckbotCommand.cs file performs the execution of the command in the third-party application to open checkbot and creates the thread in which both programs can communicate.  

To relate FEA model objects from a third-party app we create a set of 'wrapper' classes that implement the necessary IOM object Interfaces required to generate IOM transfer data.

The wrapper Classes:

• Serve as the conversion conduits of third-party information to IOM model information
• Have defined methods that can extract information from third-party objects to IOM required data.

It is up to the developer to configure the implementation of the BimAPI IOM Interface and populate information such as Id and Name parameters on objects.

It is also up to the developer to configure how base application objects are translated to IOM objects (e.g. how third-party I-Section parameters are translated into a parametric I-Section in IDEA IOM format). This also includes how element abstraction is dealt with when transferring to relating IOM object requirements. Please refer to the IOM Model Documentation for further information.

Object wrappers are created under the Project Namespace with a .BimApi suffix.

using IdeaStatiCa.BimApi;

namespace IdeaRstabPlugin.BimApi
{

• The naming convention is typically the following [AppName][IOM element interface].
• Each wrapper object should have access to a read-only instance of the IPluginLogger.

The following page gives an explanation of the BimApi and the Rstab Implementation:

• BimApi Material and Section Property Implementation
• BimApi Geometry Implementation
• BimApi FEA Results Implementation
• BimApi Model Implementation

The IDEAStatiCa public GitHub provides different examples of how these can be set up.

Auxiliary factories help create the BimApi objects (defined previously). They will typically contain methods that can parse and direct the conversion between a third-party plug-in and the BimApi objects.

A factory interface IFactory is defined in order to set up the base functionality of the different object factories. The factory interface uses generics to define the 'Source' type (i.e the Rstab API object) and the 'Target' type to which it will be converted to, in this case, our BimApi definition wrapper.

Below is the code of the IFactory:

namespace IdeaRstabPlugin.Factories
{
	internal interface IFactory<Source, Target>
	{
		/// <summary>
		/// Creates an instance of <typeparamref name="Target"/> based on <typeparamref name="Source"/>.
		/// </summary>
		/// <param name="objectFactory">IObjectFactory instance</param>
		/// <param name="importSession"></param>
		/// <returns><typeparamref name="Target"/> instance</returns>
		/// <param name="source"><typeparamref name="Source"/> instance</param>
		
		Target Create(IObjectFactory objectFactory, IImportSession importSession, Source source);
	}
}

The below pages look at the definition of the following factories:

• Material Factory
• Cross-Section Factory
• Element Factory
• Results Factory

The BimImporter package provides an interface IGeometry that provides several methods to allow the management of Geometry coming from the base application. This also involved updating Geometry on syncing.

The following pages describe the files and classes created for the management and conversion of Rstab Geometry to IOM.

• Defining RstabGeometry Class

• GeometryProvider - Helps retrieve geometric information about how members, elements, and nodes connect to one another.

Provides allow easy interaction with the base application API and associated model. For an FEA application, typically, three provider classes will be required:

• ModelDataProvider – Helps to provide all the required model data information from the application as required by different classes.
• LoadsProvider – Helps provide load case and combination information from the application.
• ResultsProvider – Helps to retrieve member force results from selected members.

The ObjectFactory class is mainly for creating BimApi objects from RSTAB objects. The file below explains the class in detail and also describes object storage and persistence.

• Configure the Object Factory

Depending on how the project will be deployed, it is often necessary to create a way to install or uninstall and register the plug-in with the base application. This typically means creating an application project (.exe) or similar. Most programs will provide information on how this can be completed.

It is up to the developer's discretion of how to configure and deploy their plugin as required.

For reference, the Rstab PlugIn installation code for the Rstab installation can be found here.