Generated .NET API#
Caution
The generated .NET API is an experimental part of Cantera and may be changed or removed without notice.
The .NET API is written in C# and supports .NET 8 (and newer) on all platforms that support both .NET and the Cantera C++ library. The .NET interface requires an installation of the .NET 8.0 SDK to build.
The .NET API implementation draws on two parts:
C# Code Generation, which translates CLib headers into corresponding C# implementations.
The .NET API included in
interfaces/dotnet, which contains hand-coded API wrappers that extend generated code to form the actual user interface.
Building the .NET Interface#
After building the main Cantera library with default options, switch
to the interfaces/dotnet directory and run
dotnet build
The .NET test suite is invoked by running
dotnet test
In order to force re-import of generated code from sourcegen, run
dotnet clean
C# Code Generation#
Source generation for the .NET interface is fully integrated into the build process. C# files used by the .NET API can be generated for informational purposes by running the following command from the root folder of the Cantera source code:
sourcegen --api=csharp --output=build/csharp
Generated C# files are placed in the output folder build/csharp. Note that this
step requires installation of sourcegen via
python -m pip install -e interfaces/sourcegen.
.NET Source Generator Overview#
The primary C# project is Cantera.csproj. This project uses P/Invoke extensively with
the native Cantera library via the Cantera C interface (CLib), and wraps the low-level
interfaces with classes and concepts familiar to a .NET developer. As part of the build
process, it invokes sourcegen to scaffold the interop code and some of the
code for the wrapper objects, such as simple properties which can mapped directly to
CLib getter and setter functions. Cantera.csproj targets .NET 8. This project will be
released as a NuGet package.
Cantera.Tests.csproj contains the unit tests for the Cantera .NET library and targets
.Net 8.
The examples directory contains separate projects for each Cantera example. These will
be packaged as a template for use with the .NET CLI, allowing developers to create a
solution with all the examples using dotnet new.
Extending the .NET API#
Like all of Cantera, we welcome contributions to the .NET interface.
Contributors should review general and
C#-specific coding standards. Please note that contributing to the
.NET interface requires a relatively advanced understanding of C#.
This includes being comfortable with unsafe blocks and interop concepts such as raw
pointers, understanding how to use Span<T> and similar memory APIs, and having a solid
grip on object-oriented library design.
Discussions about contributing to the .NET interface assumes the developer has installed the .NET SDK and is using the text editor of their choice, optionally with a plugin for C# development installed. Visual Studio is not required, and although contributors may choose to use it, submissions should not depend on Visual Studio or require the use of Windows.