Hexarc.Borsh 2.0.1

.NET 7.0
dotnet add package Hexarc.Borsh --version 2.0.1
NuGet\Install-Package Hexarc.Borsh -Version 2.0.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Hexarc.Borsh" Version="2.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Hexarc.Borsh --version 2.0.1
#r "nuget: Hexarc.Borsh, 2.0.1"
#r directive can be used in F# Interactive, C# scripting and .NET Interactive. Copy this into the interactive tool or source code of the script to reference the package.
// Install Hexarc.Borsh as a Cake Addin
#addin nuget:?package=Hexarc.Borsh&version=2.0.1

// Install Hexarc.Borsh as a Cake Tool
#tool nuget:?package=Hexarc.Borsh&version=2.0.1

Borsh in .NET

License NuGet Downloads

Hexarc.Borsh is .NET implementation of the Binary Object Representation Serializer for Hashing format.

Features

  • 100% C# library
  • Zero dependencies
  • Ready for Blazor WebAssembly

Supported platforms

.NET Hexarc.Borsh
6.x 1.x
7.x 2.x

Getting started

Install the package with the NuGet CLI:

dotnet add package Hexarc.Borsh

Reference the Hexarc.Borsh namespace in your code:

using Hexarc.Borsh;

Serialize and deserialize .NET objects via the BorshSerializer class:

[BorshObject]
public class Point
{
    [BorshPropertyOrder(0)]
    public Int32 X { get; init; }
    
    [BorshPropertyOrder(1)]
    public Int32 Y { get; init; }
    
    [BorshPropertyOrder(2)]
    public Int32 Z { get; init; }
}

var point = new Point() { X = 5, Y = 10, Z = 20 };

var raw = BorshSerializer.Serialize(point);
var restored = BorshSerializer.Deserialize<Point>(raw);

Features

These types can be serialized by default:

  • Byte, SByte, Boolean, Int16, UInt16, Int32, UInt32, Int64, UInt64, Int128, UInt128
  • Single, Double, Half
  • Nullable<T>
  • Enum
  • String
  • DateTime
  • ValueTuple
  • Arrays as T[]
  • List<T>
  • HashSet<T>
  • Dictionary<TKey, TValue>
  • Hexarc.Borsh.Option<T>
  • POCO like user defined classes

Object serialization

Serializable types must be annotated with the BorshObject attribute. The BorshIgnore attribute can be used to exclude properties from serialization.

[BorshObject]
public class Point
{
    [BorshPropertyOrder(0)]
    public required Int32 X { get; init; }
    
    [BorshPropertyOrder(1)]
    public required Int32 Y { get; init; }
    
    [BorshPropertyOrder(2)]
    public required Int32 Z { get; init; }
    
    // This property will be exluded from serialization.
    [BorshIgnore]
    public String? Memo { get; init; }
}

var raw = BorshSerializer.Serialize(new Point { X = 1, Y = 2, Z = 3 });

Records serialization:

[BorshObject]
public sealed record Rect(
    [property: BorshPropertyOrder(0)] Int32 Width,
    [property: BorshPropertyOrder(1)] Int32 Height
);

var rect = new Rect(10, 20);
var raw = BorshSerializer.Serialize(rect);

Nullable reference type serialization

Another important notice that Borsh is mostly designed to support the Rust type system. So null reference values are not supported in .NET implementation. Please use the special BorshOptional attribute or Hexarc.Borsh.Option<T> type.

Property annotation example:

[BorshObject]
public class PersonDetails
{
    [BorshPropertyOrder(0)]
    [BorshOptional]
    public String? FirstName { get; init; }

    [BorshPropertyOrder(1)]
    [BorshOptional]
    public String? LastName { get; init; }
}

In case you need to serialize a top level nullable reference type object:

String? input = Console.ReadLine();

var raw = BorshSerializer.Serialize(Option<String>.Create(input));
var restored = BorshSerializer.Deserialize<Option<String>>(raw);

Fixed array type serialization

The BorshFixedArray attribute allows to serialize fixed array types according to the BORSH specification:

[BorshObject]
public class Data
{
    [BorshPropertyOrder(0)]
    [BorshFixedArray(3)]
    public required Int32[] Numbers { get; init; }
}

var data = new Data { Numbers = new[] { 1, 2, 3 } };
var raw = BorshSerializer.Serialize(data);

Union type serialization

The BorshUnion attribute allows to serialize union types:

[BorshUnion(0, typeof(Circle))]
[BorshUnion(1, typeof(Square))]
[BorshObject]
public abstract class Figure {}

[BorshObject]
public sealed class Circle : Figure
{
    [BorshPropertyOrder(0)]
    public required Int32 Radius { get; init; }
}

[BorshObject]
public sealed class Square : Figure
{
    [BorshPropertyOrder(0)]
    public required Int32 SideSize { get; init; }
}

Figure square = new Square { SideSize = 1 };
var raw = BorshSerializer.Serialize(square);

Acknowledgments

Built with JetBrains tools for Open Source projects.

JetBrains Logo (Main) logo

License

MIT © Hexarc Software and its contributors

Product Versions
.NET net7.0
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.
  • net7.0

    • No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
2.0.1 53 11/18/2022
2.0.0 66 11/12/2022
1.3.1 3,529 8/31/2022
1.3.0 138 8/29/2022
1.2.2 127 8/28/2022
1.2.1 131 8/28/2022
1.2.0 140 8/26/2022
1.1.2 144 8/6/2022
1.1.1 3,442 7/15/2022
1.1.0 172 7/15/2022
1.0.0 5,471 2/26/2022
0.6.0 173 2/25/2022
0.5.0 165 2/24/2022
0.4.0 169 2/23/2022
0.3.0 166 2/22/2022
0.2.0 163 2/21/2022
0.1.0 171 2/20/2022
0.0.15 164 2/19/2022
0.0.14 158 2/18/2022
0.0.13 172 2/18/2022
0.0.12 172 2/17/2022
0.0.11 167 2/17/2022
0.0.10 160 2/16/2022
0.0.9 155 2/16/2022
0.0.8 157 2/16/2022
0.0.7 159 2/16/2022
0.0.6 168 2/16/2022
0.0.5 168 2/14/2022
0.0.4 154 2/10/2022
0.0.3 157 2/10/2022
0.0.2 169 2/9/2022
0.0.1 172 2/6/2022