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. Only included in the Carmenta Engine .NET Standard API. |
Carmenta.Engine.Android | Contains the Android/.NET MapControl. Only included in the Carmenta Engine .NET Standard API. |
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 MapControl accessing the Carmenta Engine kernel. It is possible to get those errors through events instead of exceptions by handling the event MapControl.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
How to use the .NET API depends on whether you target .NET Framework or .NET 6.0 or later or .NET Standard. In short, a project that targets .NET 6.0 or .NET Standard can only use the Carmenta Engine .NET Standard API. A project that targets .NET Framework can use the Carmenta Engine .NET Framework API, if it targets .NET Framework 4.7.2 or later, it can also choose to use the Carmenta Engine .NET Standard API.
You can find information on .NET Standard here: https://docs.microsoft.com/dotnet/standard/net-standard
The Carmenta Engine .NET Framework API
Supports Visual Studio 2019 or later.
The Carmenta Engine .NET Framework API targets .NET Framework 4.0. When you create a .NET Framework project, the Carmenta Engine assemblies will be available in the Visual Studio Reference Manager. You probably also want to add one or both of the two map controls to the Visual Studio toolbox, to be able to use them in the Windows Forms and Windows Presentation Foundation designers.
If you target .NET Framework 4.7.2 or later, you also have the possibility to use the Carmenta Engine .NET Standard API.
Setting up a Visual Studio project
Setting up a new project using the .NET Framework API is done by creating a new project and add references to the Carmenta Engine assemblies you're going to use. You probably also want to add one or both of the two map controls to the Visual Studio toolbox, to be able to use them in the Windows Forms and Windows Presentation Foundation designers.
Samples
There are several .NET samples available from the Programming Samples page, using different GUI map controls.
The Carmenta Engine .NET Standard API
Supports Visual Studio 2017 or later.
The Carmenta Engine .NET Standard API targets .NET Standard 2.0 instead of .NET Framework 4.0.
The Carmenta Engine .NET assemblies for .NET Standard are contained in NuGet packages. The Carmenta Engine package contains all of the Carmenta Engine .NET assemblies except for the Windows Forms, WPF, MAUI and Android/.NET map controls. The Carmenta Engine Windows Forms MapControl is located in the Carmenta Engine Forms package, the WPF MapControl is in the Carmenta Engine Controls package, the the MAUI MapControl is in the Carmenta Engine Maui package and the Android/.NET MapControl is in the Carmenta Engine Android package. If you want to use the EcwDataSet, additional runtime files are needed and are distributed in a NuGet package for use with the Carmenta Engine .NET Standard API. See the EcwDataSet for more information about how to install the ECW runtime files.
The Carmenta Engine .NET Standard API is built targeting .NET Standard 2.0, see the table below for supported .NET versions.
Implementation | Minimum version | Supported platforms |
|---|---|---|
.NET | 6.0 | Windows, Linux, Android |
.NET Framework | 4.7.2 | Windows |
When using .NET 6.0 and the Carmenta Engine .NET Standard API, applications can be built on Windows or Linux and target Windows, Linux and Android.
The Windows Forms and WPF map controls are only available for Windows, the Android/.NET map control is only available for Android and the MAUI map control is only available for Windows and Android.
On Linux the Carmenta Engine NuGet packages are located in the /usr/share/carmenta/packages directory.
Samples
The samples using the Carmenta Engine .NET Standard API is Simple tile server sample for Windows and Linux, the .NET 6 versions of the Sample application using C# and Windows Forms and the Sample application using C# and Windows Presentation Foundation samples for Windows, the HelloWorldAndroidNet sample application for Android for Android and the HelloWorldMaui sample application sample for Android and Windows. The other .NET Framework samples can be converted to use .NET Standard instead of .NET Framework by removing the Carmenta Engine references and following the guide on how to set up a project further down in this article. All samples are found at the Programming Samples page.
Changes compared to the Carmenta Engine .NET Framework API
The Carmenta Engine .NET Standard API targets .NET Standard 2.0 instead of .NET Framework 4.0. For general information on .NET Standard, see https://docs.microsoft.com/dotnet/standard/net-standard.
The Carmenta Engine .NET Standard API retains source compatibility with the Carmenta Engine .NET Framework API except for the following:
The use of System.Drawing.Color in the Carmenta Engine .NET Framework API has been replaced by a new Carmenta.Engine.Color class.
CustomObjects using the Carmenta Engine .NET Framework API can not be loaded in an application using the Carmenta Engine .NET Standard API. Use the Carmenta Engine Standard API when building the CustomObjects to make them work.
Setting up a Visual Studio project
When using the Carmenta Engine .NET Standard 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 .NET Framework application you have NuGet packages for the Windows Forms and Windows Presentation Foundation map controls that you can also install at this point if you created such a project.
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 uses the Carmenta Engine .NET Standard API on Windows and Linux. When building .NET applications using the Carmenta Engine .NET Standard API, on Windows or Linux, all supported platforms, Windows, Linux or Android, can be used as the target platform.