Working with C#

The HOOPS Exchange C# API is currently available. The API mirrors the traditional Exchange C API, but there are some important differences to keep in mind when using C#. Most of the recommendations deal with using wrapper classes, marshalling memory, and disposing of memory.

The C# API is available under the API namespace.

Wrapper classes

Use the wrapper classes when possible. They are designed to simplify the process of working with Exchange by encapsulating the most common operations. For example, to initialize your data, the API has been simplified to the following:

A3DRWParamsLoadData loadParams;
API.Initialize(out loadParams);

Marshalling

The C# API has several methods for marshalling arrays from unmanaged memory to managed memory and vice-versa. These methods are part of the ArrayWrapper utility class.

We try to expose direct types and data types as much as possible. Nevertheless, many types are just IntPtr, especially in API function parameters. IntPtr can represent an A3DEntity, a pointer, an array, or even an array of arrays. Please refer to C API documentation to check how to handle them.

All of the ArrayWrapper functions have a Read and Write naming pattern. For example, ReadIntArray will convert IntPtr to a C# array, while WriteIntArray will convert a C# array to a C array.

int[] outputArray = ArrayWrapper.ReadIntArray(inputArray, size);

Alternatively, you can handle marshalling yourself if your application has special needs related to arrays.

Disposing

When you allocate unmanaged memory in the C API which is used in C#, it is your responsibility to ensure it is disposed of properly. You are strongly encouraged to use the IDispose interface for this purpose.

We recommend you declare your wrappers with the using keyword. If you don’t do this, you will need to manually call the Dispose() function once the data is no longer needed. For more details, see https://learn.microsoft.com/en-us/dotnet/standard/garbage-collection/implementing-dispose.

API changes

It is our goal to make every C function available in C#. However, implementing some functions don’t make sense from a language standpoint. For example, string conversions from Unicode to UTF-8 are not available, since all strings in C# are inherently UTF-8 compatible.

Additionally, deprecated functions from the C API have not been provided.