Add-in Architecture and the SolidWorks Integration Model

01Executive summary

02The three-part definition

The interface contract is deliberately small. ISwAddin asks for two members and nothing else: one invoked when SolidWorks loads your assembly into memory, and one invoked when it unloads it. All of the apparent complexity of add-in development — menus, pages, notifications, installers — is built on top of that pair.

bool ConnectToSW(object ThisSW, int Cookie)
bool DisconnectFromSW()

The second condition is COM registration. A managed class library is invisible to SolidWorks until the assembly is registered for COM interop and the class is marked visible with a stable GUID. The third condition is discovery: an entry under the SolidWorks add-ins registry key, named for that same GUID, so the application knows a candidate exists and can ask COM to produce it. Miss any one and you have a correctly compiled assembly that never loads.

03Load-to-release lifecycle

Understanding the order of events removes most of the mystery from add-in debugging. The sequence below runs on every SolidWorks session in which your add-in is enabled.

1. Build timeAssembly compiled and registered

   The class library is compiled to a DLL. Registration for COM interop publishes the class under its GUID and runs your registration hook, which writes the SolidWorks discovery keys.

2. Session startSolidWorks enumerates candidates

   SolidWorks reads its add-ins registry key, collects the GUIDs it finds and consults the per-user start-up key to decide which of them to load immediately rather than on demand.

3. ActivationCOM instantiates the class

   The operating system resolves the GUID to your assembly, the runtime loads it into the SolidWorks process, and an instance of your add-in class is created.

4. ConnectConnectToSW is called

   You receive the application object and the cookie. This is where you register callback routing, acquire the Command Manager, build menus and toolbars, and attach application-level event handlers.

5. RuntimeCallbacks and notifications flow

   Menu clicks, page control events and document notifications are dispatched into your instance for as long as the add-in stays loaded.

6. DisconnectDisconnectFromSW is called

   Triggered by the user unloading the add-in or by SolidWorks closing. Remove command groups, detach every event handler, close any open pages and release interop references.

7. ReleaseReferences dropped and memory reclaimed

   Null every field holding a SolidWorks object and request collection so the runtime releases the underlying COM references promptly rather than at an arbitrary later point.

04The in-process model and what it buys you

An add-in is loaded by SolidWorks into the SolidWorks process and runs on the same thread. That single fact produces most of the practical differences between add-ins and stand-alone clients.

05The object graph you will be working in

Almost every add-in resolves the same small set of root objects during connect, then reaches the rest of the model through them.

• ISldWorksThe application root, handed to you as the connect parameter. Session settings, document creation, user messaging.
  • ICommandManagerAcquired with the cookie. Owns command groups, which in turn own the menu and toolbar items your add-in publishes.
  • IModelDoc2The active document. Its concrete type — part, assembly or drawing — determines which event interface and which feature set apply.
    • ISelectionMgrWhat the user currently has selected, and the typed object behind that selection.
    • Custom property setsThe document metadata most business logic actually reads and writes.
  • IPropertyManagerPage2A page hosted in the SolidWorks task panel, created through the application object and driven by a handler class you supply.

[Guid("00000000-0000-0000-0000-000000000000"), ComVisible(true)]
[SwAddin(Title = "KEVOS Example",
         Description = "Demonstration add-in",
         LoadAtStartup = true)]
public class KevosAddin : ISwAddin
{
    private ISldWorks _sw;
    private int _cookie;

    public bool ConnectToSW(object ThisSW, int Cookie)
    {
        _sw = (ISldWorks)ThisSW;
        _cookie = Cookie;

        // Route callbacks back to this instance before anything
        // that can raise one is created.
        _sw.SetAddinCallbackInfo(0, this, _cookie);

        BuildCommands();
        AttachApplicationEvents();
        return true;
    }

    public bool DisconnectFromSW()
    {
        DetachApplicationEvents();
        RemoveCommands();

        _sw = null;
        GC.Collect();
        GC.WaitForPendingFinalizers();
        return true;
    }
}

06Cookies and callback routing

SolidWorks needs to know which object should receive the callbacks raised on your behalf. That association is established by a single call made during connect, before any command or page that could raise a callback exists.

void SetAddinCallbackInfo(int Reserved, object AddinObject, int Cookie)

Because callbacks are resolved by name at the point the user acts, not by delegate at the point the command is created, a mistyped callback name compiles cleanly and fails silently at runtime. This is one of the most common defects in first add-ins, and the reason for treating callback names as constants rather than string literals scattered through the command-building code.

07Releasing interop references

Interop objects hold references to unmanaged COM objects. Leaving them to be collected whenever the runtime feels like it produces the classic symptom set: SolidWorks refuses to close cleanly, an orphaned process lingers, or documents stay locked after the add-in unloads.

1. Null the fields

   Set every field holding a SolidWorks type — application, model, component, page and control references — to null in the teardown path.

2. Detach first

   Remove event handlers before nulling the object that raises them, otherwise the handler keeps the source alive.

3. Force collection

   Request a collection so the release happens at a moment you choose rather than at an arbitrary later point in the host process.

4. Verify on exit

   Close SolidWorks with the add-in loaded and confirm the process actually terminates. This single test catches most reference leaks.

08Quick reference

Add-in test

Implements ISwAddin + handles connect/disconnect + registered with COM. All three, or it is a stand-alone.

Interface members

ConnectToSW(object, int) and DisconnectFromSW(), both returning bool.

Assembly type

Class library (DLL). A stand-alone client is an executable.

Process model

In-process; same process and thread as the host application.

Discovery

Registry entry named for the class GUID under the SolidWorks add-ins key, plus a per-user start-up flag.

Callback routing

SetAddinCallbackInfo(0, this, Cookie), called during connect.

Teardown obligations

Detach events, remove command groups, close pages, null references, collect.

09Where this leads

Continue in this pathway

• Part 01Add-in architecture and the integration model
• Part 02Development environment and project configuration
• Part 03COM registration and add-in discovery
• Part 04Command Manager, menus and toolbars
• Part 05Property Manager Pages and the control model
• Part 06Event and notification architecture
• Part 07Add-in, stand-alone or hybrid
• Part 08Planning, structure and debugging discipline
• Part 09Deployment methods and installer engineering
• Part 10Licensing, distribution and commercialisation