Creo Elements/Direct Modeling COM & .NET API

Creo Elements/Direct Modeling COM & .NET API - Supported Client Types

Add-ins (internal clients)

Add-ins are in-process COM or .NET clients implemented in their own DLL which is loaded into the Creo Elements/Direct Modeling process at runtime.

Building COM add-ins

Since add-ins run in the process context of Creo Elements/Direct Modeling, they should use the same C and C++ run-time libraries as the main application for consistency. To assure this, your COM add-ins must be compiled with Visual Studio 2015.

Add-ins are platform-dependent, i.e. you must provide seperate 32-bit and 64-bit versions of your add-in. A 32-bit add-in cannot be loaded into a 64-bit process and vice versa.

32 bit add-ins

32-bit add-ins should be compiled on a 32-bit machine to avoid problems. It is also possible to compile 32-bit add-ins on a 64 bit machine, but you have to take special care to:

64 bit add-ins

64-bit add-ins must be compiled on a 64-bit machine. There is no supported way to cross-compile a 64-bit version of the add-in on a 32-bit machine. In addition, you have to make sure to:

Note: By default, Microsoft Visual Studio does not use the native 64-bit compilation tools, but uses the 32-bit tools in a cross-compilation mode. This default behaviour does not work properly for compiling 64-bit COM add-ins. This is a restriction in the Microsoft tools. In order to use the native 64-bit tools for compilation, you must start the special Visual Studio x64 Win64 Command prompt provided with the Visual Studio installation on 64-bit machines

Builds from the Visual Studio IDE are also affected by this problem. In order to build 64-bit add-ins from the IDE, you must start it with devenv /useenv from the special 64-bit command prompt.

COM addin deployment on Windows Vista and Windows 7

Deploying COM addins on a machine running Microsoft Windows Vista or Windows 7 requires special considerations. In general it's important to understand that in order for Creo Elements/Direct Modeling to find and use COM addins, they must be registered in the Windows registry. Before Vista, COM addins were written to register in the HKEY_LOCAL_MACHINE part of the registry, which required administrator privileges. As a fallback, Creo Elements/Direct Modeling would try to register the addin on the fly with restricted user privileges (by redirecting the registration to the HKEY_CURRENT_USER part of the registry). This is required for network deployment scenarios, where the addin will not be installed on a PC, but simply made available via a well-known network drive (see Locating addins above).

This redirection mechanism is no longer supported by Microsoft in Windows Vista. This means that the developer of a COM addin must decide at development time about the deployment strategy: Will the COM addin be deployed by an administrator on each local PC, or will the addin be registered by a standard user? If there is no requirement for administrative rights during addin deployment, we strongly suggest you write your COM addins so that they register themselves in the HKEY_CURRENT_USER portion of the registry. Otherwise addin deployment at customer sites will fail to support network deployment scenarios.

If the COM addin registration requires administrative rights, you must make sure it is installed by an administrator at the customer site. In particular, this can be required if your addin is not a standalone addin, but needs to be installed as part of another application that wants to integrate with Creo Elements/Direct Modeling. The COM add-in wizard provides options for both deployment strategies.

Building .NET add-ins

.NET add-ins must be compiled with Visual Studio 2015, using the .NET frameworks 4.0. Project references must be set to the CoCreate.OsdmServer.dll and CoCreate.OsdmObjects.dll object model assemblies.

Locating add-ins

During startup, Creo Elements/Direct Modeling will search several directories for installed add-ins, and will attempt to load any add-ins it finds there. The search order is as follows:

Searching the directories in this order allows control over which add-ins are made available globally within the company, at a particular site, or for individual users. The Customization Concepts Guide in the online help documentation for Creo Elements/Direct Modeling explains how those directories can be configured.

In each of these directories, Creo Elements/Direct Modeling will try to locate a folder called Addins. Add-ins must be installed to this folder. Here is a simple example:

   
   |
   |-- Addins
   |
   |------ TestAddin
            |
            |------- TestAddin.cfg
            |------- TestAddin.dll

Creo Elements/Direct Modeling assumes that a subdirectory TestAddin will contain a configuration file called TestAddin.cfg which provides detailed information about the add-in. Most add-ins will be compiled into a single DLL as shown above. While it is convenient to install the add-in DLL at the same location as the associated configuration file, this is not a strict requirement for COM add-ins, and other installation options are available.

Add-in configuration file

The add-in configuration file describes, in XML format, add-in attributes such as its name, description, and ID. They are generated by the add-in wizard and typically you only need to adjust the ModuleName and Description tags.

