Transitioning to UI Bridge
Overview
The Data Exchange SDK deprecates the legacy Application class-based UI components (Autodesk.DataExchange.UI namespace) and introduces the UI Bridge pattern (Autodesk.DataExchange.UI.Core).
What “Deprecated” Means:
Deprecated components are marked [Obsolete] and are removed in a later major SDK release. They still function in this release, but you should:
- Avoid using deprecated methods in new code
- Migrate existing code to UI Bridge as soon as possible
- Expect compiler warnings when using deprecated components
- Plan for breaking changes when deprecated components are removed
Support for deprecated components will end when they are removed from the SDK. After removal, code using these components will not compile.
Current Status:
- UI Bridge - Current, recommended approach (use this)
- Legacy UI components - Deprecated, marked
[Obsolete], still functional but will be removed - Timeline - Legacy components will be removed in the next major SDK version
Migration Quick Reference
Note: Components in the “Avoid” column are marked [Obsolete] in the SDK source code and will generate compiler warnings. They are removed in a later release.
| Deprecated Component | Use Instead | Key Difference |
|---|---|---|
new Application() |
InteropBridgeFactory.Create() |
Requires whitelisted assembly |
application.Show() |
await bridge.LaunchConnectorUiAsync() |
Two-step: Initialize then Launch |
application.Hide() |
bridge.SetWindowState(WindowState.Hide) |
Enum-based state |
application.Close() |
bridge.SetWindowState(WindowState.Close) |
Closes window but keeps bridge alive |
application.Dispose() |
await bridge.DestroyAsync() |
Full cleanup and resource disposal |
application.ShowNotification() |
bridge.SendNotification() |
Uses Severity enum, supports timeout |
application.ClearAllNotification() |
Not needed | Notifications auto-clear |
application.Refresh() |
bridge.RefreshExchangeList() |
More specific method name |
application.SetDocumentName() |
bridge.SetDocumentName() |
Direct mapping |
application.SetProgressMessage() |
bridge.SetProgressMessage() |
Direct mapping |
application.WindowHandle |
bridgeOptions.HostWindowHandle |
Set during bridge configuration |
application.AdvanceLoadExchangeEvent |
ICustomFormFactory |
Custom form for create/load |
NotificationType enum |
Severity enum |
Information→Info, adds Success |
Configuration class |
InteropBridgeOptions class |
New configuration model |
Required Namespaces
using Autodesk.DataExchange.UI.Core; // InteropBridgeOptions, InteropBridgeFactory
using Autodesk.DataExchange.UI.Core.Interfaces; // IInteropBridge, IMainThreadInvoker
using Autodesk.DataExchange.UI.Core.Enums; // WindowState, Severity
using Autodesk.DataExchange.Interface; // IClient, IExchange
Note: The legacy Application class was in Autodesk.DataExchange.UI, which is now deprecated.
Basic UI Initialization
Deprecated Pattern
using Autodesk.DataExchange.UI;
var config = new Configuration
{
Title = "My Connector",
HideLoadDataExchangePanel = false
};
application = new Application(exchangeModel, config);
application.Show();
Current Pattern (Recommended)
using System.Windows.Threading;
// Create options from client (auto-populates most properties)
var bridgeOptions = InteropBridgeOptions.FromClient(client);
// Set required properties
bridgeOptions.Exchange = exchangeModel;
bridgeOptions.Invoker = new MainThreadInvoker(Dispatcher.CurrentDispatcher);
bridgeOptions.HostWindowHandle = GetHostWindowHandle(); // or IntPtr.Zero
// Optional properties
bridgeOptions.CustomFormFactory = customFormFactory;
bridgeOptions.HostDataProvider = hostDataProvider;
// Create, initialize, and launch
bridge = InteropBridgeFactory.Create(bridgeOptions);
await bridge.InitializeAsync();
await bridge.LaunchConnectorUiAsync();
Key Changes:
- Property is
Exchange, notBaseExchangeModel IMainThreadInvokerrequired for thread safety- Two-step process:
InitializeAsync()thenLaunchConnectorUiAsync() - Use
FromClient()method to auto-populate required properties
Manual Configuration (Advanced)
var bridgeOptions = new InteropBridgeOptions
{
HostApplicationName = "My Host App",
HostApplicationVersion = "1.0.0",
ConnectorName = "My Connector",
ConnectorVersion = "1.0.0",
ConnectorRootPath = @"C:\Path\To\Connector",
Environment = "prod", // or "stg", "dev"
Auth = authProvider,
Logger = logger,
HostingProvider = hostingProvider,
Exchange = exchangeModel,
Invoker = invoker,
HostWindowHandle = hostWindowHandle
};
Window Lifecycle
// Launch UI (requires Initialize first)
await bridge.LaunchConnectorUiAsync();
// Hide/Show window (bridge remains alive)
bridge.SetWindowState(WindowState.Hide);
bridge.SetWindowState(WindowState.Show);
// Close window (bridge remains alive, can relaunch)
bridge.SetWindowState(WindowState.Close);
await bridge.LaunchConnectorUiAsync(); // Can relaunch
// Full cleanup and disposal
await bridge.DestroyAsync();
Important: SetWindowState(WindowState.Close) only closes the UI window. The bridge instance remains alive and you can call LaunchConnectorUiAsync() again. Use DestroyAsync() for complete cleanup.
Notifications
// Info notification (auto-closes after 5 seconds)
bridge.SendNotification("Exchange loaded successfully", Severity.Info);
// Error notification (stays visible)
bridge.SendNotification("Failed to load exchange", Severity.Error, timeoutMs: 0);
// Warning with custom timeout
bridge.SendNotification("Exchange update available", Severity.Warning, timeoutMs: 10000);
Enum Mapping: NotificationType.Information → Severity.Info, NotificationType.Error → Severity.Error, NotificationType.Warning → Severity.Warning, (new) Severity.Success
Custom Forms (Replacing AdvanceLoadExchangeEvent)
The AdvanceLoadExchangeEvent has been replaced by the ICustomFormFactory pattern for customizing exchange creation and loading.
Deprecated:
application.AdvanceLoadExchangeEvent += (sender, args) => { /* ... */ };
Current:
// Implement ICustomFormFactory
public class MyCustomFormFactory : ICustomFormFactory
{
public ICustomForm CreateForm(CustomFormContext context)
{
// Return custom form for create/load operations
return new MyCustomForm(context);
}
}
// Set in bridge options
bridgeOptions.CustomFormFactory = new MyCustomFormFactory();
For complete implementation details, see Customizing Exchange Creation and Loading.
Monitoring Bridge State
bridge.ClientStateChanged += (sender, args) =>
{
if (args.IsConnected) { /* UI process connected */ }
};
bridge.ServerStateChanged += (sender, args) =>
{
/* Bridge server started: args.ConnectionString */
};
InteropBridgeOptions Properties
| Property | Type | Required | Description |
|---|---|---|---|
HostApplicationName |
string |
Yes | Name of the host application |
HostApplicationVersion |
string |
Yes | Version of host application |
ConnectorName |
string |
Yes | Display name of your connector |
ConnectorVersion |
string |
Yes | Version of your connector |
ConnectorRootPath |
string |
Yes | Root installation path of connector |
Environment |
string |
Yes | "prod", "stg", or "dev" |
Auth |
IAuth |
Yes | Authentication provider |
Logger |
ILogger |
Yes | Logger instance |
HostingProvider |
IHostingProvider |
Yes | Hosting provider instance |
Exchange |
IExchange |
Yes | Your exchange model implementation |
Invoker |
IMainThreadInvoker |
Yes | Main thread invoker for thread safety |
HostWindowHandle |
IntPtr |
Recommended | Parent window handle (or IntPtr.Zero) |
EventsController |
IEventsController |
No | For exchange update subscriptions |
CustomFormFactory |
ICustomFormFactory |
No | For custom forms |
HostDataProvider |
IHostDataProvider |
No | For host-specific data |
FeedbackUrl |
string |
No | Custom feedback URL |
ContactSupportUrl |
string |
Recommended | URL or mailto: link for the Contact Support action in the Info menu. Always set this to your connector's support channel to ensure users can reach you. |
Tip: Use InteropBridgeOptions.FromClient(client) to auto-populate most required properties.
Migration Checklist
New v8.0.0 Options (Optional)
- [ ] Set
ShowTitleBarBetaBadge = trueonFeatureCapabilitiesif your connector is in beta or early access - [ ] Set
ContactSupportUrlonInteropBridgeOptionsto your connector’s support channel (recommended — if omitted, support requests from your users will be misdirected) - [ ] Set
IsBeta = trueon any custom form fields that expose experimental options
Update Code
- [ ] Replace
using Autodesk.DataExchange.UI;withusing Autodesk.DataExchange.UI.Core; - [ ] Change
ApplicationtoIInteropBridge - [ ] Replace
new Application()withInteropBridgeFactory.Create() - [ ] Update initialization to two-step:
InitializeAsync()thenLaunchConnectorUiAsync() - [ ] Change property name from
BaseExchangeModeltoExchange - [ ] Add
Invokerproperty withIMainThreadInvokerimplementation - [ ] Set
HostWindowHandleinInteropBridgeOptions(replacesapplication.WindowHandle) - [ ] Replace
Hide()/Close()withSetWindowState()orDestroyAsync() - [ ] Update
ShowNotification()toSendNotification()withSeverityenum - [ ] Remove
ClearAllNotification()calls - [ ] Replace
AdvanceLoadExchangeEventwithICustomFormFactory - [ ] Update
ConfigurationtoInteropBridgeOptions
Test
- [ ] Verify UI displays correctly
- [ ] Test window state changes (show/hide/close)
- [ ] Verify notifications display and timeout correctly
- [ ] Test exchange operations (load, create, update)
- [ ] Verify
DestroyAsync()releases resources properly - [ ] Test relaunch after
SetWindowState(Close)
Troubleshooting
InitializeAsync Failed
Cause: Invoker is null, Exchange is null, or required properties not set.
Solution: Use InteropBridgeOptions.FromClient(client) to auto-populate required properties. Verify Exchange and Invoker are set.
UI Window Does Not Appear
Check:
InitializeAsync()completed successfullyLaunchConnectorUiAsync()awaited properlyHostWindowHandleis valid (orIntPtr.Zerofor standalone)
Window Not Parented Correctly
Solution: Set bridgeOptions.HostWindowHandle = GetHostWindowHandle() or use IntPtr.Zero for standalone window.
Notifications Not Appearing
Solution: Check bridge.ClientConnected property before calling SendNotification(). For error notifications, use timeoutMs: 0 to prevent auto-close.