Xe.BinaryMapper
1.1.0
See the version list below for details.
dotnet add package Xe.BinaryMapper --version 1.1.0
NuGet\Install-Package Xe.BinaryMapper -Version 1.1.0
<PackageReference Include="Xe.BinaryMapper" Version="1.1.0" />
paket add Xe.BinaryMapper --version 1.1.0
#r "nuget: Xe.BinaryMapper, 1.1.0"
// Install Xe.BinaryMapper as a Cake Addin
#addin nuget:?package=Xe.BinaryMapper&version=1.1.0
// Install Xe.BinaryMapper as a Cake Tool
#tool nuget:?package=Xe.BinaryMapper&version=1.1.0
About
Xe.BinaryMapper is a .Net library that is capable to deserialize and serialize a binary file into a managed object. BinaryMapper aims to be easy to use and to hack.
The library is available on NuGet and a Install-Package Xe.BinaryMapper
will make it available in your project in few seconds.
Learn more on https://www.nuget.org/packages/Xe.BinaryMapper/ .
Example
class Sample
{
[Data] public short Foo { get; set; }
[Data(offset: 4, count: 3, stride: 2)] public List<byte> Bar { get; set; }
}
...
var obj = new Sample
{
Foo = 123,
Bar = new List<byte>(){ 22, 44 }
};
BinaryMapping.WriteObject(writer, obj);
will be serialized into 7B 00 00 00 16 00 2C 00 00 00
.
How the data is de/serialized
The binary data serialized few lines ago can be break down in the following flow logic:
[Data] public short Foo { get; set; }
Write a short
(or System.Int16
), so 2 bytes, of foo that contains the 123
value: 7B 00
is written.
[Data(offset: 4, count: 3, stride: 2)] public List<byte> Bar { get; set; }
Move to offset
4, which is 4 bytes after the initial class definition. But we already written 2 bytes, so just move 2 bytes forward.
We now have a List<>
of two System.Byte
. The stride
between each value is 2 bytes, so write the first element 22
(our 0x16
), skip one byte of stride and do the same with the second element 44
.
But the count
is 3
, so we will just write other two bytes of zeroed data.
Can be done more?
Absolutely! Many primitive values are supported and can be customized (like how to de/serialize TimeSpan for example). Plus, nested class definitions can be used.
Usage
Serialization
The entire serialization happens in BinaryMapping.WriteObject
, which accepts a BinaryWriter
to write into a stream and the object to serialize.
The serialization always starts from BinaryWriter.BaseStream.Position
.
Deserialization
The entire de-serialization happens in BinaryMapping.ReadObject
, which accepts a BinaryReader
to read from the specified object and an existing object that will be used to store the read data.
The deserialization always starts from BinaryReader.BaseStream.Position
.
The Data attribute
The DataAttribute
is really important because, without it, the mapping does not happen.
The DataAttribute can be used only on a property that has public getter and setter, and has the following three optional parameters:
offset
where the data is physically located inside the file; the value is relative to the class definition. If not specified, the offset value is the same as the previous offset + its value size.count
how many times the item should be de/serialized. This is only useful forbyte[]
orList<T>
types.stride
how long is the actual data to de/serialize. This is very useful to skip some data when de/serializingList<T>
data.
Custom mapping
To customize how the de/serialization works for a specific type, a Mapping
object must be passed to BinaryMapping.SetMapping
.
A Mapping
object is defined by two actions: Writer
and Reader
. An example on how to customize a mapping can be found here:
BinaryMapping.SetMapping<bool>(new BinaryMapping.Mapping
{
Writer = x => x.Writer.Write((byte)((bool)x.Item ? 1 : 0)),
Reader = x => x.Reader.ReadByte() != 0
});
Types supported
byte
/System.Byte
1 byte long.sbyte
/System.SByte
1 byte long.short
/System.Int16
2 bytes long.ushort
/System.UInt16
2 bytes long.int
/System.Int32
4 bytes long.uint
/System.UInt32
4 bytes long.long
/System.Int64
8 bytes long.ulong
/System.UInt64
8 bytes long.float
/System.Single
4 bytes long.double
/System.Double
8 bytes long.Enum
variable length.TimeSpan
8 bytes long.DateTime
8 bytes long. Ignores the Kind property.Enum
customizable size based on inherted type.string
fixed size based fromcount
parameter.byte[]
fixed array of bytes based fromcount
parameter.List<>
fixed list based fromcount
parameter of any object or one of the types specified above.
Future plans
- Improve performance caching types
- Array and IEnumerable support
Projects that uses BinaryMapper
Kingdom Hearts 3 Save Editor
https://github.com/Xeeynamo/KH3SaveEditor
Written by the author of BinaryMapper. This is a perfect example on a real scenario of how BinaryMapper can be used.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
.NET Core | netcoreapp2.0 was computed. netcoreapp2.1 was computed. netcoreapp2.2 was computed. netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
.NET Standard | netstandard2.0 is compatible. netstandard2.1 was computed. |
.NET Framework | net461 was computed. net462 was computed. net463 was computed. net47 was computed. net471 was computed. net472 was computed. net48 was computed. net481 was computed. |
MonoAndroid | monoandroid was computed. |
MonoMac | monomac was computed. |
MonoTouch | monotouch was computed. |
Tizen | tizen40 was computed. tizen60 was computed. |
Xamarin.iOS | xamarinios was computed. |
Xamarin.Mac | xamarinmac was computed. |
Xamarin.TVOS | xamarintvos was computed. |
Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.0
- No dependencies.
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories (2)
Showing the top 2 popular GitHub repositories that depend on Xe.BinaryMapper:
Repository | Stars |
---|---|
OpenKH/OpenKh
Kingdom Hearts libraries, tools, game engine and documentation
|
|
Xeeynamo/KingdomSaveEditor
General purpose videogame save editor
|