Request

Response

    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 ComponentUse InsteadKey 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();
    
    Show More

    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
    };
    
    Show More

    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();
    
    Show More

    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);
    
    Show More

    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();
    
    Show More

    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 */
    };
    
    Show More

    InteropBridgeOptions Properties

    PropertyTypeRequiredDescription
    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 = true on FeatureCapabilities if your connector is in beta or early access
    • [ ] Set ContactSupportUrl on InteropBridgeOptions to your connector’s support channel (recommended — if omitted, support requests from your users will be misdirected)
    • [ ] Set IsBeta = true on any custom form fields that expose experimental options

    Update Code

    • [ ] Replace using Autodesk.DataExchange.UI; with using Autodesk.DataExchange.UI.Core;
    • [ ] Change Application to IInteropBridge
    • [ ] Replace new Application() with InteropBridgeFactory.Create()
    • [ ] Update initialization to two-step: InitializeAsync() then LaunchConnectorUiAsync()
    • [ ] Change property name from BaseExchangeModel to Exchange
    • [ ] Add Invoker property with IMainThreadInvoker implementation
    • [ ] Set HostWindowHandle in InteropBridgeOptions (replaces application.WindowHandle)
    • [ ] Replace Hide()/Close() with SetWindowState() or DestroyAsync()
    • [ ] Update ShowNotification() to SendNotification() with Severity enum
    • [ ] Remove ClearAllNotification() calls
    • [ ] Replace AdvanceLoadExchangeEvent with ICustomFormFactory
    • [ ] Update Configuration to InteropBridgeOptions

    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:

    1. InitializeAsync() completed successfully
    2. LaunchConnectorUiAsync() awaited properly
    3. HostWindowHandle is valid (or IntPtr.Zero for 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.


    API Reference

    Core Interfaces

    Methods

    Enums