"Fossies" - the Fresh Open Source Software Archive

Member "flatbuffers-23.1.21/docs/source/CsharpUsage.md" (21 Jan 2023, 9216 Bytes) of package /linux/misc/flatbuffers-23.1.21.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the last Fossies "Diffs" side-by-side code changes report for "CsharpUsage.md": 22.11.23_vs_22.12.06.

Use in C# {#flatbuffers_guide_use_c-sharp}

Before you get started

Before diving into the FlatBuffers usage in C#, it should be noted that the [Tutorial](@ref flatbuffers_guide_tutorial) page has a complete guide to general FlatBuffers usage in all of the supported languages (including C#). This page is designed to cover the nuances of FlatBuffers usage, specific to C#.

You should also have read the [Building](@ref flatbuffers_guide_building) documentation to build flatc and should be familiar with [Using the schema compiler](@ref flatbuffers_guide_using_schema_compiler) and [Writing a schema](@ref flatbuffers_guide_writing_schema).

FlatBuffers C# code location

The code for the FlatBuffers C# library can be found at flatbuffers/net/FlatBuffers. You can browse the library on the [FlatBuffers GitHub page](https://github.com/google/flatbuffers/tree/master/net/ FlatBuffers).

Building the FlatBuffers C# library

The FlatBuffers.csproj project contains multitargeting for .NET Standard 2.1, .NET Standard 2.0, and .NET Framework 4.6 (Unity 2017). Support for .NET Framework 3.5 (Unity 5) is provided by the FlatBuffers.net35.csproj project. In most cases (including Unity 2018 and newer), .NET Standard 2.0 is recommended.

You can build for a specific framework target when using the cross-platform .NET Core SDK by adding the -f command line option:

    dotnet build -f netstandard2.0 "FlatBuffers.csproj"

The FlatBuffers.csproj project also provides support for defining various conditional compilation symbols (see "Conditional compilation symbols" section below) using the -p command line option:

    dotnet build -f netstandard2.1 -p:ENABLE_SPAN_T=true -p:UNSAFE_BYTEBUFFER=true "FlatBuffers.csproj"

Testing the FlatBuffers C# library

The code to test the libraries can be found at flatbuffers/tests.

The test code for C# is located in the [FlatBuffers.Test](https://github.com/ google/flatbuffers/tree/master/tests/FlatBuffers.Test) subfolder. To run the tests, open FlatBuffers.Test.csproj in Visual Studio, and compile/run the project.

Optionally, you can run this using Mono instead. Once you have installed Mono, you can run the tests from the command line by running the following commands from inside the FlatBuffers.Test folder:

    mcs *.cs ../MyGame/Example/*.cs ../../net/FlatBuffers/*.cs
    mono Assert.exe

Using the FlatBuffers C# library

Note: See [Tutorial](@ref flatbuffers_guide_tutorial) for a more in-depth example of how to use FlatBuffers in C#.

FlatBuffers supports reading and writing binary FlatBuffers in C#.

To use FlatBuffers in your own code, first generate C# classes from your schema with the --csharp option to flatc. Then you can include both FlatBuffers and the generated code to read or write a FlatBuffer.

For example, here is how you would read a FlatBuffer binary file in C#: First, import the library and generated code. Then, you read a FlatBuffer binary file into a byte[]. You then turn the byte[] into a ByteBuffer, which you pass to the GetRootAsMyRootType function:

    using MyGame.Example;
    using Google.FlatBuffers;

    // This snippet ignores exceptions for brevity.
    byte[] data = File.ReadAllBytes("monsterdata_test.mon");

    ByteBuffer bb = new ByteBuffer(data);
    Monster monster = Monster.GetRootAsMonster(bb);

Now you can access the data from the Monster monster:

    short hp = monster.Hp;
    Vec3 pos = monster.Pos;

C# code naming follows standard C# style with PascalCasing identifiers, e.g. GetRootAsMyRootType. Also, values (except vectors and unions) are available as properties instead of parameterless accessor methods. The performance-enhancing methods to which you can pass an already created object are prefixed with Get, e.g.:

    // property
    var pos = monster.Pos;

    // method filling a preconstructed object
    var preconstructedPos = new Vec3();
    monster.GetPos(preconstructedPos);

Storing dictionaries in a FlatBuffer

FlatBuffers doesn't support dictionaries natively, but there is support to emulate their behavior with vectors and binary search, which means you can have fast lookups directly from a FlatBuffer without having to unpack your data into a Dictionary or similar.

To use it:

Text parsing

There currently is no support for parsing text (Schema's and JSON) directly from C#, though you could use the C++ parser through native call interfaces available to each language. Please see the C++ documentation for more on text parsing.

Object based API

FlatBuffers is all about memory efficiency, which is why its base API is written around using as little as possible of it. This does make the API clumsier (requiring pre-order construction of all data, and making mutation harder).

For times when efficiency is less important a more convenient object based API can be used (through --gen-object-api) that is able to unpack & pack a FlatBuffer into objects and standard System.Collections.Generic containers, allowing for convenient construction, access and mutation.

To use:

    // Deserialize from buffer into object.
    MonsterT monsterobj = GetMonster(flatbuffer).UnPack();

    // Update object directly like a C# class instance.
    Console.WriteLine(monsterobj.Name);
    monsterobj.Name = "Bob";  // Change the name.

    // Serialize into new flatbuffer.
    FlatBufferBuilder fbb = new FlatBufferBuilder(1);
    fbb.Finish(Monster.Pack(fbb, monsterobj).Value);

Json Serialization

An additional feature of the object API is the ability to allow you to serialize & deserialize a JSON text. To use Json Serialization, add --cs-gen-json-serializer option to flatc and add Newtonsoft.Json nuget package to csproj. This requires explicitly setting the --gen-object-api option as well.

    // Deserialize MonsterT from json
    string jsonText = File.ReadAllText(@"Resources/monsterdata_test.json");
    MonsterT mon = MonsterT.DeserializeFromJson(jsonText);

    // Serialize MonsterT to json
    string jsonText2 = mon.SerializeToJson();

Conditional compilation symbols

There are three conditional compilation symbols that have an impact on performance/features of the C# ByteBuffer implementation.

Using UNSAFE_BYTEBUFFER and BYTEBUFFER_NO_BOUNDS_CHECK together can yield a performance gain of ~15% for some operations, however doing so is potentially dangerous. Do so at your own risk!