Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cyriaca/Azura
source generation based serialization
https://github.com/cyriaca/Azura
csharp-sourcegenerator
Last synced: about 1 month ago
JSON representation
source generation based serialization
- Host: GitHub
- URL: https://github.com/cyriaca/Azura
- Owner: cyriaca
- Created: 2021-01-19T06:45:14.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2022-01-08T10:49:44.000Z (almost 3 years ago)
- Last Synced: 2024-11-02T17:03:41.914Z (about 1 month ago)
- Topics: csharp-sourcegenerator
- Language: C#
- Homepage:
- Size: 113 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- RSCG_Examples - Azura
README
# Azura
source generation based serialization
| Package | Release |
|------------------------|---------|
| `Azura` | [](https://www.nuget.org/packages/Azura/)|
| `Azura.Generator` | [](https://www.nuget.org/packages/Azura.Generator/) |
## Why?
Generating source code instead of relying on reflection is nice. For example,
when using NativeAOT you should be able to strip reflection metadata and
still have serialization work, as everything is hooked up at design time.
Target use case is communication between game clients and third-party programs.
* Generates serialization constructs for structs/classes/records
- Get-only properties / readonly fields are supported if type has `partial`
* Has default serializers for common BCL types
- `byte` / `sbyte` / `ushort` / `short` / `uint` / `int` / `ulong` / `long`
- Also supports enum types
- `float` / `double` / `char` / `bool`
- `Guid` / `TimeSpan` / `DateTime` / `decimal`
- `string`
- `T[]` / `List` / `HashSet` / `Dictionary`
- Includes faster path for arrays of primitives
* Supports nullable types (value types, reference types in nullable context)
* Native endianness conversion (stored as little-endian)
## Usage
0. Add generator library (includes base package, does not need to be explicitly included)
```xml
```
1. Define a data type and mark properties or fields
```csharp
using Azura;
[Azura]
public record Data
{
[Azura] public int Property1 { get; init; }
[Azura] public string? Property2 { get; init; }
[Azura] public string?[]? Property3 { get; init; }
}
```
2. Serialize the data
```csharp
var data = new Data {Property2 = "Execute order", Property1 = 66};
data.Serialize(stream);
```
3. Retrieve the data
- Helper types are generated as `Serialization`
```csharp
var data = DataSerialization.Deserialize(stream);
```
## Limitations
* Cannot serialize generic types
## Pending features
* Serialize nested classes
## Binary format
* Numeric types are little-endian.
* Primitives are serialized as expected.
* Nullable types are prefixed with a byte flag.
* Collections and strings are prefixed with an s32 count followed by
elements serialized contiguously (if a supported type parameter is
nullable, those values are prefixed with a byte flag).
## Custom serialization
Custom serialization for existing library types can be added but requires
manual implementation of the below signatures in a class under the target
type's namespace named `Serialization`.
Value types
```csharp
public static T Deserialize(Stream stream);
public static void Deserialize(Stream stream, out T self) => self = Deserialize(stream);
public static void Serialize(T self, Stream stream) => Serialize(in self, stream);
public static void Serialize(this in T self, Stream stream);
```
Reference types
```csharp
public static T Deserialize(Stream stream);
public static void Deserialize(Stream stream, out T self) => self = Deserialize(stream);
public static void Serialize(this T self, Stream stream) => Serialize(in self, stream);
public static void Serialize(in T self, Stream stream);
```