A sample COM add-in configuration file:

   <?xml version="1.0" encoding="utf-8" ?>
   <AddinConfig>
   <ProgID>TestAddin
   </ProgID>
                                                                
   <VersionProgID>
   </VersionProgID>
                                                                
   <ModuleName>My first test add-in
   </ModuleName>
                                                                
   <Description>
   </Description>
                                                                
   <CommandLineSafe>false
   </CommandLineSafe>
   </AddinConfig>

A sample .NET add-in configuration file:

   <?xml version="1.0" encoding="utf-8" ?>
   <AddinConfig>
   <AssemblyFile>TestAddin.dll
   </AssemblyFile>
                                                                
   <AddinClass> MyCompanyName.TestAddin
   </AddinClass>
                                                                
   <AlternativeUniqueName> MyCompanyName.TestAddin
   </AlternativeUniqueName>
                                                                
   <UseDefaultAppDomain> true
   </UseDefaultAppDomain>

   <ModuleName>My first .NET add-in
   </ModuleName>
                                                                
   <Description>
   </Description>
                                                                
   <CommandLineSafe>false
   </CommandLineSafe>
   </AddinConfig>

Ignoring the XML boilerplate, this is what the individual tags mean:

ProgID (COM add-ins only)
This will be familiar to COM programmers, especially to those using scripting languages or Visual Basic. COM objects are identified with a globally unique identifier (GUID) which consists of a long sequence of letters and digits. The ProgID is the human-readable version of the GUID. While not guaranteed to be unique, it is usually preferred over specifying the GUID. Each COM server has its own ProgID and can be located using this ID. Add-ins are, in fact, both COM clients and COM servers, since they also implement several interfaces (see below), which is why the add-in also needs to have its own ProgID.
VersionProgID (COM add-ins only)
This ProgID contains version information, which is important when deploying multiple versions of an add-in on the same machine.
AssemblyFile (.NET add-ins only)
The filename of the .NET assembly containing the add-in.
AddinClass (.NET add-ins only)
The name of the class implementing the IOsdmAddin interface.
AlternativeUniqueName (.NET add-ins only)
Optional. A unique name by which to uniquely identify the add-in. To avoid name clashes with other add-ins in customer environments, make sure to prepend this name with your company name.
UseDefaultAppDomain (.NET add-ins only)
Currently, this value should always be set to true.
ModuleName
This is the name of the add-in as it appears in Creo Elements/Direct Modeling's user interface (Application/Modules/Add-Ins dialog).
Description
A short description of what the add-in does; to be displayed in Creo Elements/Direct Modeling's UI.
CommandLineSafe
Should be set to false if your add-in displays UI while its code is executed.

The parameters Description and CommandLineSafe are currently not implemented.

COM add-in installation

In the XML example above, the name of the file which contains the actual add-in code is not explicitly specified. To find and load the add-in code, Creo Elements/Direct Modeling proceeds as follows:

Step 1
If Creo Elements/Direct Modeling cannot find the specified ProgID in the registry, it will search for a DLL in the add-in directory which has the same basename as the configuration file; in our example, that would be TestAddin.dll. If it finds this file, it will try to register it with COM by running regsvr32 on it. On Vista, the success of this registration attempt depends on the elevation state of the application, and the kind of registration code in the add-in. If the add-in registers into the HKCR and HKLM branches of the registry, on-the-fly registration will only work if the application runs elevated. If the registration code writes to HKCU, on-the-fly registration will only work if the application is not elevated.
Step 2
If the ProgID is now found in the registry, Creo Elements/Direct Modeling will use the standard COM mechanism (i.e. CoCreateInstance) to load the add-in code.

The recommended way to install a COM add-in is as follows:

If you know that end users will always have sufficient privileges to write to the registry, you can also skip the last registration step and have Creo Elements/Direct Modeling perform it for you.

.NET add-in installation

See the notes on COM add-in installation. Differences:

Associated Lisp files

When Creo Elements/Direct Modeling activates an add-in, it checks whether an associated Lisp file was deployed in the same directory where the configuration file was found. For example, if the configuration file is called TestAddin.cfg, and the same directory contains a file TestAddin.lsp, that Lisp file will be loaded. This can be used to integrate add-in functionality with the customization capabilities provided in the Developer's Kit; for example, user interface elements can be defined in Lisp which control the user interaction and then execute functionality in the add-in upon user request. See Integrating add-ins and Lisp for more details.

Add-in wizard

For use with the COM/.NET API, we provide an add-in wizard which can be installed in Visual Studio. Running the add-in wizard within Visual Studio will automatically produce an add-in client with the following features:

Wizards are currently available for C++ COM and C# add-ins. See The Creo Elements/Direct Modeling Add-in wizard for details on installation and usage.

Add-in interfaces

