You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/articles/framework/Serialization/entry-convert.md
+62-4Lines changed: 62 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,14 +11,41 @@ Because the `EntryConvert`-API can be confusing on first sight, we will split it
11
11
***Deserialize:** The encoded entry tree can be converted into objects after modification by the client with the overloads of `CreateInstance` and `UpdateInstance`
12
12
***Customization:** The behavior of both encoding and decoding can be customized to specific needs by providing a strategy implementing `ICustomSerialization`
13
13
14
+
## Supported Types
15
+
16
+
| .NET Type | EntryValueType | Format | Limitations |
| Dictionaries | Collection | Recursive sub-entries | Key must be a type supported by `ToObject`|
40
+
14
41
## Limitations
15
42
16
43
The `EntryConvert` API can convert objects and types as long as they comply with a few basic rules:
17
44
18
45
* Properties not fields: All attributes of a type must be defined as properties, not public fields. Therefor `public int Foo { get; set; }` instead of `public int Foo;`
19
-
* Public parameter-less constructor: All types within the class hierarchy need to offer a public constructor without parameters. In Generics this would be defined as `new()` or in code `public Foo() { }`. For the root object `EntryConvert` can extract Constructors as `MethodEntry`, which can be exchanged with a client and used to create instances.
20
-
* Primitivesor classes: The reflection approach used to deserialize the entry tree to objects requires reference access. Otherwise the modifications will only take part on a copy. Therefor properties need to be either of a primitive type like int, string, enumor a another class.
21
-
*Dictionaries of `<Primitive, Class`: Dictionaries are only supported if the key is a primitive type like `int` or `string`and the value is a class.
46
+
* Public parameter-less constructor: All types within the class hierarchy need to offer a public constructor without parameters. In Generics this would be defined as `new()` or in code `public Foo() { }`. For the root object `EntryConvert` can extract Constructors as `MethodEntry`, which can be exchanged with a client and used to create instances.
47
+
* Primitives, classes or supported structs: The reflection approach used to deserialize the entry tree to objects requires reference access. Otherwise the modifications will only take part on a copy. Therefor properties need to be either of a primitive type like int, string, enum, a class, or a supported struct (`Vector2`, `Vector3`, `Vector4`, `Quaternion`, `Plane`). Supported structs are automatically decomposed into editable sub-entries.
48
+
*Dictionary keys: Dictionary keys must be a type supported by `ToObject`, i.e. any type that can be converted to and from a string representation.
22
49
23
50
## Serialize Objects
24
51
@@ -141,6 +168,37 @@ public void Deserialize(Entry entry, FileStreamDummy dummy)
141
168
}
142
169
````
143
170
171
+
## Serialize Structs
172
+
173
+
`EntryConvert` supports decomposed serialization for the following `System.Numerics` struct types: `Vector2`, `Vector3`, `Vector4`, `Quaternion` and `Plane`. Instead of displaying unparseable strings like `<1.5, 2.5, 3.5>`, these structs are encoded as `Struct` entries with editable sub-entries for each component (X, Y, Z, W). When you serialize a class containing one of these types, the resulting entry will have sub-entries for each component of the struct.
174
+
175
+
````cs
176
+
publicclassRobotPosition
177
+
{
178
+
publicVector3Position { get; set; }
179
+
publicQuaternionOrientation { get; set; }
180
+
}
181
+
182
+
publicvoidSerialize()
183
+
{
184
+
varpos=newRobotPosition
185
+
{
186
+
Position=newVector3(1.5f, 2.5f, 3.5f),
187
+
Orientation=newQuaternion(0, 0, 0, 1)
188
+
};
189
+
varentry=EntryConvert.EncodeObject(pos);
190
+
// entry.SubEntries[0] (Position) has SubEntries: X=1.5, Y=2.5, Z=3.5
191
+
// entry.SubEntries[1] (Orientation) has SubEntries: X=0, Y=0, Z=0, W=1
192
+
}
193
+
194
+
publicvoidDeserialize(Entryentry)
195
+
{
196
+
varpos=newRobotPosition();
197
+
EntryConvert.UpdateInstance(pos, entry);
198
+
// pos.Position and pos.Orientation are reconstructed from sub-entry values
199
+
}
200
+
````
201
+
144
202
## ICustomSerialization
145
203
146
204
All public methods of `EntryConvert` have overloads that expect an instance of [ICustomSerialization](/src/Moryx/Serialization/ICustomSerialization.cs) to modify the behavior of the serializer where necessary. The overloads without the parameter use a Singleton instance of `DefaultSerialization`. When implementing a new version of `ICustomSerialization` it is recommended to derive from [DefaultSerialization](/src/Moryx/Serialization/DefaultSerialization.cs) and only override what shall behave different.
@@ -232,4 +290,4 @@ public Entry InvokeMethod(MethodEntry method)
232
290
233
291
### Serialize Constructors
234
292
235
-
In the previous sections, it was described that `EntryConvert` can also serialize constructors. The [EntrySerializeSerialization](/src/Moryx/Serialization/EntrySerializeSerialization.cs) only serializes constructors like methods with the [EntrySerializeAttribute](/src/Moryx/Serialization/EntryConvert/EntrySerializeAttribute.cs) defined.
293
+
In the previous sections, it was described that `EntryConvert` can also serialize constructors. The [EntrySerializeSerialization](/src/Moryx/Serialization/EntrySerializeSerialization.cs) only serializes constructors like methods with the [EntrySerializeAttribute](/src/Moryx/Serialization/EntryConvert/EntrySerializeAttribute.cs) defined.
The `IntegerColumnMapper` stores values as `long` in the database.
21
+
22
+
- Int16 - UInt64 are stored directly
23
+
- Enums are converted to their underlying integer type
24
+
-`DateTime` is stored as `Ticks`
25
+
-`DateOnly` is stored as `DayNumber` (days since 0001-01-01)
26
+
-`TimeOnly` is stored as `Ticks` (ticks since midnight)
27
+
-`bool` is stored as `1` or `0`
28
+
29
+
### FloatColumnMapper
30
+
31
+
The `FloatColumnMapper` stores values as `double` in the database. Supports `float`, `double` and `decimal` properties.
32
+
33
+
> **Note:** IEEE 754 special values (`NaN`, `+Infinity`, `-Infinity`) are not supported by all databases. PostgreSQL stores them natively in `float8`, but SQLite throws on `REAL` columns. The `SqliteProductsContext` registers an [Ieee754ValueConverter](/src/Moryx.Products.Management/Model/Ieee754ValueConverter.cs) that encodes these as sentinel values before writing and decodes them back when reading.
34
+
35
+
### TextColumnMapper
36
+
37
+
The `TextColumnMapper` stores values as `string` in the database.
38
+
39
+
-`string` is stored directly
40
+
-`Guid` is converted to its string representation
41
+
- Classes, interfaces and non-primitive structs (e.g. `Vector2`, `Vector3`, `Vector4`, `Quaternion`, `Plane`, `DateTimeOffset`) are serialized as JSON
0 commit comments