C# Wrapper Classes
In addition to the direct bindings to HOOPS Exchange binaries, the C# API provides high-level classes called wrappers.
Wrapper classes encapsulate both the entity handle and a local copy of its data structure, providing a C#-idiomatic interface to HOOPS Exchange.
For example, a model file entity managed by an A3DAsmModelFile
/A3DAsmModelFileData
set has a wrapper class called A3DAsmModelFileWrapper
.
These classes offer features such as constructors, resource management, inheritance, and properties. However, the current version of the C# API limits wrappers to short-lived, read-only entities. For other functionalities, you can still fallback to call bindings.
Comparison with Struct Bindings
Wrapper classes enhance the struct bindings by providing:
- Simplified struct initialization
- Automatic data loading
- Memory management
- C# properties for seamless access
- Methods for entity creation and editing
Struct Initialization
Wrapper classes provide default constructors that initialize internal data structures using API.Initialize()
.
var export_params = new A3DRWParamsExportXMLDataWrapper();
A3DRWParamsExportXMLData export_params;
API.Initialize(out export_params);
A3DRWParamsExportXMLData export_params;
A3D_INITIALIZE_DATA(A3DRWParamsExportXMLData, export_params);
Data Load
When instantiated with an entity handle, wrapper classes automatically load entity data into the internal structure:
var model_file = new A3DAsmModelFileWrapper(model_file_handle);
A3DAsmModelFileData model_file_data;
API.Initialize(out model_file_data);
API.A3DAsmModelFileGet(model_file_handle, ref model_file_data);
A3DAsmModelFileData model_file_data;
A3D_INITIALIZE_DATA(A3DAsmModelFileData, model_file_data);
A3DAsmModelFileGet(model_file_handle, &model_file_data);
Memory Management
Wrapper classes implement the IDisposable interface to manage unmanaged resources. To free resources, call Dispose()
explicitly:
var model_file = new A3DAsmModelFileWrapper(model_file_handle);
// Use the model file
model_file.Dispose();
A3DAsmModelFileData model_file_data;
API.Initialize(out model_file_data);
API.A3DAsmModelFileGet(model_file_handle, ref model_file_data);
// Use the model file
API.A3DAsmModelFileGet(IntPtr.Zero, ref model_file_data);
A3DAsmModelFileData model_file_data;
A3D_INITIALIZE_DATA(A3DAsmModelFileData, model_file_data);
A3DAsmModelFileGet(model_file_handle, &model_file_data);
// Use the model file
A3DAsmModelFileGet(0, &model_file_data);
Alternatively, use the using statement to ensure automatic disposal:
using (var model_file = new A3DAsmModelFileWrapper(model_file_handle))
{
// Use the model file
}
For details, see Using objects that implement IDisposable (MSDN).
Properties
Wrapper classes expose fields of data structures as C# Properties:
var model_file = new A3DAsmModelFileWrapper(model_file_handle);
bool unit_from_cad = model_file.m_bUnitFromCAD; // Property get
A3DAsmModelFileData model_file_data;
API.Initialize(out model_file_data);
API.A3DAsmModelFileGet(model_file_handle, ref model_file_data);
bool unit_from_cad = model_file_data.m_bUnitFromCAD;
A3DAsmModelFileData model_file_data;
A3D_INITIALIZE_DATA(A3DAsmModelFileData, model_file_data);
A3DAsmModelFileGet(model_file_handle, &model_file_data);
A3DBool unit_from_cad = model_file_data.m_bUnitFromCAD;
Properties include both get
and set
accessors.
Array properties are automatically converted to and from unmanaged C-style arrays using C# Array Wrapper.
The example below shows how to retrieve a list of child product occurrences as an IntPtr[]
:
var product_occurrence = new A3DAsmProductOccurrence(product_occurrence_handle);
IntPtr[] children_handles = product_occurrence.m_ppPOccurrences;
A3DAsmProductOccurrenceData product_occurrence_data;
API.Initialize(out product_occurrence_data);
API.A3DAsmModelFileGet(product_occurrence_handle, ref product_occurrence_data);
IntPtr[] children_handles = ArrayWrapper.ReadIntPtrArray(
product_occurrence_data.m_ppPOccurrences,
product_occurrence_data.m_uiPOccurrencesSize
);
Entity Creation
Wrapper classes provide a Create()
method to encapsulate the entity creation process:
var model_file = new A3DAsmModelFileWrapper();
model_file.Create();
A3DAsmModelFileData model_file_data;
API.Initialize(out model_file_data);
IntPtr model_file_handle = IntPtr.Zero;
API.A3DAsmModelFileCreate(ref model_file_data, out model_file_handle);
A3DAsmModelFileData model_file_data;
A3D_INITIALIZE_DATA(A3DAsmModelFileData, model_file_data);
A3DAsmModelFile model_file_handle = 0;
A3DAsmModelFileCreate(&model_file_data, &model_file_handle);
Entity Edition
If an entity supports editing, wrapper classes provide an Edit()
method:
// ...
model_file.Edit();
// ...
API.A3DAsmModelFileEdit(ref model_file_data, model_file_handle);
// ...
A3DAsmModelFileEdit(&model_file_data, model_file_handle);