Request

Response

    Migration Guide

    This guide helps you update your connector to SDK v7.6.0. It is cumulative, covering every change you may still need to make from a v7.2.x baseline forward — across the v7.4.0, v7.5.0, and v7.6.0 releases — because those releases share this single guide.

    The work falls into these areas: the exception namespace reorganization, new members added to interfaces you may implement, the geometry namespace migration and engine upgrade, removal of the local viewable-generation API, the IElement/IElementDataModel/IElementGeometry return-type migration, strongly typed validation hooks, the ADP Analytics package split, sync pipeline changes, the new classification and design-instancing model, and optional features you can adopt when they fit your connector.

    Start with Already on 7.4.0? to see only what applies to the version you are coming from.

    Estimated time: 60–120 minutes for a full upgrade from 7.4.x. Considerably less if you already shipped on 7.5.x — see the fast path below.


    At a Glance

    This table is a complete inventory of everything this guide covers, regardless of which release introduced it. To see only the work that applies to your upgrade, use the release-scoped tables in Already on 7.4.0? instead.

    ChangeTypeAction Required
    Exchange description field (Create modal) New Feature None
    Revision Note field (Update dialog) New Feature None — read exchangeItem.Description if needed
    Version chip tooltip shows revision notes New Feature None
    ShowTitleBarBetaBadge on FeatureCapabilities New Feature None — opt in if needed
    ContactSupportUrl on InteropBridgeOptions New Feature Recommended — set to your connector's support channel
    IsBeta on input descriptors New Feature None — opt in if needed
    FeatureCapabilities class Non-Breaking Migrate to avoid deprecation warnings
    Runtime SetApplicationMode on IInteropBridge New Feature Adopt if you need context-dependent UI modes
    Fallback callback URLs for authentication New Feature Adopt to handle port conflicts
    .NET 10 support New Feature None — existing net8/net48 projects continue to work
    Parameter Service (out-of-process) Internal Ensure ParameterService/ folder is included in deployments
    IElement.RenderStyle property Non-Breaking Adopt the instance-over-geometry precedence rule if your connector renders colors
    SDKOptions.WarmupServices flag Non-Breaking Opt in to pre-warm geometry translation; note the default flip on SDKOptionsDefaultSetup
    Exception namespace flattening (CustomExceptions removed) Breaking Find-replace across codebase
    New members on existing interfaces Breaking Add to any custom implementations
    ADP Analytics moved to a standalone Abstractions package Breaking Add the package reference, update using directives, and register IAdpAnalytics yourself — see ADP Analytics Moved to a Standalone Package
    Geometry engine upgraded to GUSDK 0.9.4 Breaking Rebuild and repack so you deploy the new native binaries, then verify geometry translation
    zh-CN Connector UI locale removed Breaking Supply the locale downstream if you ship a Chinese UI
    Element, ElementDataModel, ElementGeometry now returned as IElement, IElementDataModel, IElementGeometry Breaking Update explicit type declarations wherever your code touches one of ~20 affected SDK members — see Element, ElementDataModel, and ElementGeometry Are Now Returned as Interfaces
    Strongly-typed validation hook parameters (ValidateCanCreateExchangeAsync, ValidateCanUpdateExchangeAsync, ValidateGetLatestExchangeAsync, ValidateGetLatestExchangeDetailsAsync) Breaking Update override signatures to the typed parameters
    Geometry namespace migration (GUSDK 0.9.3) Breaking Update using directives from Autodesk.GeometryPrimitives.* to Autodesk.GeometryUtilities.PrimitivesAPI[.IO]
    GenerateViewableAsync removed Breaking Remove calls; viewables now generate automatically during sync
    ViewableGenerationStarted / ViewableGenerationCompleted events removed Breaking Remove event subscriptions
    ViewableGenerationStatus, ViewableGenerationException, ViewableDetails removed Breaking Remove references
    ViewDataInfoData, GenerateSVFViewableAsync removed Breaking Remove from test mocks or advanced geometry client code
    Region parameter on schema calls (Autodesk Schema Registry — ASR) Breaking Pass region to GetSchemaAsync / GetSchemasAsync if you call the schema SDK directly
    Streaming sync pipeline Changed No code change for most connectors; review sync behavior and optional tuning
    Mesh translation output path Changed Ensure connector workspace/storage path is configured — empty paths fail fast
    Autodesk.Newtonsoft.Json internalized Changed Add Newtonsoft.Json from NuGet.org if your connector code uses it
    ForceRefresh flag on ExchangeSearchFilter New Feature None — opt in to bypass your exchange-list cache on user-initiated refresh
    GeometryUtilitiesService Client (new subsystem) New Feature None — existing geometry code continues to work
    IExchangeContextForm for context-aware Load forms New Feature Adopt if Load forms need exchange metadata
    UseConversionApiForGeometryTranslation on GeometryConfiguration New Feature None — on by default; review if your connector explicitly sets it to false. Legacy GUSDK Client APIs will be deprecated in an upcoming release
    SyncUploadConcurrency on GeometryConfiguration New Feature None — optional sync upload throughput tuning
    TuneThreadPool on GeometryConfiguration New Feature None — on by default; opt out only if your host tunes the thread pool
    Classify / ClassificationSystem New Feature Adopt to replace ad hoc category/family/type strings
    DefineType / SetType / AddTypeParameterAsync New Feature + Breaking (behavior) Adopt for new type-scoped code; review existing code if you define same-named types in different branches
    GetOrCreateDesignRef / InstantiateDesignBySourceId / GetDesignRefs New Feature Adopt for design instancing (blocks, families, sub-assemblies, nested blocks)
    DownloadExchangeAsUSD New Feature None — opt in to download an exchange as USD alongside OBJ, STEP, and IFC
    Delta pipeline for RetrieveLatestExchangeAsync Changed No code change — review retrieval behavior when you test
    Hardened authentication (retry with backoff, proactive refresh, per-request PKCE) Changed None
    Mirrored STEP geometry handled correctly Fixed None — verify against mirrored models if you export STEP
    Google.Protobuf consolidated to 3.30.1 Changed None unless your connector pins a different Google.Protobuf version
    SourceLink and .snupkg symbol packages New Feature None — optionally enable symbol loading to step into SDK sources
    Autodesk.DataExchange.DXLive package (skeleton) New Feature None — no action in this release
    InstantiateDesignById / GetDesignInstancesById / IDesign.ID Deprecated Move to the BySourceId equivalents and IDesign.SourceId to avoid deprecation warnings; the obsolete members are removed in the next major version
    ElementProperties class Deprecated Migrate to AddElement + Classify/DefineType to avoid deprecation warnings; the class will be removed in a future release
    IElementDataModel.GetElementById Deprecated Move to GetElementsBySourceId for all matches, or GetElementByUniqueId for one unambiguous element
    IElementDataModel.CreateDesignRef Deprecated Move to GetOrCreateDesignRef, which returns the existing design instead of throwing when the source identifier is already in use
    IClient.RetrieveLatestExchangeDataAsync Deprecated Move to RetrieveLatestExchangeAsync, which drops the revision arguments
    ConversionBatchSize on GeometryConfiguration now functional Fixed Review if set — a previously inert setting can now affect conversion memory/timing; retest if you set a positive value other than 10000, including the former default of 5000
    ---

    Start here

    Complete required work first, then optional adoption.

    1. Migration Steps 1–7 — fixes compile-time and startup breaks: exception namespaces, custom interface implementations, geometry using updates, viewable API removal, schema region (only if you call the schema SDK directly), the IElement/IElementDataModel/IElementGeometry return-type migration, and the ADP Analytics package split.
    2. Breaking change reference — Exception namespace · Interface members · Element/ElementDataModel/ElementGeometry interfaces · Geometry namespace · Geometry engine · Viewable generation · Schema region (ASR) · ADP Analytics · Chinese UI locale
    3. Steps 9–13 — test large-model sync, deploy (ParameterService/, Newtonsoft, storage path), review classification/types/design instancing, and verify the build.

    Sections between Start here and Migration Steps explain each change in depth. UI and performance features in New features and Step 10 are opt-in.

    Already on 7.4.0?

    If you completed the 7.4.0 migration guide (or shipped on 7.4.x), most of this page is review-only. Focus on what changed across 7.5.0 and 7.6.0.

    Introduced in 7.5.0 — skip these if you already shipped on 7.5.x:

    PriorityWhat to doSection / step
    Required Update geometry using directives (GeometryPrimitives → GeometryUtilities.PrimitivesAPI) Geometry namespace migration (GUSDK 0.9.3) · Step 3
    Required Remove local viewable-generation calls, events, and types Local viewable generation removed · Step 4
    Required if applicable Add ForceRefresh to a custom IExchangeSearchFilter implementation, and Error(string, Exception, string) to a custom ILogger implementation New Members on Existing Interfaces · Step 2
    Required if applicable Pass region on GetSchemaAsync / GetSchemasAsync Region required for schema (ASR) calls · Step 5
    Review Understand new sync pipeline behavior; tune only if needed How sync works in 7.6.0 · Sync Performance Tuning
    Review Confirm IStorage workspace path is set (mesh translation no longer falls back to %TEMP%) Mesh translation and output paths
    Deploy Add explicit Newtonsoft.Json NuGet reference if your connector code uses it Newtonsoft.Json packaging · Step 11
    Optional Honor ForceRefresh in GetExchangesAsync if you cache the exchange list Refresh trigger on the Exchange List · Step 10 (item 9)

    Introduced in 7.6.0 — required for every upgrade to this release:

    PriorityWhat to doSection / step
    Required Update explicit Element/ElementDataModel/ElementGeometry type declarations to IElement/IElementDataModel/IElementGeometry Element, ElementDataModel, and ElementGeometry Are Now Returned as Interfaces · Step 6
    Required Rebuild and repack so your connector deploys the GUSDK 0.9.4 native binaries, then verify geometry translation Geometry engine upgrade (GUSDK 0.9.4) · Step 3
    Required if applicable Reference Autodesk.DataExchange.ADPAnalytics.Abstractions and register IAdpAnalytics yourself ADP Analytics Moved to a Standalone Package · Step 7
    Required if applicable Update the four exchange validation hook override signatures to typed parameters Strongly-Typed Validation Hook Parameters
    Required if applicable Add the new IElement and IElementDataModel members to any custom implementation New Members on Existing Interfaces · Step 2
    Required if applicable Ship the zh-CN locale yourself if your connector offers a Chinese UI Chinese UI Locale Removed
    Required if applicable Retest large-model sync if you set ConversionBatchSize to a positive value other than 10000 — including 5000, the former default — it's now honored instead of silently ignored Sync Performance Tuning
    Required if applicable Review type-attribution behavior if your connector defines same-named types in different branches Type Attribution Fix · Step 12
    Review Test RetrieveLatestExchangeAsync, which now runs through a delta retrieval pipeline Delta Retrieval for RetrieveLatestExchangeAsync
    Optional Migrate off ElementProperties to AddElement + Classify/DefineType, and adopt design instancing Classification, Types, and Design Instancing
    Optional Offer USD as a download format USD Download Support

    You can skip for a 7.4 → 7.6 upgrade: Feature Capabilities, Exception namespace, the 7.4 interface members in Step 2, GeometryUtilitiesService Client, IExchangeContextForm, Adopt Instance-Level Render Style, Pre-warm Services, Fallback Callback URLs, .NET 10 Support, and Fire-and-forget async tasks — unless you have not adopted them yet.

    Suggested path: Step 3 → Step 4 → Step 5 (if needed) → Step 6 → Step 7 (if needed) → Step 9 → Step 11 → Step 12 (if applicable) → Step 13. Estimated time: 30–55 minutes.


    Prerequisites

    • SDK v7.2.x or later installed
    • Visual Studio 2022 or later
    • Access to your existing connector source code

    Note: If you’re migrating from v6.x or earlier, complete the v7.1.0 Migration Guide first, then return here.


    Feature Capabilities

    The FeatureCapabilities class lets your connector declare which UI features it supports. The Connector UI only shows buttons and menu items for capabilities you’ve enabled.

    What’s changing:

    Before (v7.1.x)After (v7.6.0)
    Feature flags on InteropBridgeOptions Consolidated in FeatureCapabilities object
    No control over "Select Elements" button New EnableSelectElements flag (on by default)

    This change is non-breaking. Your existing code continues to work, but you should migrate to avoid deprecation warnings.

    New FeatureCapabilities Class

    The SDK provides a dedicated class for UI feature configuration:

    namespace Autodesk.DataExchange.UI.Core
    {
        public class FeatureCapabilities
        {
            public bool EnableTaskCancellation { get; set; } = false;
            public bool EnableHideUnhideExchange { get; set; } = false;
            public bool EnableSelectElements { get; set; } = true;
            public bool ShowTitleBarBetaBadge { get; set; } = false;
        }
    }
    
    Show More

    Deprecated Properties

    The following properties on InteropBridgeOptions are deprecated:

    Deprecated PropertyReplacement
    InteropBridgeOptions.EnableTaskCancellation FeatureCapabilities.EnableTaskCancellation
    InteropBridgeOptions.EnableHideUnhideExchange FeatureCapabilities.EnableHideUnhideExchange

    New Capability

    EnableSelectElements: When enabled, adds a “Select Elements” option to the exchange context menu, allowing users to select/highlight exchange elements in the host application.

    Feature Capabilities migration

    Identify existing usage

    Search your codebase for usage of the deprecated properties:

    // Look for these patterns
    bridgeOptions.EnableTaskCancellation = ...
    bridgeOptions.EnableHideUnhideExchange = ...
    

    Update to FeatureCapabilities

    Replace individual property assignments with a FeatureCapabilities object:

    Before:

    var bridgeOptions = InteropBridgeOptions.FromClient(client);
    bridgeOptions.EnableTaskCancellation = true;
    bridgeOptions.EnableHideUnhideExchange = true;
    bridgeOptions.Exchange = customReadWriteModel;
    bridgeOptions.Invoker = mainThreadInvoker;
    
    var bridge = InteropBridgeFactory.Create(bridgeOptions);
    

    After:

    var bridgeOptions = InteropBridgeOptions.FromClient(client);
    
    // Configure all feature flags in one place
    bridgeOptions.FeatureCapabilities = new FeatureCapabilities
    {
        EnableTaskCancellation = true,
        EnableHideUnhideExchange = true,
        EnableSelectElements = true  // Default; set false to disable
    };
    
    bridgeOptions.Exchange = customReadWriteModel;
    bridgeOptions.Invoker = mainThreadInvoker;
    
    var bridge = InteropBridgeFactory.Create(bridgeOptions);
    
    Show More

    Consider disabling Select Elements

    EnableSelectElements is enabled by default. Evaluate whether to disable it:

    Keep enabled (default) if:

    • Your connector tracks element associations between exchanges and host elements
    • Your host application supports programmatic element selection
    • You implement IHostDataProvider.SelectElementsAsync()
    • Users would benefit from visually identifying exchange elements

    Disable if:

    • Your connector doesn’t track element associations
    • Your application doesn’t support selection
    • Selection doesn’t make sense for your use case

    Configuration Scenarios

    Scenario 2: Minimal Connector (No Select Elements)

    bridgeOptions.FeatureCapabilities = new FeatureCapabilities
    {
        EnableSelectElements = false  // Disable the default
    };
    

    Implementing Select Elements

    If you enable EnableSelectElements, implement the selection callback in your IHostDataProvider:

    public class MyHostDataProvider : BaseHostDataProvider
    {
        private readonly IHostApplication _hostApp;
    
        public MyHostDataProvider(IHostApplication hostApp)
        {
            _hostApp = hostApp;
        }
    
        public override Task SelectElementsAsync(
            IEnumerable<string> elementIds,
            CancellationToken cancellationToken = default)
        {
            // Select/highlight elements in your host application
            foreach (var elementId in elementIds)
            {
                if (cancellationToken.IsCancellationRequested)
                    break;
    
                _hostApp.SelectElement(elementId);
            }
    
            return Task.CompletedTask;
        }
    }
    
    Show More

    New Features

    All new features in this section are non-breaking and opt-in. Your existing connector code continues to work without modification.

    Exchange Description and Revision Notes

    The Connector UI now exposes two description fields to end users:

    • Create Exchange modal — a Description field where users can document the purpose of a new exchange.
    • Update Exchange dialog — a Revision note field (max 500 characters) where users describe what changed before publishing an update. This replaces the previous generic confirmation dialog for the Update action.

    What this means for your connector: When a user enters a revision note and confirms the update, the text is passed to your UpdateExchangeAsync override as exchangeItem.Description. No code changes are required, but you can read this value to log change history, annotate operations, or send it to analytics. Both the Create modal description and the Update revision note use the same Description field. If the user leaves either field empty, exchangeItem.Description will be null or empty — add a null check if your code depends on it.

    public override Task UpdateExchangeAsync(ExchangeItem exchangeItem, CancellationToken cancellationToken = default)
    {
        var note = exchangeItem.Description ?? "(no revision note)";
        logger.Info($"Exchange '{exchangeItem.Name}' updated: {note}");
        return Task.CompletedTask;
    }
    

    Version chip tooltip: Hovering over the version badge in the exchange list now shows the revision note for that version. This is automatic — no developer action needed.

    For full details, see Working with Exchange Descriptions.


    ShowTitleBarBetaBadge

    A new optional flag on FeatureCapabilities that shows a Beta badge in the Connector UI title bar. Defaults to false — no badge is shown unless you explicitly enable it.

    bridgeOptions.FeatureCapabilities = new FeatureCapabilities
    {
        ShowTitleBarBetaBadge = true  // Set to false or omit before stable release
    };
    

    ContactSupportUrl

    A new property on InteropBridgeOptions that sets the link behind the Contact Support action in the Connector UI Info menu.

    Always set ContactSupportUrl. If omitted, the Contact Support action in the Info menu routes to a default address not monitored for third-party connector issues. Users’ support requests will not reach your team.

    bridgeOptions.ContactSupportUrl = "https://your-support-page.com";
    // or
    bridgeOptions.ContactSupportUrl = "mailto:support@example.com";
    

    IsBeta on Input Descriptors

    A new optional bool property (default: false) on all custom form input descriptor types. When true, a Beta badge renders next to the field’s title in the custom form.

    new TextFieldDescriptor("exportFormat")
    {
        Title = "Export Format",
        IsBeta = true
    }
    

    Use when a specific form field exposes an experimental option — not the entire connector. Use ShowTitleBarBetaBadge to mark the whole connector as beta.


    Fire-and-forget async tasks

    The SDK provides TaskExtensions.SafeFireAndForget for intentional fire-and-forget Task calls. It logs failures through your ILogger instead of leaving the task unobserved.

    Who should adopt: Connectors that start background work (for example, telemetry or cache writes) without awaiting the result.

    Who can skip: Connectors that always await async operations or use another observability pattern.

    using Autodesk.DataExchange.Core;
    
    // Avoid bare Task discards that swallow exceptions silently:
    SomeAsyncOperation().SafeFireAndForget(logger, operationName: "TelemetryFlush");
    

    USD Download Support

    SDK v7.6.0 adds DownloadExchangeAsUSD, which downloads an exchange as USD alongside the existing OBJ, STEP, and IFC formats. The release also adds DATA_FORMAT_USD to the download format enum and a USD option to the AdvanceLoad custom form, so users of the Connector UI can pick USD without any change on your side.

    Who should adopt: Connectors whose users work with USD downstream, and connectors that present their own format picker and want USD in the list.

    Who can skip: Connectors that do not expose downloads, or that offer a fixed format.

    This is purely additive. Existing download calls keep working unchanged.


    Delta Retrieval for RetrieveLatestExchangeAsync

    RetrieveLatestExchangeAsync now pulls the latest exchange changes through a delta retrieval pipeline rather than retrieving in full.

    What you need to do: Nothing at the call site — the signature is unchanged. Treat this as a testing item rather than a code change. Exercise your load-latest path against an exchange that has been updated several times, and confirm the resulting model matches what you expect.


    Source Identifier Uniqueness

    SDK v7.6.0 fixes exchange and spec handling that previously assumed SourceId values are unique. The SDK no longer relies on that assumption.

    Who should review: Connectors that emit the same SourceId for more than one element — for example, when a host application reuses identifiers across documents or families. Behavior that previously depended on the SDK collapsing or arbitrarily resolving duplicates changes as a result.

    Who can skip: Connectors that already guarantee unique SourceId values per exchange.

    Test a model that contains duplicate source identifiers and confirm the elements land as you expect.

    The same change deprecates IElementDataModel.GetElementById(string sourceId), because a source identifier can no longer be assumed to select a single element. When duplicates exist it now returns the first non-deleted match and logs a warning. Move to whichever replacement matches your intent:

    IntentUse
    Retrieve every element sharing a source identifier GetElementsBySourceId(string sourceId)
    Retrieve one specific element, unambiguously GetElementByUniqueId(string uniqueId) — see IElement.UniqueId

    Geometry Translation Path

    GeometryConfiguration.UseConversionApiForGeometryTranslation selects which implementation the SDK uses to translate geometry: the out-of-process ConversionAPI (a gRPC-backed service) when true, or the legacy in-process GUSDK Client APIs when false. It is a bool with a default of true, so most connectors are already on the ConversionAPI path without any code change.

    Heads-up — legacy GUSDK Client APIs will be deprecated: the SDK will deprecate the legacy in-process GUSDK Client API path in an upcoming release. No action is needed today if you have not overridden the default. If your connector explicitly sets UseConversionApiForGeometryTranslation = false, plan to remove that override before the legacy path is removed.

    The ConversionAPI path is also a prerequisite for newer geometry capabilities as they ship — correct STEP export for mirrored instance geometry depends on this path being active. Staying on the default keeps your connector ready for capabilities like this without further configuration changes.

    Who should adopt: Every connector, by taking no action — the default already selects the recommended path.

    Who should review: Connectors that explicitly set UseConversionApiForGeometryTranslation = false. Confirm why, and plan to remove the override before legacy GUSDK Client APIs are deprecated.

    var geometryConfig = new GeometryConfiguration
    {
        UseConversionApiForGeometryTranslation = true  // Default; use the ConversionAPI translation path.
    };
    

    For setup and full guidance, see Choosing the geometry translation path.


    Authentication Hardening

    SDK v7.6.0 strengthens token handling without changing the authentication API. Token acquisition now retries with backoff, tokens refresh proactively before they expire, and PKCE uses a per-request state and verifier.

    What you need to do: Nothing. These changes are internal. If your connector implemented its own retry loop around token acquisition to work around transient failures, you can now consider removing it, but leaving it in place is harmless.


    Debugging with SDK Symbols

    The SDK now publishes SourceLink metadata and .snupkg symbol packages, with portable PDBs and a git commit hash build stamp. Enable symbol loading and source server support in your debugger to step directly into SDK source while debugging your connector.

    What you need to do: Nothing. Enable this only when you want to debug into the SDK.


    Sync Performance Tuning

    GeometryConfiguration offers three optional tunables covering both phases of sync: geometry conversion, then upload. Each defaults to a value that preserves prior behavior or reflects internal testing, so most connectors do not need to set any of them.

    PropertyTypeDefaultNotes
    ConversionBatchSize int 10000 Geometry assets per conversion batch. 0 or negative falls back to the default. Now functional — see below.
    SyncUploadConcurrency int 20 Valid range 1–35. Out-of-range values are silently clamped (no exception).
    TuneThreadPool bool true Process-wide effect.

    ConversionBatchSize bounds how many geometry assets the SDK converts per batch during the conversion phase, before upload begins. A smaller batch trades a longer conversion phase (more, smaller service calls) for a lower peak memory footprint — useful for large models that run out of memory during conversion.

    Source-compatible behavior change: In SDK versions before 7.6.0, ConversionBatchSize was not applied — the conversion phase always used a fixed batch of 10,000 regardless of this setting. No code update is required; your connector compiles and runs unchanged. But if it explicitly sets ConversionBatchSize to a positive value other than 10000 — including 5000, the former property default — that value now takes effect for the first time and may change memory usage and sync duration. Test large-model sync after upgrading. See ConversionBatchSize Now Controls Geometry Conversion Batching in the changelog.

    SyncUploadConcurrency bounds how many sync upload batches the SDK sends to the exchange in parallel. Raising it toward 35 mainly helps small or fast models. It provides little benefit for large models, where conversion time dominates, and it is not a memory-control lever. Lower it for constrained or unreliable network environments to reduce the number of simultaneous in-flight requests.

    TuneThreadPool controls whether the SDK raises the process-wide .NET ThreadPool minimum-thread settings during client initialization. This avoids thread-pool starvation (for example, There were not enough free threads in the ThreadPool to complete the operation.) during heavy geometry conversion on large models. The SDK only raises the minimums; it never lowers them below what the host has already configured.

    Who should adopt: Connectors that sync large models and run out of memory during conversion or hit thread-pool starvation, or connectors on constrained networks that need to reduce in-flight uploads. Connectors that already set ConversionBatchSize to anything other than 10000 should re-test large-model sync regardless, since the setting is now honored.

    Who can skip: Most connectors. The defaults are tuned for general-purpose use.

    Set TuneThreadPool = false only when the host application manages the thread pool itself, or when the SDK shares its process with other components that should not be affected by a process-wide change.

    These three settings are independent — tune one at a time, based on the specific symptom you’re addressing, rather than changing all of them together:

    // Lower only after measuring excessive memory use during the conversion phase.
    var geometryConfig = new GeometryConfiguration { ConversionBatchSize = 2000 };
    
    // Raise only for a measured upload-throughput need or network constraint.
    var geometryConfig = new GeometryConfiguration { SyncUploadConcurrency = 30 };  // Clamped to 1-35.
    
    // Disable only when the host application manages the thread pool itself.
    var geometryConfig = new GeometryConfiguration { TuneThreadPool = false };
    

    For setup and full guidance, see Tuning geometry conversion batch size, Tuning sync upload concurrency, and Tuning the thread pool. For an at-a-glance summary of all three options, see the Quick reference table.

    How sync works in 7.6.0

    Sync now runs through a single streaming pipeline for all model sizes. There is no runtime fallback to the previous path. You do not need to change your SyncExchangeDataAsync calls, but you should understand these behavior differences when you test or troubleshoot large models:

    • On-demand batches — the SDK serializes sync payloads in batches (up to 990 items per upload batch) and uploads them with bounded parallelism (SyncUploadConcurrency).
    • Faster failure — a fault in one batch aborts the sync within roughly one batch instead of after the entire model is processed.
    • Mixed upload ordering — assets, relationships, and schemas upload concurrently in mixed batches rather than all assets first, then all relationships. Do not assume relationships always arrive after their referenced assets when you validate server-side state in tests.
    • Timeout retries — an HttpClient timeout (not a user cancel) is retried with exponential backoff. A request that reached the server but timed out on the response may be sent again, so your publish/sync flow must tolerate duplicate requests.

    If large-model sync fails with thread-pool errors, start with the defaults in Sync Performance Tuning and see Resolving thread pool starvation.


    Adopt Instance-Level Render Style

    SDK v7.4.0 added a read-only property, IElement.RenderStyle, that exposes the render style attached directly to an element instance — for example, a body or instance color applied in Inventor. It is unchanged in v7.6.0, so skip this section if you already adopted it.

    This change is non-breaking. Existing code that reads only IElementGeometry.RenderStyle continues to compile and run. However, connectors that render element colors or materials should adopt the new precedence rule to surface instance-level overrides that were previously dropped silently.

    Who should adopt: Connectors that render element colors or materials and currently read IElementGeometry.RenderStyle.

    Who can skip: Connectors that don’t render colors or materials.

    Why instance render style was added

    Some authoring applications attach color to the instance asset rather than the geometry. Until v7.4.0, the SDK had no public surface to read that override, so the loaded exchange rendered the geometry color — an element shown in red in ACC would appear in the geometry color in the connector. IElement.RenderStyle makes the override visible to the consumer.

    Apply the precedence rule

    Use instance over geometry — read the instance-level override first and fall back to the geometry-level style:

    Before:

    var geometries = await dataModel.GetElementGeometriesAsync(elements);
    
    foreach (var element in elements)
    {
        var geometry = geometries.TryGetValue(element, out var g) ? g.FirstOrDefault() : null;
        var style    = geometry?.RenderStyle;
        if (style != null)
        {
            ApplyColor(target, style.RGBA, style.Transparency);
        }
    }
    
    Show More

    After:

    var geometries = await dataModel.GetElementGeometriesAsync(elements);
    
    foreach (var element in elements)
    {
        var geometry = geometries.TryGetValue(element, out var g) ? g.FirstOrDefault() : null;
        var style    = element.RenderStyle ?? geometry?.RenderStyle;
        if (style != null)
        {
            ApplyColor(target, style.RGBA, style.Transparency);
        }
    }
    
    Show More

    Note: Most elements will not have an instance-level override. IElement.RenderStyle returns null when no override is set — always null-check.

    Details: Resolve an element’s render style


    Pre-warm Services at SDK Initialization

    SDK v7.4.0 added the SDKOptions.WarmupServices flag, which controls whether the geometry translation service is pre-warmed when the SDK initializes, instead of starting on the first call that needs it. It is unchanged in v7.6.0, so skip this section if you already adopted it.

    This change is non-breaking. The default on SDKOptions is false, so existing connectors that construct SDKOptions directly continue to start translation on demand.

    Who should adopt: Connectors whose users would notice latency on the first geometry translation call, and that can afford a slightly longer SDK initialization. Typically: UI-driven or console flows where the user spends time selecting folders or naming an exchange before triggering the first translation — that wall-clock time absorbs the warm-up cost.

    Who can skip: Test setups or scripted flows that initialize the client and trigger a translation back-to-back, or any connector where first-call latency is not user-visible. Pre-warming offers no benefit in those cases and only adds to startup time.

    Note: The property defaults to false. InitializeSDKOptions sets it to true for production connectors, so if you initialize through that path you are already pre-warming — set WarmupServices = false explicitly if you do not want the startup cost. Leave it false in unit and integration tests so services start lazily on demand.

    Configure the flag

    var options = new SDKOptions
    {
        ConnectorName = "MyConnector",
        // ... other options
        WarmupServices = true  // Pre-warm geometry translation at SDK init
    };
    
    IClient client = new Client(options);
    
    Show More

    If you use SDKOptionsDefaultSetup, WarmupServices is already true by default — set it to false only if you want to opt out:

    var setup = new SDKOptionsDefaultSetup
    {
        ClientId = AuthClientID,
        ClientSecret = AuthClientSecret,
        CallBack = AuthCallBack,
        ConnectorName = "Revit-Connector",
        // ... other options
        WarmupServices = false  // Opt out of pre-warm
    };
    
    Show More

    Classification, Types, and Design Instancing

    SDK v7.6.0 adds three related, non-breaking additions that decouple element creation from how you tag and reuse elements: Classify with ClassificationSystem, DefineType with SetType, and GetOrCreateDesignRef with InstantiateDesignBySourceId and GetDesignRefs.

    This change is non-breaking. Existing code that uses ElementProperties and the legacy Category/Family/Type fields continues to compile and run. ElementProperties is now [Obsolete] and will be removed in a future release, so you should migrate before then.

    Who should adopt: Connectors that currently build category/family/type tags from free-text strings, that manage type parameters manually, or that reuse geometry (blocks, families, sub-assemblies) and currently duplicate it per instance.

    Who can skip: Connectors with no classification or type needs, and connectors that never reuse geometry across multiple elements.

    Why the classification model changed

    The legacy element-creation constructor took Category, Family, and Type as free-text strings. A typo — Classify(element, "Categori", "Walls") — compiled and ran without error, but silently fragmented what should have been a single classification into two. There was also no way to reuse a design (a block, family, or sub-assembly) across multiple elements without duplicating its geometry and hierarchy for every occurrence.

    ClassificationSystem replaces the free-text system name with a fixed, typed set of well-known values plus a Custom escape hatch that enforces a naming convention. DefineType/SetType replace ad hoc type strings with a resolvable handle. GetOrCreateDesignRef/InstantiateDesignBySourceId give design reuse first-class, idempotent APIs.

    ElementProperties and the classification-agnostic model

    Before:

    var wall = elementDataModel.AddElement(
        new ElementProperties("wall-001", "Exterior Wall", "Walls", "Basic Wall", "8in-Concrete"));
    

    After:

    var wall = elementDataModel.AddElement("wall-001", "Exterior Wall");
    
    var category = elementDataModel.Classify(wall, ClassificationSystem.Category, "Walls");
    var family = elementDataModel.Classify(wall, ClassificationSystem.Family, "Basic Wall", parent: category);
    
    var wallType = elementDataModel.DefineType(system: "Type", name: "8in-Concrete", parent: family);
    elementDataModel.SetType(wall, wallType);
    

    Element creation (AddElement) no longer requires a category, family, or type — the SDK does not enforce any classification hierarchy. Attach as much or as little classification as your connector needs, using Classify for tags and DefineType/SetType when elements share a type definition and its parameters.

    Full guidance: Working with classification · Working with types · Working with design instancing


    Breaking Changes

    Exception Namespace Reorganization

    Breaking change: Code referencing the CustomExceptions sub-namespace will not compile. A single find-replace resolves all occurrences.

    All 14 custom exception types and the ValidationContext enum have moved from Autodesk.DataExchange.Exceptions.CustomExceptions up one level to Autodesk.DataExchange.Exceptions. Class shapes, constructors, and base types are unchanged.

    Migration:

    // Before
    using Autodesk.DataExchange.Exceptions.CustomExceptions;
    
    try { await client.GetExchangeAsync(id); }
    catch (DataSyncException ex) { logger.Error(ex, "exchange sync failed"); }
    
    throw new Exceptions.CustomExceptions.GeneralException(ex.Message, ex);
    
    // After
    using Autodesk.DataExchange.Exceptions;
    
    try { await client.GetExchangeAsync(id); }
    catch (DataSyncException ex) { logger.Error(ex, "exchange sync failed"); }
    
    throw new Exceptions.GeneralException(ex.Message, ex);
    

    A repo-wide regex find-replace of Autodesk\.DataExchange\.Exceptions\.CustomExceptions\. → Autodesk.DataExchange.Exceptions. is safe for connectors already on the current 7.4.x SDK.

    The same applies to ValidationContext — it is still an enum, just relocated. Exception filters that reference it by fully-qualified name require the same update:

    // Before
    catch (Autodesk.DataExchange.Exceptions.CustomExceptions.ValidationFailedException ex)
        when (ex.Context == Autodesk.DataExchange.Exceptions.CustomExceptions.ValidationContext.Create)
    {
        // ...
    }
    
    // After
    catch (Autodesk.DataExchange.Exceptions.ValidationFailedException ex)
        when (ex.Context == Autodesk.DataExchange.Exceptions.ValidationContext.Create)
    {
        // ...
    }
    

    The find-replace covers this — both the exception type and the enum reference follow the same namespace pattern.


    New Members on Existing Interfaces

    Breaking change: Custom implementations of the interfaces below will not compile until the new members are added. Connectors using the SDK’s built-in implementations are unaffected.

    Added in 7.5.0:

    InterfaceNew memberKind
    Autodesk.DataExchange.Interface.IElement RenderStyle RenderStyle { get; } Property
    Autodesk.DataExchange.Interface.IElementDataModel string RootAssetName { get; set; } Property
    Autodesk.DataExchange.UI.Core.Interfaces.IInteropBridge void SetApplicationMode(ApplicationMode applicationMode) Method
    Autodesk.DataExchange.UI.CustomForm.Interfaces.IInputDescriptor bool IsBeta { get; set; } Property
    Autodesk.DataExchange.Core.Interface.IExchangeSearchFilter bool ForceRefresh { get; set; } Property
    Autodesk.DataExchange.Core.Interface.ILogger void Error(string message, Exception exception, string caller = null) Method

    Added in 7.6.0, alongside the classification and type model:

    InterfaceNew memberKind
    Autodesk.DataExchange.Interface.IElement IReadOnlyList<IClassification> Classifications { get; } Property
    Autodesk.DataExchange.Interface.IElement IElementType Type { get; } Property
    Autodesk.DataExchange.Interface.IElement IEnumerable<IParameter> TypeParameters { get; } Property
    Autodesk.DataExchange.Interface.IElementDataModel IClassification Classify(IElement element, ClassificationSystem system, string value, IClassification parent = null, string sourceId = null) Method
    Autodesk.DataExchange.Interface.IElementDataModel IElementType DefineType(string system, string name, IClassification parent = null, string sourceId = null) Method
    Autodesk.DataExchange.Interface.IElementDataModel void SetType(IElement element, IElementType type) Method
    Autodesk.DataExchange.Interface.IElementDataModel Task<IParameter> AddTypeParameterAsync(IElementType type, IParameter parameterDefinition) Method

    SetType has a second, by-name overload. See Type Attribution Fix for the difference between the two and when to prefer the handle-based one.

    Why ILogger gained this member: the SDK’s previous Error overloads forced a choice between a diagnostic message (Error(string)) and the exception itself (Error(Exception)). Internal error-reporting code that needed both had no single call to make, which contributed to inconsistent exception capture in session telemetry. The new overload lets any caller — the SDK internally, or your connector — log a message and an exception together in one call. See Logging errors with context for usage guidance.

    Migration — add the missing members to your implementations:

    // IElement
    public class MyElement : IElement
    {
        public RenderStyle RenderStyle => null; // Return null if no instance-level override
    
        // Added in 7.6.0. Return empty and null when your element carries no
        // classification or type, rather than throwing.
        public IReadOnlyList<IClassification> Classifications => Array.Empty<IClassification>();
        public IElementType Type => null;
        public IEnumerable<IParameter> TypeParameters => Enumerable.Empty<IParameter>();
    }
    
    // IElementDataModel
    public class MyElementDataModel : IElementDataModel
    {
        public string RootAssetName { get; set; } = "TopLevelAssembly";
    
        // Added in 7.6.0. Implement these if your test double or custom model
        // participates in classification and type workflows.
        public IClassification Classify(IElement element, ClassificationSystem system, string value,
            IClassification parent = null, string sourceId = null) => throw new NotImplementedException();
    
        public IElementType DefineType(string system, string name,
            IClassification parent = null, string sourceId = null) => throw new NotImplementedException();
    
        public void SetType(IElement element, IElementType type) => throw new NotImplementedException();
    
        public Task<IParameter> AddTypeParameterAsync(IElementType type, IParameter parameterDefinition)
            => throw new NotImplementedException();
    }
    
    // IInteropBridge
    public class MyInteropBridge : IInteropBridge
    {
        public void SetApplicationMode(ApplicationMode applicationMode) { }
    }
    
    // IInputDescriptor
    public class MyInputDescriptor : IInputDescriptor
    {
        public bool IsBeta { get; set; } = false;
    }
    
    // IExchangeSearchFilter
    public class MyExchangeSearchFilter : IExchangeSearchFilter
    {
        public bool ForceRefresh { get; set; }
        // ... existing filter properties
    }
    
    // ILogger
    public class MyLogger : ILogger
    {
        public void Error(string message, Exception exception, string caller = null)
        {
            // Delegate to your existing single-argument overloads, or log message + exception together.
            this.Error($"{message}: {exception}", caller);
        }
        // ... existing logger members
    }
    
    Show More

    Element, ElementDataModel, and ElementGeometry Are Now Returned as Interfaces

    Breaking change: Code that declares Element, ElementDataModel, or ElementGeometry as an explicit variable, field, or parameter type — for values that come back from the SDK — will not compile. The concrete classes still exist and still do the work; roughly 20 SDK members that hand data back to your connector now declare their return or parameter type as the interface (IElement, IElementDataModel, or IElementGeometry) instead.

    Why this change: Depending on the concrete classes coupled every connector to the SDK’s internal implementation. Depending on the interfaces instead means the SDK team can evolve Element, ElementDataModel, and ElementGeometry internally without breaking your build, and it means your own connector code can substitute a mock or fake in unit tests — something you can’t do with a sealed-in-spirit concrete class. This is the same reason the SDK already asked custom implementers to add members to IElement and IElementDataModel in New Members on Existing Interfaces above; this change extends the interface-first approach to the values the SDK hands back, not just the contracts you implement.

    Who must migrate: Any connector with an explicit Element, ElementDataModel, or ElementGeometry type in code that consumes or exposes a value from one of the members in the table below. A local variable declared with var upgrades silently, since var binds to whatever the compiler infers — but var only protects locals. Fields, properties, method parameters, return types, generic collections (List<Element>), arrays, nullable declarations (Element?), and casts back to the concrete type all still name the concrete class explicitly, regardless of how consistently your codebase uses var elsewhere. Run the discovery search below before assuming this doesn’t apply to you.

    Affected members:

    MemberOld signature (concrete)New signature (interface)
    IElementDataModel.Elements IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.TopLevelElements IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.DeletedElements IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.GetElementById(string) Element IElement
    IElementDataModel.GetAllElements(...) IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.GetCreatedElements(...) IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.GetDeletedElements(...) IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.GetModifiedElements(...) IEnumerable<Element> IEnumerable<IElement>
    IElement.GetChildElements() IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.GetElementGeometriesAsync(...) Task<Dictionary<Element, IEnumerable<ElementGeometry>>> Task<Dictionary<IElement, IEnumerable<IElementGeometry>>>
    IElementDataModel.GetGeometriesAsync(...) Task<IEnumerable<ElementGeometry>> Task<IEnumerable<IElementGeometry>>
    IElementDataModel.GetElementGeometryCounts(...) Dictionary<GeometryFilters, long> (param IEnumerable<Element>) param IEnumerable<IElement>
    IElementDataModel.GetDesignInstances(IDesign) IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.GetDesignInstancesBySourceId(string) IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.GetDesignInstancesByName(string) IEnumerable<Element> IEnumerable<IElement>
    IElementDataModel.CreateDesignRef(...) param Element param IElement
    IElementDataModel.InstantiateDesign(...) param Element param IElement
    IClient.GetElementDataModelAsync(...) (3 overloads) Task<IResponse<ElementDataModel>> Task<IResponse<IElementDataModel>>
    IClient.SyncExchangeDataAsync(...) param ElementDataModel param IElementDataModel
    IClient.RetrieveLatestExchangeDataAsync(...) param ElementDataModel param IElementDataModel

    Not affected by this migration: ElementDataModel.Create(...), ElementDataModel.CreateFileGeometry(...), CreateMeshGeometry(...), and CreatePrimitiveGeometry(...) still return the concrete class in this release, because they construct something new rather than retrieve something that already exists — leave calls to these factory methods as-is. A small number of geometry-setter overloads (AddElement(ElementProperties, ...), the concrete-typed SetElementGeometry overload) kept their old concrete-typed signature as [Obsolete] alongside a new interface-typed overload, so references to those specific overloads still compile — with a CS0618 warning — even without an immediate change.

    Interface-typed overloads added alongside this migration: AddElement, GetOrCreateDesignRef, and InstantiateDesignBySourceId each gained an IElement-typed overload. Once your own variables hold interfaces rather than concrete types, these overloads are what your calls bind to, so no cast back to Element is needed at the call site. If you find yourself adding such a cast to make a call compile, reach for the interface-typed overload instead.

    Migration:

    // Before
    Element wall = model.GetElementById("wall-001");
    List<Element> allWalls = model.Elements.Where(e => e.Category == "Walls").ToList();
    
    Task<Dictionary<Element, IEnumerable<ElementGeometry>>> geometries =
        model.GetElementGeometriesAsync(allWalls);
    
    ElementDataModel loadedModel = (await client.GetElementDataModelAsync(exchangeIdentifier)).Result;
    
    Show More
    // After
    IElement wall = model.GetElementById("wall-001");
    List<IElement> allWalls = model.Elements.Where(e => e.Category == "Walls").ToList();
    
    Task<Dictionary<IElement, IEnumerable<IElementGeometry>>> geometries =
        model.GetElementGeometriesAsync(allWalls);
    
    IElementDataModel loadedModel = (await client.GetElementDataModelAsync(exchangeIdentifier)).Result;
    
    Show More

    Finding affected references: Don’t rely on compiler errors alone to find every case — the compiler only catches incompatible assignments and arguments in the configurations you actually build, and it can’t see concrete types left in unused methods, public signatures, generic declarations, or code excluded by conditional compilation. Search broadly for every reference to the three concrete type names, then review the results by hand:

    grep -rnE '\b(Element|ElementDataModel|ElementGeometry)\b' --include="*.cs" .
    

    This search is deliberately broad — it will also surface constructors, factory calls, comments, and unrelated uses that don’t need to change. Review each result and change it only if it:

    • Receives a value from one of the members in the table above.
    • Passes such a value through your own fields, properties, parameters, or return types.
    • Stores such a value in an array or generic collection (for example, List<Element> becomes List<IElement>).
    • Casts an SDK interface value back to the concrete implementation.

    Leave factory and constructor calls unchanged unless “Not affected by this migration” above, or another migration item, explicitly documents a change to that call.


    Strongly-Typed Validation Hook Parameters

    Breaking change: Four exchange validation hooks changed signature. A connector that overrides any of them will not compile until the override signature is updated. Connectors that do not override these hooks are unaffected, and the default behavior is unchanged.

    The exchange models expose validation hooks that run before a create, update, or load operation and let your connector allow or block it. Previously these hooks received no parameters or an untyped Dictionary<string, object>, so an override could not reliably tell which exchange, project, folder, or hub was being validated. They now receive strongly-typed domain objects that the SDK already holds at the point of validation, giving you compile-time safety and autocomplete instead of runtime string-key lookups.

    HookBeforeAfter
    ValidateGetLatestExchangeAsync () (ExchangeItem exchangeItem)
    ValidateGetLatestExchangeDetailsAsync () (ExchangeItem exchangeItem)
    ValidateCanCreateExchangeAsync (Dictionary<string, object>) (ExchangeInput exchangeInput)
    ValidateCanUpdateExchangeAsync (Dictionary<string, object>) (ExchangeItem exchangeItem)

    No return types changed. The two GetLatest hooks still return Task<bool>, and the create and update hooks still return Task<IEnumerable<string>>.

    Migration — update each override to read from the typed parameter:

    // Before — untyped dictionary, runtime string-key lookup
    public override Task<IEnumerable<string>> ValidateCanUpdateExchangeAsync(
        Dictionary<string, object> parameters)
    {
        var exchangeId = parameters.TryGetValue("ExchangeId", out var v) ? v as string : null;
        // ...
    }
    
    // After — typed ExchangeItem, compile-time safety
    public override Task<IEnumerable<string>> ValidateCanUpdateExchangeAsync(ExchangeItem exchangeItem)
    {
        var exchangeId = exchangeItem.ExchangeID;
        // ...
    }
    
    Show More

    The dictionary keys the old create and update hooks relied on (ExchangeId, ProjectUrn, FolderUrn, FileUrn, HubId, ContainerId) have equivalent properties on ExchangeItem and ExchangeInput. Read the typed property instead of a string key.

    For the full set of hooks, their return-value contracts, and a complete worked example, see Validating Exchange Operations.

    Geometry namespace migration (GUSDK 0.9.3)

    Breaking change: Public members that take or return geometry types now reference Autodesk.GeometryUtilities.PrimitivesAPI instead of Autodesk.GeometryPrimitives.*. Consumer code that constructs or reads Geometry, Vector3d, render styles, or related types must update its using directives and rebuild.

    This namespace migration landed in 7.5.0, when the geometry engine moved to GUSDK 0.9.3. The SDK pins a single geometry-utilities package set and no longer switches between 0.7.x and newer package versions at runtime. If you are upgrading from 7.5.x, the namespace work is already done — see Geometry engine upgrade (GUSDK 0.9.4) for what 7.6.0 adds on top.

    Who must migrate: Any connector that creates in-memory geometry, reads geometry from exchanges, or sets viewable orientation using Vector3d and related types.

    Who can skip: Connectors that only call high-level sync/load APIs and never reference geometry types directly in their own code.

    Commonly affected APIs:

    • ElementDataModel.CreatePrimitiveGeometry(...) — the Geometry parameter is now Autodesk.GeometryUtilities.PrimitivesAPI.Geometry.
    • ViewableWorldCoordinates.UP / Front / North — now Autodesk.GeometryUtilities.PrimitivesAPI.Vector3d.
    • PrimitiveGeometry, IPrimitiveGeometry, GeometryWrapper, Design, CoordinateSystemVector, and related types now reference Autodesk.GeometryUtilities.PrimitivesAPI[.IO].

    Migration:

    // Before
    using Autodesk.GeometryPrimitives.Data;
    using Autodesk.GeometryPrimitives.Data.Design;
    using Autodesk.GeometryPrimitives.IO.STEP;
    
    // After
    using Autodesk.GeometryUtilities.PrimitivesAPI;
    using Autodesk.GeometryUtilities.PrimitivesAPI.Design;
    using Autodesk.GeometryUtilities.PrimitivesAPI.IO.STEP;
    
    Show More

    Run a repo-wide search for Autodesk.GeometryPrimitives and replace each namespace with its Autodesk.GeometryUtilities.PrimitivesAPI equivalent. Update tutorial and sample code in your connector repository the same way.

    Render and style behavior (GUSDK 0.9.x): StyleInfo.Transparency is now nullable — a null value renders fully opaque. If your connector maps transparency from host applications, treat null as opaque rather than assuming a numeric default. Per-face style mapping (SubEntStyles) changed shape for STEP/IFC imports; validate color output on representative models after upgrading.

    Note: ViewableWorldCoordinates and GetViewableWorldCoordinates / SetViewableWorldCoordinates are retained. Only the Vector3d type they use changed namespaces. See also Local Viewable Generation Removed.

    Geometry engine upgrade (GUSDK 0.9.4)

    Breaking change: SDK v7.6.0 moves the geometry engine from GUSDK 0.9.3 to 0.9.4. The out-of-process GeometryUtilitiesService and its native payload change with it.

    There is no source change to make. No namespace moves and no public signatures change — that work happened at 0.9.3, covered in Geometry namespace migration (GUSDK 0.9.3). What changes is the set of native binaries your connector ships.

    Who must act: Every connector. A connector that upgrades the SDK package but redeploys stale native binaries runs a mismatched engine.

    What to do:

    1. Rebuild your connector against the 7.6.0 SDK package.
    2. Repack or re-run your deployment step so the refreshed GUSDK native binaries and the GeometryUtilitiesService payload are the ones you ship. Pay particular attention if you copy SDK files manually rather than relying on NuGet package restore.
    3. Run your geometry regression set and compare translation output against your 7.5.x baseline.

    Mirrored STEP geometry is worth a second look here. SDK v7.6.0 fixes handling of BRep elements from mirrored STEP geometry, so models that previously exported incorrectly should now be correct. If your regression baseline captured the old behavior, expect those cases to change and update the baseline.

    Local Viewable Generation Removed

    Viewable (visual representation) generation now happens automatically (server-side) as part of the publish/sync process. The local viewable-generation pipeline and its public API surface have been removed.

    Impact: Code that starts viewable generation, subscribes to its events, or references its status/exception/details types will not compile.

    Removed members:

    RemovedLocation
    GenerateViewableAsync IClient / Client
    ViewableGenerationStarted, ViewableGenerationCompleted (events) IClient / Client, IExchangeWriter, BaseReadWriteExchangeModel, BaseWriteOnlyExchangeModel
    ViewableGenerationStatus (enum) Autodesk.DataExchange.Core.Enums
    ViewableGenerationException Autodesk.DataExchange.Exceptions
    ViewableDetails (model) Autodesk.DataExchange.Core.Models
    ViewDataInfoData (type) Autodesk.DataExchange.GeometryUtilitiesService.Client
    GenerateSVFViewableAsync(...) IGeometryUtilitiesServiceClient

    Note: GenerateViewableAsync was already marked [Obsolete] in a previous release, so its removal is expected. The events, ViewableGenerationStatus, ViewableGenerationException, and ViewableDetails removals are new breaking changes with no prior deprecation — check for these explicitly.

    Migration — viewable generation is now automatic after sync:

    // Before
    client.ViewableGenerationCompleted += OnViewableGenerated;
    await client.SyncExchangeDataAsync(exchangeIdentifier, dataModel);
    await client.GenerateViewableAsync(exchangeId, collectionId);
    
    // After
    // Viewable generation is automatic after sync — no explicit call or event needed.
    await client.SyncExchangeDataAsync(exchangeIdentifier, dataModel);
    
    Show More

    Setting viewable orientation (retained): The ViewableWorldCoordinates type and the SetViewableWorldCoordinates / GetViewableWorldCoordinates methods remain. Use them to set the orientation (the up, front, and north vectors) of the generated viewable before the publish/sync call. Update the Vector3d namespace as described in Geometry namespace migration.

    Region required for schema (ASR) calls

    Breaking change: ISchemaSDK.GetSchemaAsync / GetSchemasAsync gained a required region parameter for the Autodesk Schema Registry (ASR), sent as a region HTTP header. On a cache miss with a null or empty region, the call throws ArgumentException("Region is required for ASR calls."). Previously a missing region silently defaulted to US, which could serve wrong-region data.

    Who must migrate: Connectors, tools, or tests that call the schema SDK directly — not typical connector flows that rely solely on SyncExchangeDataAsync and built-in schema resolution.

    Who can skip: Connectors that never call ISchemaSDK in their own code.

    What to do: Pass the data residency region for the hub or project context (for example, the region you already use for ACC/Forma API calls). Cache hits do not require a region; the exception applies on a cold cache when region is null or empty.

    If your connector operates outside the US and previously relied on the silent US default, you may see this exception after upgrade on the first schema fetch. Plumb region through from your hosting provider or project metadata before calling the schema SDK.

    Migration:

    // Obtain the data-residency region from hub or project metadata —
    // use the same region string you already pass to ACC/Forma hosting calls.
    string region = GetProjectRegion();
    
    // Before — region omitted
    await schemaSdk.GetSchemaAsync(schemaName, schemaVersion);
    await schemaSdk.GetSchemasAsync(schemaRequests);
    
    // After — pass region on every call (required on cache miss)
    await schemaSdk.GetSchemaAsync(schemaName, schemaVersion, region);
    await schemaSdk.GetSchemasAsync(schemaRequests, region);
    
    Show More

    Cache hits do not require a region. The exception applies only on a cold cache when region is null or empty.

    Type Attribution Fix (DefineType and SetType)

    Breaking change (behavior, not compilation): Resolving a type by name is now scoped by ancestry and throws InvalidOperationException when more than one match is found in scope, instead of silently using the first match anywhere in the model. Code that previously ran without error may now throw.

    Attaching a type parameter previously resolved “the type named X” by searching the entire model and using the first match — regardless of where it lived in the model hierarchy. If two branches of a model each defined a type with the same name, a parameter intended for one type could silently attach to the other. This was a correctness bug: nothing failed, but data could end up on the wrong type.

    Who must review: Connectors that define multiple types with the same name in different branches of a model (for example, “Standard Bolt” under two unrelated sub-assemblies).

    Who can skip: Connectors that use unique type names, or that always resolve types through a handle returned by DefineType rather than by name.

    What changed:

    • DefineType now returns a handle (IElementType) that resolves directly to a specific type. Pass this handle to AddTypeParameterAsync and to the handle-based overload of SetType — neither performs a name lookup.
    • The by-name overload of SetType is scoped by ancestry: pass an under classification to restrict resolution to types nested under it. Unscoped, it searches the whole model.
    • If a by-name resolution finds more than one match in scope, it now throws InvalidOperationException instead of picking the first result. If it finds no match, it throws NotFoundException.

    What to do: Prefer the handle returned by DefineType wherever you already have it — this makes the ambiguity case structurally impossible. Where you only have a type’s name, scope the lookup with under if the same name could exist in more than one branch of your model.

    Details: Working with types — Why this API exists

    ADP Analytics Moved to a Standalone Package

    Breaking change: IAdpAnalytics and its data transfer objects moved out of the SDK into their own package, and the SDK no longer registers IAdpAnalytics through its own ConfigureServices. Code that references these types stops compiling, and dependency injection wiring that relied on the SDK to register the implementation stops receiving analytics.

    IAdpAnalytics, AdpEvent, and ExchangeProcessStatus now live in Autodesk.DataExchange.ADPAnalytics.Abstractions. That package ships at version 1.0.0 and versions independently of the SDK, so analytics contracts can evolve without forcing an SDK upgrade.

    Who must migrate: Connectors that implement IAdpAnalytics, construct AdpEvent, read ExchangeProcessStatus, or relied on the SDK registering an ADP analytics implementation for them.

    Who can skip: Connectors that never reference ADP analytics types.

    This one deserves care, because only part of it is a compile error. Missing the package reference breaks the build, which is hard to overlook. Dropping the registration does not — your connector compiles and runs, and analytics silently stop arriving. Verify the events actually flow after upgrading rather than assuming a clean build means success.

    Migration — step 1, reference the package:

    <PackageReference Include="Autodesk.DataExchange.ADPAnalytics.Abstractions" Version="1.0.0" />
    

    Migration — step 2, register your implementation. The SDK no longer does this for you. The preferred route is RegisterAdpAnalytics on SDKOptions, which chains with any ConfigureServices delegate you have already set:

    var options = new SDKOptions
    {
        ConnectorName = "MyConnector",
        // ... other options
    }
    .RegisterAdpAnalytics(new MyAdpAnalytics());
    
    IClient client = new Client(options);
    
    Show More

    If you are already composing services through ConfigureServices and want the registration inline with the rest of your wiring, use the AddAdpAnalytics extension from the Autodesk.DataExchange.ADPAnalytics namespace instead:

    using Autodesk.DataExchange.ADPAnalytics;
    
    var options = new SDKOptions
    {
        ConnectorName = "MyConnector",
        ConfigureServices = services =>
        {
            services.AddAdpAnalytics(new MyAdpAnalytics());
            // ... your other service registrations
        }
    };
    
    Show More

    Use one or the other, not both. AddAdpAnalytics deliberately lives in the SDK assembly rather than in the Abstractions package, so that it binds to the ILRepack-internalized IServiceCollection types that ConfigureServices exposes.

    Migration — step 3, verify. Run a scenario that emits analytics and confirm the events reach your implementation.

    Chinese UI Locale Removed

    Breaking change: SDK v7.6.0 deletes the Chinese (zh-CN) localization resource file from the Connector UI and simplifies the locale wiring. The SDK no longer bundles this locale.

    Who must act: Connectors that ship the Connector UI in zh-CN. Those users fall back to the default locale after you upgrade.

    Who can skip: Connectors that do not offer a Chinese UI.

    What to do: Supply the locale downstream in your own application if you need to keep offering it. Treat this as a release-note item for your users as well, since it is a visible change for anyone currently running the connector in Chinese.


    GeometryUtilitiesService Client

    A new gRPC-backed client (IGeometryUtilitiesServiceClient / GeometryUtilitiesServiceClient) replaces in-process geometry calls with out-of-process service calls. No action required for existing connectors — the SDK handles the transition internally.

    Note for test harnesses: The service now runs out-of-process. Allow the SDK to spawn helper processes in integration test environments.


    IExchangeContextForm

    IExchangeContextForm is a new opt-in interface under Autodesk.DataExchange.UI.CustomForm.Interfaces that extends ICustomForm. Implement it when your Load form needs exchange metadata — such as the connector name or source application name — before building input fields.

    Forms that do not implement IExchangeContextForm are unaffected. This is a purely additive change.

    Who should adopt: Connectors whose Load forms need to vary their input fields based on which exchange is being loaded — for example, showing format-specific options only for exchanges from a particular source application.

    Who can skip: Connectors with static Load forms that always show the same input fields regardless of exchange context.

    How it works

    The bridge calls ApplyExchangeContext once per session, after CreateAsync and before GetInputFieldsAsync. The method receives a read-only dictionary of exchange attributes keyed by name.

    Available attribute keys include:

    KeyValue
    ConnectorName The name of the connector that created the exchange
    SourceApplicationName The source application (for example, Revit or Inventor)

    Adopt IExchangeContextForm

    1. Implement IExchangeContextForm on your Load form class instead of (or in addition to) ICustomForm.
    2. Add an ApplyExchangeContext method that reads the attributes your form needs and stores them as fields.
    3. Use the stored values in GetInputFieldsAsync — they are set before that method runs.
    public class MyLoadForm : IExchangeContextForm
    {
        private string _connectorName;
        private string _sourceApp;
    
        // Called once per session, after CreateAsync and before GetInputFieldsAsync.
        public void ApplyExchangeContext(IReadOnlyDictionary<string, string> exchangeAttributes)
        {
            exchangeAttributes.TryGetValue("ConnectorName", out _connectorName);
            exchangeAttributes.TryGetValue("SourceApplicationName", out _sourceApp);
        }
    
        public async Task<IEnumerable<IInputField>> GetInputFieldsAsync()
        {
            // _connectorName and _sourceApp are available here.
            var fields = new List<IInputField>();
            // Build fields using the exchange context as needed.
            return fields;
        }
    }
    
    Show More

    Note: If a key is absent from exchangeAttributes, TryGetValue sets the output variable to null. Always null-check before using the value.


    Runtime Application Mode Control

    The IInteropBridge interface now exposes a SetApplicationMode method that lets you switch the Connector UI between read-only, write-only, and read-write modes at runtime. This is useful when the host application needs to restrict capabilities based on document context — for example, showing read-only UI for template documents and full read-write UI for project documents.

    Requirements: The connector must be initialized with a BaseReadWriteExchangeModel. Calling SetApplicationMode on a read-only or write-only connector throws InvalidOperationException.

    // Switch to read-only when user opens a template document
    bridge.SetApplicationMode(ApplicationMode.ReadOnly);
    
    // Restore full mode when user opens a project document
    bridge.SetApplicationMode(ApplicationMode.ReadWrite);
    

    See Creating New Base Model — Runtime Application Mode Control for details and error handling guidance.


    Refresh Trigger on the Exchange List

    The ExchangeSearchFilter passed to your GetExchangesAsync override now carries a ForceRefresh flag. It lets your connector distinguish a user-initiated Refresh (which should bypass any locally cached exchange list and re-read from the host) from a routine programmatic refresh (which may serve cached results for a faster response).

    This change is non-breaking for callers — ForceRefresh defaults to false, so existing connectors that ignore the flag behave exactly as before. It is breaking if you implement IExchangeSearchFilter yourself; add the property as described in New Members on Existing Interfaces.

    Who should adopt: Connectors that cache the exchange list (via GetCachedExchanges) and want the Refresh button to return the latest data instead of stale cached entries.

    Who can skip: Connectors that always re-read exchanges from the host and never serve cached results.

    How the flag is set

    The Connector UI calls GetExchangesAsync whenever the exchange list needs to be populated, and sets ForceRefresh according to the trigger:

    TriggerForceRefreshExpected behavior
    The user clicks the Refresh button in the Connector UI true Hard refresh: invalidate the local cache and re-read exchanges from the host document.
    A programmatic refresh — for example, the host calling RefreshExchangeList() after a document switch, create, or delete false (default) You may return cached results for a faster response.

    Honoring the flag

    Inspect filter.ForceRefresh and skip your cache only when it is true. On a hard refresh, re-read from the host document and update your local cache so it reflects the latest data:

    public override async Task<List<DataExchange>> GetExchangesAsync(ExchangeSearchFilter filter)
    {
        // Soft (programmatic) refresh: reuse the cached list for a fast response.
        if (!filter.ForceRefresh)
        {
            var cached = GetCachedExchanges();
            if (cached.Count > 0)
            {
                return cached;
            }
        }
    
        // Hard refresh (user clicked Refresh), or the cache is empty:
        // re-read from the host document and refresh the local cache.
        var exchanges = await FetchExchangesFromHostAsync(filter);
        UpdateLocalCache(exchanges);
        return exchanges;
    }
    
    Show More

    GetCachedExchanges is the abstract method every base model already implements; FetchExchangesFromHostAsync and UpdateLocalCache are placeholders for your own logic. For the full pattern, see Refreshing the exchange list.


    Fallback Callback URLs

    SDKOptionsDefaultSetup and AuthOptions now support a FallbackRedirectUrls property. When the primary OAuth callback port is in use by another application, the SDK automatically tries each fallback URL in order. All URLs must be pre-registered as valid redirect URIs in the APS portal.

    var options = new SDKOptionsDefaultSetup
    {
        ClientId = "your-client-id",
        CallBack = "http://localhost:8080/",
        FallbackRedirectUrls = new List<string>
        {
            "http://localhost:9090/",
            "http://localhost:3000/",
        },
        // ... other properties
    };
    
    Show More

    If all configured ports are exhausted, the SDK throws AllCallbackPortsInUseException (instead of PortInUseException). Update any existing catch blocks if you handle authentication port errors:

    try
    {
        IClient client = await Task.Run(() => new Client(options));
    }
    catch (PortInUseException ex)
    {
        // Primary callback port is unavailable
    }
    catch (AllCallbackPortsInUseException ex)
    {
        // All configured callback ports are in use
        // ex.AttemptedUrls contains the URLs that were tried
    }
    
    Show More

    .NET 10 Support

    The Data Exchange SDK now supports .NET 10 (net10.0-windows) in addition to .NET 8 and .NET Framework 4.8. No code changes are required — existing connectors targeting net8.0-windows or net48 continue to work without modification.


    Mesh translation and output paths

    GUSDK 0.9.x handles long file paths natively. The SDK removed the previous %TEMP% long-path workaround. Mesh translation now uses the per-connector output directory derived from your SDK workspace setup (the path you provide through IStorage and connector initialization).

    Impact: If your connector initializes the SDK without a valid storage/workspace path, mesh translation fails fast with InvalidOperationException when the output directory is empty.

    What to do: Follow the Setting up the SDK pattern — create IStorage with a non-empty application workspace path before you construct SDKOptions and Client. Do not rely on implicit %TEMP% fallbacks.


    Newtonsoft.Json packaging

    In Release builds, Autodesk.Newtonsoft.Json is now ILRepacked into Autodesk.DataExchange.dll. It no longer ships as a standalone DLL or flows as a transitive NuGet dependency.

    Impact: This is not an API break — no public SDK type exposes a Newtonsoft type. However, if your connector code uses Newtonsoft.Json for its own serialization and previously relied on the SDK’s transitive reference, your project may fail to compile after upgrade.

    What to do: Add an explicit Newtonsoft.Json package reference from NuGet.org to your connector project. Do not reference Autodesk.Newtonsoft.Json in connector code.


    Parameter Service

    Custom parameter schema generation now uses an out-of-process service. This change is internal and does not affect the parameter registration API — your existing code for creating custom parameters continues to work without changes.

    Deployment note: The NuGet package now includes a ParameterService/ folder containing the service executable. If you manually copy SDK files during deployment (rather than using NuGet package restore), ensure the ParameterService/ folder and its contents are included alongside the SDK DLLs. The service process is started automatically by the SDK and terminates when the host application exits.

    Migration Steps

    Complete these steps to finish your v7.6.0 migration.

    Step 1 — Exception Namespace (Required: breaks compilation)

    1. Find-replace Autodesk.DataExchange.Exceptions.CustomExceptions. → Autodesk.DataExchange.Exceptions. across your codebase.
    2. Remove any remaining using Autodesk.DataExchange.Exceptions.CustomExceptions; directives, replacing with using Autodesk.DataExchange.Exceptions;.
    3. Build and confirm no compilation errors remain.

    Step 2 — New Interface Members (Required: breaks compilation for custom implementations only)

    Skip this step if you use only the SDK’s built-in implementations.

    1. If you implement IElement, add RenderStyle RenderStyle { get; }.
    2. If you implement IElementDataModel, add string RootAssetName { get; set; }.
    3. If you implement IInteropBridge, add void SetApplicationMode(ApplicationMode applicationMode).
    4. If you implement IInputDescriptor, add bool IsBeta { get; set; }.
    5. If you implement IExchangeSearchFilter, add bool ForceRefresh { get; set; } (default false).
    6. If you implement ILogger, add void Error(string message, Exception exception, string caller = null).

    Step 3 — Geometry Namespace and Engine (Required: breaks compilation)

    Items 1 through 4 apply only if your connector references geometry types directly, and only if you have not already done them on 7.5.x. Items 5 and 6 apply to every connector.

    1. Search your codebase for Autodesk.GeometryPrimitives.
    2. Replace each using with the matching Autodesk.GeometryUtilities.PrimitivesAPI namespace.
    3. Rebuild geometry creation, load, and viewable-orientation code paths.
    4. Validate render output on representative STEP/IFC models if you map colors or transparency. See Geometry namespace migration.
    5. Rebuild and repack so you deploy the GUSDK 0.9.4 native binaries and the matching GeometryUtilitiesService payload. See Geometry engine upgrade (GUSDK 0.9.4).
    6. Run your geometry regression set against the 7.5.x baseline. Expect mirrored STEP models to change, since 7.6.0 fixes BRep handling for mirrored geometry.

    Step 4 — Viewable Generation Removed (Required: breaks compilation)

    1. Remove calls to GenerateViewableAsync — viewable generation is now automatic after sync.
    2. Remove ViewableGenerationStarted / ViewableGenerationCompleted event subscriptions and their handlers.
    3. Remove references to ViewableGenerationStatus, ViewableGenerationException, and ViewableDetails.
    4. If you mock IGeometryUtilitiesServiceClient, remove GenerateSVFViewableAsync and ViewDataInfoData from your mocks.
    5. If you use ViewableWorldCoordinates, update the Vector3d namespace. See Local Viewable Generation Removed.

    Step 5 — Region for Schema Calls (Required if you call ISchemaSDK directly)

    Skip this step if your connector does not call the schema SDK in its own code.

    1. Identify every call to GetSchemaAsync or GetSchemasAsync.
    2. Pass the hub or project data-residency region on each call.
    3. Test a cold-cache schema fetch outside the US to confirm you no longer rely on the silent US default. See Region required for schema (ASR) calls.

    Step 6 — Element/ElementDataModel/ElementGeometry Interfaces (Required: breaks compilation)

    A local variable declared with var will often need no change. Don’t skip this step solely because most of your call sites use var — fields, properties, parameters, return types, generic declarations, and casts must still be reviewed; see “Who must migrate” in Element, ElementDataModel, and ElementGeometry Are Now Returned as Interfaces above.

    1. Run the discovery search from Element, ElementDataModel, and ElementGeometry Are Now Returned as Interfaces to enumerate candidate references.
    2. Review each result against the affected-members table in that section. Where your code consumes or exposes a value returned by an affected member, replace the concrete type with its corresponding interface: Element → IElement, ElementDataModel → IElementDataModel, ElementGeometry → IElementGeometry.
    3. Update nested and generic declarations the same way — for example, List<Element> becomes List<IElement>.
    4. Remove casts back to the concrete implementation unless a separate, documented API still requires one.
    5. Leave factory and constructor calls unchanged (see “Not affected by this migration” in the same section above) unless another migration item explicitly requires an update.
    6. Rebuild every target framework and build configuration your connector supports. Resolve remaining errors, including CS0029 (cannot implicitly convert type), CS0266 (cannot implicitly convert type; an explicit conversion exists), and CS1503 (argument cannot convert from one type to another).
    7. Run your unit and integration tests, particularly workflows that load elements, filter element collections, or retrieve geometry.

    Validation: Before moving on, confirm that no compilation errors remain from this migration, no SDK values returned as interfaces are cast back to concrete implementations unnecessarily, and every target framework and build configuration compiles clean.

    Step 7 — ADP Analytics (Required if you use ADP analytics)

    Skip this step if your connector never references IAdpAnalytics, AdpEvent, or ExchangeProcessStatus.

    1. Add a package reference to Autodesk.DataExchange.ADPAnalytics.Abstractions.
    2. Update the using directives for the moved types.
    3. Replace any reliance on the SDK registering IAdpAnalytics for you with an explicit RegisterAdpAnalytics call on SDKOptions.
    4. Run a scenario that emits analytics and confirm the events still reach your implementation. See ADP Analytics Moved to a Standalone Package.

    Step 8 — FeatureCapabilities (Non-breaking: removes deprecation warnings)

    1. Search your codebase for bridgeOptions.EnableTaskCancellation and bridgeOptions.EnableHideUnhideExchange.
    2. Replace with a FeatureCapabilities object — see Feature Capabilities.
    3. Evaluate EnableSelectElements — disable if your connector does not support element selection.
    4. If keeping EnableSelectElements enabled, implement SelectElementsAsync() in your IHostDataProvider.

    Step 9 — Testing

    1. If you mock IGeometryUtilitiesServiceClient in tests, update mocks to cover the new interface contract.
    2. Allow the SDK to spawn helper processes in integration test harnesses — GeometryUtilitiesService now runs out-of-process.
    3. Validate ValidationFailedException catch sites still bind the Context enum value.
    4. Re-test large-model sync end to end — confirm the streaming pipeline completes and watch for thread-pool starvation. See How sync works in 7.6.0.
    5. If your connector supports cancel and retry on the same ExchangeData, verify retry no longer throws NullReferenceException during asset-info collection (the SDK now clears unsaved geometry mappings on cancel).
    6. If you implement IElement, IElementDataModel, or IElementGeometry in test doubles, confirm your mocks/fakes are exercised by the code paths you updated in Step 6.
    7. If you use ADP analytics, run a scenario that emits events and confirm they still reach your implementation. A clean build does not prove the registration survived — see ADP Analytics Moved to a Standalone Package.
    8. Exercise RetrieveLatestExchangeAsync against an exchange with several revisions, now that it retrieves deltas. See Delta Retrieval for RetrieveLatestExchangeAsync.
    9. If you export STEP, re-check mirrored geometry against your baseline — 7.6.0 corrects BRep handling for mirrored STEP models.
    10. If your connector can emit the same SourceId for more than one element, test a model containing duplicates. See Source Identifier Uniqueness.

    The release also ships a ConsoleConnector sample application that exercises the SDK end to end — geometry attachment, primitives, design references, download as IFC, OBJ, and STEP, and telemetry. Use it as a reference implementation when a migrated code path does not behave as you expect.

    Step 10 — Optional Adoption

    Adopt these features as needed for your connector:

    1. Render style — If your connector renders element colors, adopt element.RenderStyle ?? geometry?.RenderStyle. See Adopt Instance-Level Render Style.
    2. Service warm-up — Set SDKOptions.WarmupServices = true for production connectors where first-call geometry latency is user-visible. See Pre-warm Services.
    3. Contact support URL — Set ContactSupportUrl on InteropBridgeOptions. If omitted, the Contact Support action routes to a default address not monitored for third-party connector issues.
    4. Revision notes — Review your UpdateExchangeAsync override — exchangeItem.Description now carries the user-entered revision note. Add a null check if your code reads this field.
    5. Beta badge — Set ShowTitleBarBetaBadge = true on FeatureCapabilities if your connector is in beta or early access.
    6. Context-aware Load forms — Implement IExchangeContextForm if your Load form needs exchange metadata. See IExchangeContextForm.
    7. Fallback callback URLs — Set FallbackRedirectUrls if OAuth port conflicts are a concern. Register all URLs in the APS portal first.
    8. Fire-and-forget async — For intentional background tasks, use TaskExtensions.SafeFireAndForget so failures reach your logger. See Fire-and-forget async tasks.
    9. Refresh trigger — If your base model caches the exchange list, honor ExchangeSearchFilter.ForceRefresh in GetExchangesAsync so the Refresh button bypasses the cache. See Refresh Trigger on the Exchange List.
    10. Sync performance tuning — Leave ConversionBatchSize (default 10000), SyncUploadConcurrency (default 20), and TuneThreadPool (default true) unchanged unless you have a measured reason. Lower ConversionBatchSize for large models that run out of memory during conversion; lower SyncUploadConcurrency for constrained networks; set TuneThreadPool = false only if your host manages the thread pool. If you already set ConversionBatchSize to anything other than 10000 (including the former default of 5000), retest large-model sync — it’s now honored for the first time. See Sync Performance Tuning.
    11. USD downloads — Offer USD as a download format if your users work with USD downstream. See USD Download Support.
    12. Geometry translation path — Leave UseConversionApiForGeometryTranslation at its default true. Review only if your connector sets it to false, and plan to remove that override. See Geometry Translation Path.
    13. SDK symbols — Enable SourceLink and symbol loading in your debugger if you want to step into SDK sources. See Debugging with SDK Symbols.

    Step 11 — Deployment

    1. If you manually copy SDK files during deployment, ensure the ParameterService/ folder and its contents are included alongside the SDK DLLs.
    2. If your connector uses Newtonsoft.Json for its own code, add an explicit NuGet package reference — do not rely on a transitive SDK reference. See Newtonsoft.Json packaging.
    3. Confirm IStorage is initialized with a valid workspace path before client creation. See Mesh translation and output paths.
    4. Confirm the package you ship carries the GUSDK 0.9.4 native binaries rather than a stale 0.9.3 payload. See Geometry engine upgrade (GUSDK 0.9.4).
    5. If you use ADP analytics, ship Autodesk.DataExchange.ADPAnalytics.Abstractions alongside the SDK. See ADP Analytics Moved to a Standalone Package.
    6. If you ship a Chinese UI, bundle the zh-CN locale yourself and note the change in your release notes. See Chinese UI Locale Removed.

    Step 12 — Classification, Types, and Design Instancing

    1. Required if applicable — if your connector defines multiple types with the same name in different branches of a model, review those code paths against Type Attribution Fix; scope by-name SetType calls with under where the name isn’t unique model-wide.
    2. Recommended — migrate calls that construct ElementProperties to AddElement + Classify/DefineType to avoid CS0618 deprecation warnings ahead of removal. See ElementProperties and the classification-agnostic model.
    3. Optional — adopt GetOrCreateDesignRef and InstantiateDesignBySourceId if your connector reuses geometry (blocks, families, sub-assemblies) and currently duplicates it per instance. See Working with design instancing.
    4. Recommended — replace InstantiateDesignById, GetDesignInstancesById, and IDesign.ID with InstantiateDesignBySourceId, GetDesignInstancesBySourceId, and IDesign.SourceId. The old members are [Obsolete] and raise CS0618; they are removed in the next major version. If you pass GetOrCreateDesignRef’s third argument by name, rename it to sourceId.
    5. Recommended — replace GetElementById with GetElementsBySourceId or GetElementByUniqueId, CreateDesignRef with GetOrCreateDesignRef, and RetrieveLatestExchangeDataAsync with RetrieveLatestExchangeAsync. All three are newly [Obsolete] in this release and raise CS0618. See Source Identifier Uniqueness.

    Step 13 — Final Verification

    1. Build and confirm no compilation errors from the IElement/IElementDataModel/IElementGeometry migration (Step 6) and no deprecation warnings (CS0618).
    2. Run your full test suite.
    3. Set up log monitoring for geometry translation failures.

    See Also