Request

Response

    Migration Guide

    This guide helps you update your connector to the latest SDK, which includes attribute handling improvements and new features.


    New Features

    Exchange Descriptions

    The SDK adds support for exchange descriptions - a way to document changes similar to Git commit messages.

    Capabilities:

    • Add descriptions when creating or updating exchanges
    • View descriptions in Connector UI version history
    • Retrieve descriptions programmatically via SDK

    Learn more: Exchange Descriptions


    Attribute Handling Changes

    Overview

    The SDK introduces automatic metadata attributes and cleaner attribute naming. This improves exchange tracking and UI display without requiring changes to most existing code.

    The SDK automatically captures which tool and version created each exchange, making it easier to track exchange origins and diagnose problems. When an exchange has issues, you can immediately see what tool or version created it. The FDX Connector UI organizes this information clearly, separating system metadata (in “Authoring Connector” and “Authoring App” fields) from custom attributes (in the “Filters applied” section).

    For most developers, your existing code works as-is. The SDK handles the new metadata automatically.


    What Changed

    1. Automatic SDK Metadata

    The SDK now automatically adds four metadata attributes to every exchange, eliminating the need for developers to manually track this information and ensuring consistent data across all exchanges:

    AttributeDescriptionSource
    ConnectorName Name of your connector SDKOptions.ConnectorName
    ConnectorVersion Version of your connector SDKOptions.ConnectorVersion
    SourceApplicationName Host application name SDKOptions.HostApplicationName
    SourceApplicationVersion Host application version SDKOptions.HostApplicationVersion

    Impact: No code changes needed. These are added automatically.

    2. Attribute Name Format

    Attribute names no longer include the platformAttribute- prefix:

    Old FormatNew Format
    platformAttribute-ConnectorName ConnectorName
    platformAttribute-CustomFilter CustomFilter

    Impact: Only affects code that parses attribute names. The SDK handles reading both formats when loading exchanges.

    3. Enhanced UI Display

    The FDX Connector UI now displays authoring information separately, making it easier to distinguish between system metadata and custom filters:

    Before:

    • All attributes shown in “Filter by” section

    After:

    • Authoring Connector: Displays connector name and version (from SDK metadata)
    • Authoring App: Displays host app name and version (from SDK metadata)
    • Filters applied: Shows only custom attributes (SDK metadata excluded)

    This separation improves the user experience by clearly distinguishing between automatically captured system information and user-defined organizational filters.

    Impact: Better user experience. No code changes needed.

    Migration Scenarios

    Scenario 1: Using PlatformAttributes

    Existing Code:

    var client = new Client(sdkOptions);
    client.PlatformAttributes = () => new Dictionary<string, string>
    {
        { "Department", "Engineering" },
        { "ProjectType", "Commercial" }
    };
    

    Migration Required: None - code works as-is

    What Happens:

    • Your custom attributes (Department, ProjectType) are merged with SDK metadata
    • SDK automatically adds ConnectorName, ConnectorVersion, SourceApplicationName, SourceApplicationVersion
    • All attributes stored in exchange

    Scenario 2: Using ExchangeCreateRequest.Attributes (Alternative Approach)

    Existing Code:

    var exchangeRequest = new ExchangeCreateRequestACC
    {
        // ... other properties
        Attributes = new Dictionary<string, string>
        {
            { "Department", "Engineering" },
            { "ProjectType", "Commercial" }
        }
    };
    
    Show More

    Migration Recommended: Consider moving to Client.PlatformAttributes for cleaner code

    Alternative Approach:

    // Set once during initialization
    var client = new Client(sdkOptions);
    client.PlatformAttributes = () => new Dictionary<string, string>
    {
        { "Department", "Engineering" },
        { "ProjectType", "Commercial" }
    };
    
    // ExchangeCreateRequest no longer needs Attributes
    var exchangeRequest = new ExchangeCreateRequestACC
    {
        // ... other properties
        // Attributes property optional when using PlatformAttributes
    };
    
    Show More

    Benefits of PlatformAttributes:

    • Cleaner code - set attributes once instead of per-exchange
    • Better separation of concerns
    • Attributes can be dynamic (function is called for each exchange)

    Backward Compatibility:

    • Old code continues to work

    Scenario 3: Overriding SDK Metadata

    The SDK applies attributes in priority order: SDK Metadata (lowest) → PlatformAttributes → Request.Attributes (highest priority wins).

    You can override SDK metadata at the platform level:

    var client = new Client(sdkOptions);
    
    // Override SDK metadata (not typically recommended, but possible)
    client.PlatformAttributes = () => new Dictionary<string, string>
    {
        // Override SDK default connector name
        { "ConnectorName", "Custom Brand Name" },
        
        // Add custom attributes
        { "Department", "Engineering" },
        { "CostCenter", "CC-2024-001" }
    };
    
    Show More

    Or override at the request level when creating an exchange:

    var request = new CreateExchangeRequest
    {
        FolderId = folderId,
        Name = "Exchange Name",
        Attributes = new Dictionary<string, string>
        {
            // This will override SDK metadata and PlatformAttributes
            { "ConnectorName", "Request-Specific Custom Name" },
            { "Priority", "High" }
        }
    };
    
    await client.CreateExchangeAsync(request);
    
    Show More

    Use Cases:

    • White-labeling connectors
    • Custom branding requirements
    • Special deployment scenarios
    • Exchange-specific metadata customization

    Best Practices

    DO:

    • Use PlatformAttributes for custom metadata that helps users organize and filter exchanges
    • Use meaningful attribute names (e.g., “Department”, “ProjectPhase”)
    • Keep attribute values concise for better UI display

    DON’T:

    • Don’t use reserved SDK metadata keys (ConnectorName, ConnectorVersion, SourceApplicationName, SourceApplicationVersion) - they will throw an exception
    • Don’t include sensitive information in platform attributes (they are visible in the UI and stored in the exchange)

    Testing Attribute Changes

    1. Create a Test Exchange

    var exchangeRequest = new ExchangeCreateRequestACC
    {
        // ... exchange properties
    };
    
    var result = await client.CreateExchangeAsync(exchangeRequest);
    
    if (result.IsSuccess)
    {
        var exchange = result.Value;
        
        // Verify SDK metadata is present
        Assert.Contains("ConnectorName", exchange.Attributes.Keys);
        Assert.Contains("ConnectorVersion", exchange.Attributes.Keys);
        Assert.Contains("SourceApplicationName", exchange.Attributes.Keys);
        Assert.Contains("SourceApplicationVersion", exchange.Attributes.Keys);
        
        // Verify your custom attributes are present
        Assert.Contains("Department", exchange.Attributes.Keys);
        
        Console.WriteLine("Migration successful!");
    }
    
    Show More

    2. Verify UI Display

    1. Create an exchange using your connector
    2. Open the Connector UI
    3. Select the exchange
    4. In Exchange Details panel, verify:

      • Authoring Connector shows your connector name and version
      • Authoring App shows your host application name and version
      • Filters applied shows only your custom attributes (not SDK metadata)

    3. Test Loading Legacy Exchanges

    // Load an exchange created with SDK v6.x or earlier
    var oldExchange = await client.GetExchangeAsync(legacyExchangeId);
    
    // Attributes should still load correctly
    // SDK handles the platformAttribute- prefix automatically
    foreach (var attr in oldExchange.Attributes)
    {
        Console.WriteLine($"{attr.Key}: {attr.Value}");
        // Keys will NOT have "platformAttribute-" prefix
    }
    
    Show More

    Troubleshooting Attribute Changes

    Issue: Attributes Not Showing in UI

    Symptom: Custom attributes don’t appear in “Filters applied” section

    Cause: Attribute keys match SDK metadata keys

    Solution: Use different attribute key names

    // DON'T - conflicts with SDK metadata
    client.PlatformAttributes = () => new Dictionary<string, string>
    {
        { "ConnectorName", "MyValue" }  // Reserved key
    };
    
    // DO - use unique keys
    client.PlatformAttributes = () => new Dictionary<string, string>
    {
        { "CustomConnectorProperty", "MyValue" }
    };
    
    Show More

    Issue: Old Attribute Names Still in Database

    Symptom: Querying exchanges shows platformAttribute- prefix in some exchanges

    Cause: Legacy exchanges created before this release

    Solution: SDK handles this automatically when reading. If you need clean data:

    // The SDK provides clean attribute names regardless of how they're stored
    var exchange = await client.GetExchangeAsync(exchangeId);
    // exchange.Attributes will have clean names (no prefix)
    

    Issue: SDK Metadata Shows Wrong Values

    Symptom: Authoring Connector shows unexpected name/version

    Cause: SDKOptions not configured correctly

    Solution: Verify your SDKOptions initialization

    var sdkOptions = new SDKOptions
    {
        ConnectorName = "My Connector Name",        // Check this
        ConnectorVersion = "1.0.0",                 // Check this
        HostApplicationName = "Revit",              // Check this
        HostApplicationVersion = "2025",            // Check this
        // ... other options
    };
    
    Show More

    Breaking Changes - Attributes

    Breaking: Attribute Name Format

    If you have code that explicitly checks for the platformAttribute- prefix, you must update it.

    Before:

    if (attributeName.StartsWith("platformAttribute-"))
    {
        // Process attribute
    }
    

    After:

    // Attributes no longer have prefix
    // Process all application category attributes directly
    

    Not Breaking: Reading Legacy Exchanges

    The SDK automatically handles reading exchanges created with older SDK versions. Attribute names are normalized when loaded.


    Deleted APIs

    The following APIs have been deleted from the SDK. Update your code to use the recommended replacements.

    1. UpdateElement() Method Removed

    Removed: ElementDataModel.UpdateElement(elementId, elementProperties)

    Replacement: Set properties directly on the element object.

    // Before (removed)
    ElementDataModel.UpdateElement("ElementId", new ElementProperties
    {
        Transformation = newTransformation
    });
    
    // After
    var element = ElementDataModel.Elements.FirstOrDefault(e => e.Id == "ElementId");
    element.Transformation = newTransformation;
    
    Show More

    2. GetTypeParameters() Signature Changed

    Changed: GetTypeParameters(List<string> types) → GetTypeParameters(params string[] types)

    // Before
    var typeParams = data.GetTypeParameters(new List<string> { "type1", "type2" });
    
    // After - get all type parameters
    var allTypeParams = data.GetTypeParameters();
    
    // After - get specific type parameters
    var specificParams = data.GetTypeParameters("type1", "type2");
    
    Show More

    3. GetElementGeometryByElementAsync() Removed

    Removed: ElementDataModel.GetElementGeometryByElementAsync(element)

    Replacement: Use GetGeometriesAsync() or GetElementGeometriesByElementsAsync().

    // Before (removed)
    var geometry = await elementDataModel.GetElementGeometryByElementAsync(element);
    
    // After
    var geometries = await elementDataModel.GetElementGeometriesByElementsAsync(new[] { element });
    var elementGeometry = geometries[element].FirstOrDefault();
    

    4. SetGeometryConfiguration() Removed

    Removed: Client.SetGeometryConfiguration() and IClient.SetGeometryConfiguration()

    Migration: Remove all calls to this method. Geometry configuration is now handled automatically.

    5. IHostingProvider.GetExchangeMetaDataAsync() Renamed

    Removed: IHostingProvider.GetExchangeMetaDataAsync()

    Replacement: IHostingProvider.GetExchangeMetadataDescriptorAsync() - returns ExchangeMetadataDescriptor with status information.

    // Before (removed)
    public async Task<ExchangeMetaData> GetExchangeMetaDataAsync(string projectId, string itemId)
    {
        return await FetchMetadata(projectId, itemId);
    }
    
    // After
    public async Task<ExchangeMetadataDescriptor> GetExchangeMetadataDescriptorAsync(string projectId, string itemId)
    {
        try
        {
            var metadata = await FetchMetadata(projectId, itemId);
            return new ExchangeMetadataDescriptor { StatusCode = 200, Metadata = metadata };
        }
        catch (Exception ex)
        {
            return new ExchangeMetadataDescriptor { StatusCode = 500, ResponseMessage = ex.Message };
        }
    }
    
    Show More

    Geometry Stream Handling Changes

    The SDK simplifies geometry stream handling by removing wrapper classes and introducing extension methods for format conversions.

    Overview

    The refactor renames MemoryStreamGeometry to StreamGeometry, removes the ReturnGeometryAsMemoryStream option, and eliminates geometry wrapper classes. Users now work with FileGeometry by default and use extension methods for conversions when needed.

    What Changed

    1. MemoryStreamGeometry Renamed to StreamGeometry

    The class has been renamed for clarity and consistency.

    Before:

    var memStreamGeom = geometry as MemoryStreamGeometry;
    var stream = memStreamGeom.GetStream();
    

    After:

    var streamGeom = geometry as StreamGeometry;
    var stream = streamGeom.GetStream();
    

    Impact: Compilation error if using old name


    2. ReturnGeometryAsMemoryStream Option Removed

    The GeometryOutputOptions.ReturnGeometryAsMemoryStream property has been removed. Geometry is now always returned as FileGeometry by default.

    Before:

    var options = new GeometryOutputOptions { ReturnGeometryAsMemoryStream = true };
    var geometries = await elementDataModel.GetElementGeometriesAsync(elements, ct, options);
    var memStreamGeom = geometries.Values.First().First() as MemoryStreamGeometry;
    var stream = memStreamGeom.GetStream();
    

    After:

    var geometries = await elementDataModel.GetElementGeometriesAsync(elements, ct);
    var fileGeom = geometries.Values.First().First() as FileGeometry;
    
    // Convert to stream when needed using extension method
    var streamGeom = await fileGeom.AsStreamGeometryAsync(ct);
    var stream = streamGeom.GetStream();
    

    Impact: Compilation error if using removed property


    3. Geometry Wrapper Classes Removed

    The following wrapper classes have been removed:

    • Step
    • Ifc
    • Obj
    • Bimdex

    Before:

    using var memoryStream = new MemoryStream(stepData);
    var step = new Step(memoryStream);
    var geometryProperties = new GeometryProperties(step, renderStyle, units);
    

    After:

    using var memoryStream = new MemoryStream(stepData);
    var geometryProperties = new GeometryProperties(
        memoryStream, 
        GeometryFormat.Step, 
        renderStyle, 
        units);
    

    Impact: Compilation error if using wrapper classes


    4. New Extension Methods

    The SDK now provides extension methods in the Autodesk.DataExchange.Extensions namespace for converting between geometry types:

    // Convert StreamGeometry to FileGeometry
    Task<FileGeometry> AsFileGeometryAsync(
        this StreamGeometry streamGeometry, 
        string outputPath, 
        CancellationToken cancellationToken = default)
    
    // Convert FileGeometry to StreamGeometry
    Task<StreamGeometry> AsStreamGeometryAsync(
        this FileGeometry fileGeometry, 
        CancellationToken cancellationToken = default)
    
    // Convert ElementGeometry to StreamGeometry (only works for FileGeometry)
    Task<StreamGeometry> AsStreamGeometryAsync(
        this ElementGeometry elementGeometry, 
        CancellationToken cancellationToken = default)
    
    Show More

    Migration Scenarios - Geometry

    Scenario 1: Using MemoryStreamGeometry

    Existing Code:

    var geometries = await elementDataModel.GetElementGeometriesAsync(elements);
    foreach (var geom in geometries.Values.SelectMany(g => g))
    {
        if (geom is MemoryStreamGeometry memStreamGeom)
        {
            var stream = memStreamGeom.GetStream();
            // Process stream...
        }
    }
    
    Show More

    Migration Required: Replace class name

    Updated Code:

    var geometries = await elementDataModel.GetElementGeometriesAsync(elements);
    foreach (var geom in geometries.Values.SelectMany(g => g))
    {
        if (geom is StreamGeometry streamGeom)
        {
            var stream = streamGeom.GetStream();
            // Process stream...
        }
    }
    
    Show More

    Scenario 2: Using ReturnGeometryAsMemoryStream

    Existing Code:

    var options = new GeometryOutputOptions 
    { 
        ReturnGeometryAsMemoryStream = true 
    };
    var geometries = await elementDataModel.GetElementGeometriesAsync(elements, ct, options);
    
    foreach (var geom in geometries.Values.SelectMany(g => g))
    {
        var memStreamGeom = geom as MemoryStreamGeometry;
        if (memStreamGeom != null)
        {
            var stream = memStreamGeom.GetStream();
            // Process stream...
        }
    }
    
    Show More

    Migration Required: Use extension methods

    Updated Code:

    var geometries = await elementDataModel.GetElementGeometriesAsync(elements, ct);
    
    foreach (var geom in geometries.Values.SelectMany(g => g))
    {
        if (geom is FileGeometry fileGeom)
        {
            // Convert to stream when needed
            using var streamGeom = await fileGeom.AsStreamGeometryAsync(ct);
            var stream = streamGeom.GetStream();
            // Process stream...
            
            // StreamGeometry implements IDisposable - ensure proper cleanup
        }
    }
    
    Show More

    Scenario 3: Using Wrapper Classes

    Existing Code:

    using var stepStream = new MemoryStream(stepData);
    var step = new Step(stepStream);
    var geometryProps = new GeometryProperties(step, renderStyle);
    var geometry = ElementDataModel.CreateFileGeometry(geometryProps);
    

    Migration Required: Use GeometryProperties constructor directly

    Updated Code:

    using var stepStream = new MemoryStream(stepData);
    var geometryProps = new GeometryProperties(
        stepStream, 
        GeometryFormat.Step, 
        renderStyle);
    var geometry = ElementDataModel.CreateFileGeometry(geometryProps);
    

    Other Formats:

    // IFC
    var geometryProps = new GeometryProperties(ifcStream, GeometryFormat.Ifc, renderStyle);
    
    // OBJ
    var geometryProps = new GeometryProperties(objStream, GeometryFormat.Obj, renderStyle);
    
    // Bimdex
    var geometryProps = new GeometryProperties(bimdexStream, GeometryFormat.Bimdex, renderStyle);
    
    Show More

    Scenario 4: Converting FileGeometry to StreamGeometry

    New Pattern:

    var geometries = await elementDataModel.GetElementGeometriesAsync(elements);
    
    foreach (var geom in geometries.Values.SelectMany(g => g))
    {
        if (geom is FileGeometry fileGeom)
        {
            // Convert to stream for in-memory processing
            using var streamGeom = await fileGeom.AsStreamGeometryAsync();
            var stream = streamGeom.GetStream();
            
            // Read stream data
            byte[] data = new byte[stream.Length];
            await stream.ReadAsync(data, 0, data.Length);
            
            // Process data...
        }
    }
    
    Show More

    Scenario 5: Converting StreamGeometry to FileGeometry

    New Pattern:

    StreamGeometry streamGeometry = /* obtained from somewhere */;
    
    // Write to specific location
    var fileGeom = await streamGeometry.AsFileGeometryAsync(
        "C:/output/geometry.stp", 
        cancellationToken);
    
    Console.WriteLine($"Saved to: {fileGeom.FilePath}");
    
    Show More

    Testing Geometry Changes

    1. Test Class Rename

    var geometries = await elementDataModel.GetElementGeometriesAsync(elements);
    var firstGeom = geometries.Values.FirstOrDefault()?.FirstOrDefault();
    
    // Should work with new name
    Assert.IsType<StreamGeometry>(firstGeom);  // Not MemoryStreamGeometry
    

    2. Test Default FileGeometry Behavior

    var geometries = await elementDataModel.GetElementGeometriesAsync(elements);
    var firstGeom = geometries.Values.FirstOrDefault()?.FirstOrDefault();
    
    // Geometry should be FileGeometry by default
    Assert.IsType<FileGeometry>(firstGeom);
    Assert.False(string.IsNullOrEmpty(((FileGeometry)firstGeom).FilePath));
    

    3. Test Extension Methods

    var geometries = await elementDataModel.GetElementGeometriesAsync(elements);
    var fileGeom = geometries.Values.First().First() as FileGeometry;
    
    // Test conversion to stream
    using var streamGeom = await fileGeom.AsStreamGeometryAsync();
    Assert.NotNull(streamGeom);
    Assert.True(streamGeom.SizeInBytes > 0);
    
    // Test conversion back to file
    var outputPath = Path.Combine(Path.GetTempPath(), "test.stp");
    var newFileGeom = await streamGeom.AsFileGeometryAsync(outputPath);
    Assert.True(File.Exists(outputPath));
    
    Show More

    Breaking Changes - Geometry

    Breaking: Class Renamed

    MemoryStreamGeometry → StreamGeometry

    Action Required: Update all references

    Breaking: Property Removed

    GeometryOutputOptions.ReturnGeometryAsMemoryStream removed

    Action Required: Remove property usage, use extension methods instead

    Breaking: Classes Removed

    Step, Ifc, Obj, Bimdex wrapper classes removed

    Action Required: Use GeometryProperties constructor with GeometryFormat enum


    FAQ

    Q: Do I need to update existing exchanges?
    A: No. The SDK handles both old and new formats when reading exchanges.

    Q: Will old connectors work with new exchanges?
    A: Yes. Older SDK versions (v6.x and earlier) can read exchanges created by v7.1.0.

    Q: Can I disable automatic SDK metadata?
    A: No. SDK metadata is always added. However, you can override values using PlatformAttributes.

    Q: What happens if I use reserved attribute keys?
    A: Your values override the SDK defaults. This is allowed but not typically recommended.

    Q: Are attributes case-sensitive?
    A: Yes. Attribute keys are case-sensitive. Use exact casing: ConnectorName, not connectorname.


    Summary Checklist - Attributes

    • [ ] Review your usage of PlatformAttributes - no changes needed
    • [ ] If using ExchangeCreateRequest.Attributes, consider migrating to Client.PlatformAttributes
    • [ ] Update code that parses attribute names expecting platformAttribute- prefix
    • [ ] Update filtering/querying code to use clean attribute names
    • [ ] Test creating and loading exchanges
    • [ ] Verify UI display in Exchange Details panel
    • [ ] Test loading legacy exchanges created with older SDK versions

    Summary Checklist - Geometry

    • [ ] Replace all MemoryStreamGeometry references with StreamGeometry
    • [ ] Remove ReturnGeometryAsMemoryStream from GeometryOutputOptions
    • [ ] Replace wrapper class constructors with GeometryProperties(stream, format, ...)
    • [ ] Use .AsStreamGeometryAsync() when stream access is needed
    • [ ] Use .AsFileGeometryAsync(path) when persisting streams
    • [ ] Ensure proper disposal of StreamGeometry objects (using statements)
    • [ ] Test geometry loading and conversion in your connector

    Need Help? Refer to the SDK tutorials for complete examples: