Carmenta Engine .NET API
The Carmenta Engine .NET API consists of:
.NET assemblies with all the Carmenta Engine types.
Map controls for different GUI frameworks.
Intellisense files for the assemblies for integration with Visual Studio.
Documentation showing how the API should be used (this document), plus reference documentation for all the .NET types.
Samples that show you how to use the .NET API.
Architecture
With a few exceptions, the types in the .NET API are built as thin, managed wrappers around the unmanaged Carmenta Engine kernel classes. The class hierarchy closely corresponds to the Carmenta Engine object model seen in the other APIs and in Carmenta Studio.
There are several different types of classes and other types in the API:
Static classes are classes with only static methods, and are never instantiated. A good example is the Runtime class, which contains static methods for initialization and shutdown of Carmenta Engine.
Reference classes are those that inherit from EngineObject. Each instance of these classes internally holds a reference to a Carmenta Engine kernel object. Accessing properties or calling methods affect the kernel object directly.
All collections are implemented as concrete classes that implement the generic IList<T> interface. The collection classes are reference classes, they inherit from EngineObject, and hold a reference to a collection instance in the Carmenta Engine kernel. Adding or removing objects to a collection directly modifies the kernel object.
Value types all have their own copy of their data, and the most commonly used value types are implemented as pure .NET structures for performance reasons. Good examples of this are the Point and AttributeValue types. A few types that are value types in the other APIs, like Pen and Brush, are implemented as classes in .NET.
Callback interfaces. Some classes may perform callbacks back to application code, using callback interfaces, for instance the custom operator and custom dataset classes. The application creates objects which implement the corresponding callback interfaces, and registers these with the API classes.
Carmenta Engine types should in general not be used as base classes. The following types are exceptions to this rule:
All built-in tools, for example StandardTool.
All custom object interfaces.
Namespaces
Namespace | Functionality |
|---|---|
Carmenta.Engine | Contains the public Carmenta Engine API except the GUI controls. Note that the functionality is split over several assemblies but all public types are defined in the Carmenta.Engine namespace. |
Carmenta.Engine.Forms | Contains the Windows Forms MapControl. |
Carmenta.Engine.Controls | Contains the Windows Presentation Foundation MapControl. |
Carmenta.Engine.Maui | Contains the MAUI MapControl. |
Carmenta.Engine.Android | Contains the Android/.NET MapControl. |
There is also an undocumented Carmenta.Internal.Engine namespace that is used by the .NET API implementation and using anything from it is not supported.
Collections
Carmenta Engine provides several collection classes that holds items of a specific type. The following picture shows the inheritance hierarchy of the PointCollection and StringCollection classes but all the other collections have a similar structure.
 |
As you can see in the picture all collections inherit from the abstract class EngineObject and implement the System::Collections::Generic::IList<T> interface makes them easy to use in the .NET languages, for instance in a C# foreach loop.
When collections are passed as arguments to methods there will always exist an overload that takes an IEnumerable<T>.
// Constructor that takes a Carmenta Engine collection that holds Point items
void Foo(PointCollection points);
// Constructor overload that takes an IEnumerable<Point>
void Foo(IEnumerable<Point> points);
The first overload takes a Carmenta Engine collection, implemented in the Carmenta Engine kernel, and Foo will extract the kernel collection and pass it to the kernel implementation of Foo. The second overload takes a standard .NET IEnumerable<Point> which will be copied into a new kernel collection and it is the copy that is passed to the kernel implementation of Foo.
One example where this difference is critical to understand are the LineGeometry constructors. The constructor that takes a PointCollection will instantiate a new LineGeometry that takes ownership of the specified collection while the constructor that takes an IEnumerable<Point> will copy the points into the new geometry.
Object finalization
A class that holds a reference to a kernel object will release the reference in its finalizer. This works automatically together with the .NET garbage collector. Relying on the finalizer is usually fine but in some cases, typically performance critical loops that work with very large numbers of objects, you may want to release the kernel objects explicitly; by calling EngineObject.Dispose or through a using statement that disposes the object.
Error handling
The .NET API contains one exception class, EngineException that is thrown when an error occurs in the Carmenta Engine kernel. Errors that occur in the API layer typically use standard .NET exceptions, such as System.ArgumentException and System.NullPointerException, but some API calls throw EngineExceptions.
When using a map control, EngineExceptions can occur as a result of the control accessing the Carmenta Engine kernel. It is possible to get those errors through events instead of exceptions by handling the event IMapControl.Error.
There are also errors that can occur anytime due to asynchronous code started by the kernel. Read more about these here Runtime.Error.
Using the .NET API
The Carmenta Engine .NET assemblies are contained in NuGet packages. The following tables lists the available packages and the minimum .NET runtime version required to use them:
Package | Target frameworks | .NET Runtime required | Supported platforms |
|---|---|---|---|
Carmenta.Engine | .NET Standard 2.0 | .NET 6.0 or .NET Framework 4.7.2 | Windows, Linux, Android |
Carmenta.Engine.Forms | .NET 6.0 or .NET Framework 4.7.2 | .NET 6.0 or .NET Framework 4.7.2 | Windows |
Carmenta.Engine.Controls | .NET 6.0 or .NET Framework 4.7.2 | .NET 6.0 or .NET Framework 4.7.2 | Windows |
Carmenta.Engine.Maui | .NET 8.0 | .NET 8.0 | Windows, Android |
Carmenta.Engine.Android | .NET 8.0 | .NET 8.0 | Android |
Carmenta.Engine.Ecw | .NET Standard 2.0 | .NET 6.0 or .NET Framework 4.7.2 | Windows, Linux, Android |
Most applications will use just the Carmenta.Engine package, plus one of the other packages depending on platform. If you want to use the EcwDataSet, additional runtime files are needed, these are distributed in the Carmenta.Engine.Ecw NuGet package. See the EcwDataSet for more information about how to install the ECW runtime files.
On Linux the Carmenta Engine NuGet packages are located in the /usr/share/carmenta/packages directory.
Samples
There are several samples included in the SDK that use the .NET API. Most of them targets .NET 6.0. The HelloWorldWinForms and HelloWorldWpf samples also comes in versions targeting .NET Framework 4.7.2, but they are otherwise identical. All samples are found at the Programming Samples page.
Setting up a Visual Studio project
When using the Carmenta Engine .NET API, you can create a .NET 6.0 or later, or a .NET Framework 4.7.2 or later, application. You can also create a .NET Standard code library.
In Visual Studio there are two ways for a project to manage NuGet packages, the Carmenta Engine NuGet packages will only work using the PackageReference style. This is how you create a project with Carmenta Engine:
Open Tools->NuGet Package Manager->Package Manager Settings. There's a drop-down list named Default project management format. If you use .NET 6.0 or later, this setting will be ignored since it will always use PackageReference. We recommend that you check the Allow format selection on first package install checkbox so that you can choose for each project. Otherwise it becomes a global setting for all new projects in Visual Studio.
If you already have a project that includes a packages.config file, you can remove any already added NuGet packages and remove the packages.config file from the project. Then select PackageReference and add the NuGet references again.
Once the management format is set, create a NuGet package source to find the Carmenta Engine packages:
Click Package Sources in the list to the left.
Click the plus button to add a new source.
Enter a suitable name and browse to the "packages" folder in the Carmenta Engine SDK folder.
Click OK.
Add the Carmenta Engine NuGet packages:
Right-click on the project and select Manage NuGet references...
Select the new source that you added in the drop-down list in the top right.
Click on Browse to look at all of the packages in the source.
Select Carmenta.Engine and install it.
For a Windows Forms application, select the Carmenta.Engine.Forms package and install it.
For a Windows Presentation Foundation application, select the Carmenta.Engine.Controls package and install it.
As the Carmenta Engine NuGet packages only contain 64-bit libraries, the PlatformTarget should be set to x64 in the build properties for the project, when targeting Windows.
You can also use .NET 6.0 and the dotnet command to build applications and assemblies that use the Carmenta Engine .NET API.