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:
| Attribute | Description | Source |
|---|---|---|
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 Format | New 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" }
}
};
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
};
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" }
};
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);
Use Cases:
- White-labeling connectors
- Custom branding requirements
- Special deployment scenarios
- Exchange-specific metadata customization
Best Practices
DO:
- Use
PlatformAttributesfor 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!");
}
2. Verify UI Display
- Create an exchange using your connector
- Open the Connector UI
- Select the exchange
- 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
}
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" }
};
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
};
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;
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");
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 };
}
}
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:
StepIfcObjBimdex
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)
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...
}
}
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...
}
}
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...
}
}
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
}
}
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);
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...
}
}
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}");
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));
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 toClient.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
MemoryStreamGeometryreferences withStreamGeometry - [ ] Remove
ReturnGeometryAsMemoryStreamfromGeometryOutputOptions - [ ] 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
StreamGeometryobjects (usingstatements) - [ ] Test geometry loading and conversion in your connector
Need Help? Refer to the SDK tutorials for complete examples: