Plugin Lifecycle

Full sequence

sequenceDiagram
    participant HS as HydroSym
    participant P as Plugin

    Note over HS: Application startup
    HS->>P: GetInfo({})
    P-->>HS: {name, version, apiVersion, capabilities, menus}
    Note over HS: Verify apiVersion compatibility
    HS->>P: Initialize({hydrosymVersion, configPath, windowsUser, ...})
    P-->>HS: {} (OK)
    Note over HS: Build menus from GetInfo.menus

    Note over HS: ... user works ...

    Note over HS: Application shutdown
    HS->>P: Finalize({})
    P-->>HS: {} (OK)
    Note over HS: Unload DLL / terminate process

Step 1: GetInfo

GetInfo is called immediately after loading, before anything else. HydroSym uses the response to:

1. Check apiVersion — if not compatible, HydroSym logs an error and aborts loading.
2. Record capabilities — only listed methods will ever be called.
3. Build the Plugin menu from menus.
4. Decide whether to add a Settings item (hasSettings).

Do not open database connections or perform network calls in GetInfo. If it throws, the plugin fails to load. Keep it fast and stateless.

Step 2: Initialize

Initialize is called once, after GetInfo, with context:

Field	Description
hydrosymVersion	Running HydroSym version — use for version-specific behavior
configPath	Path to your config file — read connection strings, options
hydrosymDataPath	HydroSym's data directory — rarely needed
mainWindowHandle	HWND of the main window — use as parent for modal dialogs
windowsUser	Windows username — use for Windows-integrated authentication
windowsDomain	Domain name, if domain-joined

This is the place to: - Read your config file. - Open and test your database connection. - Authenticate with your ERP or PDM system. - Load any data needed for fast GetComponentParameters responses (e.g., a product catalog cache).

If Initialize throws PluginException, HydroSym shows the error to the user and disables the plugin for this session. The plugin is not unloaded.

Step 3: Normal operation

After Initialize, HydroSym calls your plugin based on user actions and the open project. See Call Sequences for when each method is called.

Step 4: Finalize

Finalize is called once, when HydroSym shuts down (or when the plugin is being disabled). Use it to: - Close database connections. - Flush any pending writes. - Release external resources.

No methods are called after Finalize. The DLL is unloaded immediately after Finalize returns.

Finalize on crash

If HydroSym crashes, Finalize is not called. Design your resources to be recoverable on next startup (e.g., do not leave exclusive locks held).

Failure behavior summary

Stage	Plugin throws	HydroSym behavior
GetInfo	Any error	Log error, abort plugin load, no menus added
Initialize	PluginException	Show error dialog, plugin disabled for session
Normal method	PluginException	Show error dialog, return ERROR result code
Normal method	Unhandled exception	DLL: crash propagates; Process: process terminates, HydroSym shows error
Finalize	Any error	Logged, DLL unloaded anyway