{"id":19244301,"url":"https://github.com/nanoframework/system.runtime.serialization","last_synced_at":"2025-04-21T09:33:30.520Z","repository":{"id":64863716,"uuid":"576886958","full_name":"nanoframework/System.Runtime.Serialization","owner":"nanoframework","description":":package: System.Runtime.Serialization library for .NET nanoFramework","archived":false,"fork":false,"pushed_at":"2025-04-02T11:16:37.000Z","size":134,"stargazers_count":2,"open_issues_count":0,"forks_count":5,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-19T16:40:51.075Z","etag":null,"topics":["csharp","embedded-systems","esp32","hacktoberfest","iot","nanoframework","nxp","serialization","stm32","texas-instruments"],"latest_commit_sha":null,"homepage":"https://www.nanoframework.net","language":"C#","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nanoframework.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"open_collective":"nanoframework","github":"nanoframework"}},"created_at":"2022-12-11T10:09:41.000Z","updated_at":"2025-04-02T11:07:23.000Z","dependencies_parsed_at":"2023-02-09T01:45:24.206Z","dependency_job_id":"817a9a1c-e6c0-4119-8752-d3911efc6288","html_url":"https://github.com/nanoframework/System.Runtime.Serialization","commit_stats":{"total_commits":42,"total_committers":3,"mean_commits":14.0,"dds":"0.47619047619047616","last_synced_commit":"ec6b398055f15a2f7f5886548ed623dc20dbdf75"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoframework%2FSystem.Runtime.Serialization","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoframework%2FSystem.Runtime.Serialization/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoframework%2FSystem.Runtime.Serialization/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nanoframework%2FSystem.Runtime.Serialization/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nanoframework","download_url":"https://codeload.github.com/nanoframework/System.Runtime.Serialization/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250032457,"owners_count":21363839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csharp","embedded-systems","esp32","hacktoberfest","iot","nanoframework","nxp","serialization","stm32","texas-instruments"],"created_at":"2024-11-09T17:22:54.911Z","updated_at":"2025-04-21T09:33:30.506Z","avatar_url":"https://github.com/nanoframework.png","language":"C#","funding_links":["https://opencollective.com/nanoframework","https://github.com/sponsors/nanoframework"],"categories":[],"sub_categories":[],"readme":"[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=nanoframework_System.Runtime.Serialization\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=nanoframework_System.Runtime.Serialization) [![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=nanoframework_System.Runtime.Serialization\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=nanoframework_System.Runtime.Serialization) [![NuGet](https://img.shields.io/nuget/dt/nanoFramework.System.Runtime.Serialization.svg?label=NuGet\u0026style=flat\u0026logo=nuget)](https://www.nuget.org/packages/nanoFramework.System.Runtime.Serialization/) [![#yourfirstpr](https://img.shields.io/badge/first--timers--only-friendly-blue.svg)](https://github.com/nanoframework/Home/blob/main/CONTRIBUTING.md) [![Discord](https://img.shields.io/discord/478725473862549535.svg?logo=discord\u0026logoColor=white\u0026label=Discord\u0026color=7289DA)](https://discord.gg/gCyBu8T)\n\n![nanoFramework logo](https://raw.githubusercontent.com/nanoframework/Home/main/resources/logo/nanoFramework-repo-logo.png)\n\n-----\n\n# Welcome to the .NET **nanoFramework** System.Runtime.Serialization repository\n\n## Build status\n\n| Component | Build Status | NuGet Package |\n|:-|---|---|\n| nanoFramework.System.Runtime.Serialization | [![Build Status](https://dev.azure.com/nanoframework/System.Runtime.Serialization/_apis/build/status/nanoframework.System.Runtime.Serialization?branchName=main)](https://dev.azure.com/nanoframework/System.Runtime.Serialization/_build/latest?definitionId=101\u0026branchName=main) | [![NuGet](https://img.shields.io/nuget/v/nanoFramework.System.Runtime.Serialization.svg?label=NuGet\u0026style=flat\u0026logo=nuget)](https://www.nuget.org/packages/nanoFramework.System.Runtime.Serialization/) |\n| nanoFramework.Serialization.Helper | [![Build Status](https://dev.azure.com/nanoframework/System.Runtime.Serialization/_apis/build/status/nanoframework.System.Runtime.Serialization?branchName=main)](https://dev.azure.com/nanoframework/System.Runtime.Serialization/_build/latest?definitionId=101\u0026branchName=main) | [![NuGet](https://img.shields.io/nuget/v/nanoFramework.Serialization.Helper.svg?label=NuGet\u0026style=flat\u0026logo=nuget)](https://www.nuget.org/packages/nanoFramework.Serialization.Helper/) |\n\n\n## Usage\n\nThe BinaryFormatter class serializes and deserializes an object, or an entire graph of connected objects, in binary format. This allows a compact storage or transition. Because it's implemented in native code, execution of serialization and deserialization operations are blazing fast.\n\nThe only requirement is to decorate a class or some of it's fields with the `[Serializable]` attribute.\nOther attributes are available to provide hints to the serialization engine so the serialization data it's reduced as much as possible. More on this on the next section.\n\nNative support for this feature it's available in all targets that have support for reflection enabled, unless support for this has been disabled by a build option.\n\n\u003e **Warning** the implementation of binary serialization for .NET **nanoFramework** is **NOT** compatible with the one of .NET Framework or .NET Core, meaning that it's not possible to use it to exchange data between the two frameworks. A helper class is available for .NET Framework and .NET Core to serializes and deserialize data coming from (or sent to) nanoFramework devices. More on this in the respective [section](#using-it-from-net-framework-or-net-core) bellow.\n\n### Serializing a class\n\nFollows a `Person` class that will be used in the following examples.\n\n```csharp\n[Serializable]\npublic class Person\n{\n    public string FirstName { get; set; }\n    public string LastName { get; set; }\n    public string Address;\n    public DateTime Birthday { get; set; }\n    public int ID { get; set; }\n    public string[] ArrayProperty { get; set; }\n    public Person Friend { get; set; }\n}\n```\n\nTo serialize it, simply call the method `Serialize()` and pass the class instance. Like this:\n\n```csharp\nvar nestedTestClass = new Person()\n{\n    FirstName = \"John\",\n    LastName = \"Doe\",\n    Birthday = new DateTime(1988, 4, 23),\n    ID = 2700,\n    Address = null,\n    ArrayProperty = new string[] { \"hello\", \"world\" },\n    Friend = new Person()\n    {\n        FirstName = \"Bob\",\n        LastName = \"Smith\",\n        Birthday = new DateTime(1983, 7, 3),\n        ID = 2000,\n        Address = \"123 Some St\",\n        ArrayProperty = new string[] { \"hi\", \"planet\" },\n    }\n};\n\nbyte[] serializedPerson = BinaryFormatter.Serialize(nestedTestClass);\n```\n\nThe `serializedPerson` byte array above will contain the binary representation of the `nestedTestClass`.\n\n\u003e **Note** As default all properties and fields in a serializable class will be serialized unless they are decorated with the `NonSerialized` attribute.\n\n### Deserializing a class\n\nIn order to deserialize a class from it's binary representation to an instance of the class, call the `Deserialize()` method and pass the binary representation.\n\n```csharp\n[Serializable]\n\nPerson anotherPerson = (Person)BinaryFormatter.Deserialize(serializedPerson);\n```\n\n### Serialization hints\n\nThere are optional attributes that can be used to provide hints to the serialization engine so the serialization data it's reduced as much as possible.\nTaking the `Person` class, follows the optimizations that are possible with the above example:\n\n```csharp\n[Serializable]\npublic class Person\n{\n    public string FirstName { get; set; }\n    public string LastName { get; set; }\n    public string Address;\n    public DateTime Birthday { get; set; }\n    [SerializationHints(RangeBias = 2000)]\n    public int ID { get; set; }\n    [SerializationHints(ArraySize = 2)]\n    public string[] ArrayProperty { get; set; }\n    public Person Friend { get; set; }\n}\n```\n\nThe `SerializationHints` has several options to improve the data packing.\nLooking at the `ID` property above, which is of `int` type, without any optimization it takes 32bits to store. Now, this is used to store an ID which, let's assume for the sake of the example that only store IDs bigger than 2000.\nUsing the RangeBias with a value of `2000` that value will be subtracted to the value being stored.\nIn the code above, the ID with value 2700, would be serialized as (2700 - 2700 = 700) which can be stored as 16bits value instead of the 32bits that it would initially take.\n\nAnother serialization hint is the array size. For the `ArrayProperty` let's assume that it will be always contain 2 elements.\nDecorating it with `ArraySize` and the size of the array, will store that information as part of the serialization data thus saving space that otherwise would be wasted with a generic count for the size of the array.\n\n### Using it from .NET Framework or .NET Core\n\nA helper class for .NET Framework or .NET Core (distributed as [NuGet package](https://www.nuget.org/packages/nanoFramework.Serialization.Helper)) is available to serialize and deserialize data coming from (or sent to) nanoFramework devices.\n\nThe usage it's exactly the same as with the code running in the nanoFramework device.\n\nTo serialize a class:\n\n```csharp\nvar binaryFormatter = new BinaryFormatter();\nvar serializedPerson = binaryFormatter.Serialize(personOne);\n```\n\nTo deserialize a binary representation back to a C# class:\n\n```csharp\nvar binaryFormatter = new BinaryFormatter();\nvar newPersonOne = binaryFormatter.Deserialize(UnitTestHelper.PersonOneSerialized) as Person;\n```\n\nIt is recommended that the source code for the classes being exchanged is the same in the projects for both frameworks.\nTo accomplish this one can use any of the usual approaches, like shared projects or linked files.\n\n\u003e **Warning** Make sure the fully qualified name of the class is the same at both ends. Failing to do so will prevent properly deserialize the data. This is another good reason for sharing the same code file in both projects.\n\nA detailed example of this can be found in the Unit Tests projects for the BinaryFormatter. They are using both techniques there.\n\n- [Unit Test project](Tests/HelperTests) for the Helper library\n- [Unit Test project](Tests/SerializationTests) for nanoFramework library\n\n## Feedback and documentation\n\nFor documentation, providing feedback, issues and finding out how to contribute please refer to the [Home repo](https://github.com/nanoframework/Home).\n\nJoin our Discord community [here](https://discord.gg/gCyBu8T).\n\n## Credits\n\nThe list of contributors to this project can be found at [CONTRIBUTORS](https://github.com/nanoframework/Home/blob/main/CONTRIBUTORS.md).\n\n## License\n\nThe **nanoFramework** Class Libraries are licensed under the [MIT license](LICENSE.md).\n\n## Code of Conduct\n\nThis project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behaviour in our community.\nFor more information see the [.NET Foundation Code of Conduct](https://dotnetfoundation.org/code-of-conduct).\n\n## .NET Foundation\n\nThis project is supported by the [.NET Foundation](https://dotnetfoundation.org).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanoframework%2Fsystem.runtime.serialization","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnanoframework%2Fsystem.runtime.serialization","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnanoframework%2Fsystem.runtime.serialization/lists"}