Creo Elements/Direct Modeling assumes that the add-in implements certain standard interfaces through which it can communicate with the add-in. Creo Elements/Direct Modeling will query the add-in for those interfaces and call them as appropriate.

The files OsdmServer.tlb and CoCreate.OsdmServer.dll contain the required add-in interface definitions for COM and .NET clients, respectively.

IOsdmAddin interface

This interface contains functions that control the lifecycle of an add-in. The most important member functions are:

OnConnection
Called when Creo Elements/Direct Modeling has loaded the add-in and now wants to activate it. Creo Elements/Direct Modeling passes an IApplication interface pointer which refers to its main application interface and which can be used by the add-in to subsequently access the rest of the object model.
OnDisconnection
Called when Creo Elements/Direct Modeling disconnects from the add-in, for example when a user disables an add-in from the Application/Modules dialog. All interface and object handles to Creo Elements/Direct Modeling or other add-ins must be released here.
OnBeginShutdown
Called when the application is about to shut down.

IOsdmCommandTarget interface

Add-ins can register one or several commands with the application. Typically, each such command is represented in the UI by a button in the add-in's own menu. IOsdmCommandTarget provides member functions to control user interaction:

Execute
Called with the name of the command to be executed. Triggered when the user clicks the button which represents the command in the user interface.
QueryStatus
Called with the name of the command for which status information is to be retrieved. This can be used by Creo Elements/Direct Modeling's UI components to check whether a command button should be displayed as enabled or disabled. (Currently not used by Creo Elements/Direct Modeling yet.)

Default dispatch interface

This interface is optional. If the add-in implements a default dispatch interface, methods in this interface can be called via the invoke-addin Lisp command. This provides a (preferred) alternative to the IOsdmCommandTarget.Execute interface. For details, see the section on Lisp interoperability.

IOsdmAddinTests interface

This interface is optional. Its purpose is to integrate unit tests in the add-in into Creo Elements/Direct Modeling's unit test infrastructure.

Count
Inquires from the add-in the number of unit tests defined in the add-in.
TestName
Inquires the name of the unit test specified by an index between 0 and Count - 1.
SetUp
To be called before RunTest. Sets up the test environment in the add-in.
TearDown
To be called after the last unit test has been executed. Releases all resources acquired during tests, including global interface pointers.
RunTest
Runs the unit test specified by an index.

Add-Ins dialog

Add-ins generated by the add-in wizard optionally also implement the test interfaces. To run the tests for an add-in from within Creo Elements/Direct Modeling, proceed as follows:

Step 1: Start Creo Elements/Direct Modeling. Check the Applications/Modules/Add-Ins dialog to see whether the add-ins you want to test have been detected during startup.

Step 2: Using the dialog, activate the add-ins which you want to test.

Step 3: Open the console window (View/Console ). Test results and messages will appear in this window when you run tests.

Step 4: To run test 0 from the set of tests implemented in the add-in, enter the following Lisp command in the user command line:

    (f2::run-addin-test "yourprogid" 0)

"yourprogid" is the ProgID of the add-in you want to test (see also the section on add-in configuration files) The result of the tests are displayed in the console window.

Run add-in tests manually

Set-up and tear-down functions can be called as follows:

    (f2::setup-addin-tests "yourprogid")
    ;; execute any number of tests now using f2::run-addin-test
    (f2::teardown-addin-tests "yourprogid")

For development partners, we are preparing more convenient ways to run unit tests in add-ins (using a so-called "unit test browser").

External clients

External COM clients can be either vtable ("raw COM") clients or dispatch clients. If you are not familiar with these terms: They mean that it is possible to use both strictly-typed languages such as C or C++ and loosely-typed languages such as VBscript to interface to Creo Elements/Direct Modeling.

To build 64-bit external COM clients, it is important to use the right development environment. For details, please refer to the notes above on building 64-bit COM addins.

External .NET clients are currently not supported.

Choosing the right client type

Add-ins run in the main thread of the Creo Elements/Direct Modeling process, so there is no interprocess communication and only low parameter marshaling overhead. Therefore, add-ins should be used for all integration tasks which require frequent calls into the Creo Elements/Direct Modeling object model.

Typical add-in design models:

Add-ins are loaded and activated by an instance of Creo Elements/Direct Modeling which is typically started by and end user, so they often provide a Modeling-compliant user interface through which users can interact with the add-in's functionality.

External clients typically instantiate Creo Elements/Direct Modeling in the background and drive this instance with their requests; there is usually no user interaction within Creo Elements/Direct Modeling. In scenarios where performance is less important than flexibility and independence from Creo Elements/Direct Modeling, external clients can be a better choice. External clients are best used in scenarios where the time to instantiate the server and to communicate with the server is significantly lower than the actual computational task at hand.