See "How to Install" to learn how to install this .NET package.
Introduction
A C# implementation of Concise Binary Object Representation, a general-purpose binary data format defined in RFC 7049. According to that RFC, CBOR's data model "is an extended version of the JSON data model", supporting many more types of data than JSON. "CBOR was inspired by MessagePack", but "is not intended as a version of or replacement for MessagePack."
This implementation was written by Peter O. and is released to the Public Domain under the CC0 Declaration.
This implementation also doubles as a reader and writer of JSON, and can convert data from JSON to CBOR and back.
Finally, this implementation supports arbitrary-precision binary and decimal floating-point numbers and rational numbers with arbitrary-precision components.
Source code is available in the project page.
How to Install
Starting with version 0.21.0, the C# implementation is available in the NuGet Package Gallery under the name PeterO.Cbor. To install this library as a NuGet package, enter Install-Package PeterO.Cbor
in the NuGet Package Manager Console.
Documentation
This library defines one class, called CBORObject, that allows you to read and write CBOR objects to and from data streams and byte arrays, and to convert JSON text to CBOR objects and back.
See the C# (.NET) API documentation.
The C# implementation is designed as a Portable Class Library.
Other Sites
Examples
Creating a map and converting that map to CBOR bytes and a JSON string:
<code>
var cbor = CBORObject.NewMap()
.Add("item", "any string")
.Add("number", 42)
.Add("map", CBORObject.NewMap().Add("number", 42))
.Add("array", CBORObject.NewArray().Add(999f).Add("xyz"))
.Add("bytes", new byte[] { 0, 1, 2 });
byte[] bytes = cbor.EncodeToBytes();
string json = cbor.ToJSONString();
Console.WriteLine(json);
Reading data from a file (C#). Note that all the examples for reading and writing to files assume that the platform supports file I/O; the portable class library doesn't make that assumption.
<code>
var cbor = CBORObject.DecodeFromBytes(File.ReadAllBytes("object.cbor"));
Another example of reading data from a file:
<code>
using (var stream = new FileStream("object.cbor", FileMode.Open)) {
var cbor = CBORObject.Read(stream);
if (stream.Position != stream.Length) {
} else {
}
}
If a byte array contains multiple CBOR objects, the byte array should be wrapped in a MemoryStream and the stream used to read the objects, as DecodeFromBytes assumes the array contains only one CBOR object. Here is an example.
<code>
using (var stream = new MemoryStream(byteArray)) {
var cbor = CBORObject.Read(stream);
}
Writing CBOR data to a file (C#):
<code>
using (var stream = new FileStream("object.cbor", FileMode.Create)) {
cbor.WriteTo(stream);
}
Writing multiple objects to a file, including arbitrary objects:
<code>
using (var stream = new FileStream("object.cbor", FileMode.Create)) {
CBORObject.Write(true, stream);
CBORObject.Write(422.5, stream);
CBORObject.Write("some string", stream);
CBORObject.Write(CBORObject.Undefined, stream);
CBORObject.NewArray().Add(42).WriteTo(stream);
}
Reading JSON from a file:
<code>
using (var stream = new FileStream("object.json", FileMode.Open)) {
var cbor = CBORObject.ReadJSON(stream);
}
Writing a CBOR object as JSON:
<code>
File.WriteAllText(
"object.json",
cbor.ToJSONString(),
new System.Text.Encoding.UTF8Encoding(false));
using (var stream = new FileStream("object2.json", FileMode.Create)) {
cbor.WriteJSONTo(stream);
}
using (var stream = new FileStream("object3.json", FileMode.Create)) {
CBORObject.WriteJSON("some string", stream);
}
using (var stream = new FileStream("object4.json", FileMode.Create)) {
CBORObject.WriteJSON(cbor, stream);
}
using (var stream = new FileStream("object5.json", FileMode.Create)) {
CBORObject.WriteJSON(true, stream);
}
using (var stream = new FileStream("object6.json", FileMode.Create)) {
CBORObject.WriteJSON(42, stream);
}
NOTE: All code samples in this section are released to the Public Domain, as explained in http://creativecommons.org/publicdomain/zero/1.0/.
Demo
Go to https://github.com/peteroupc/Calculator for source code to a demo of the CBOR library in the form of a calculator.
About
Written in 2013-2017 by Peter O.
Any copyright is dedicated to the Public Domain. http://creativecommons.org/publicdomain/zero/1.0/
If you like this, you should donate to Peter O. at: http://peteroupc.github.io/CBOR/
Clarifications
The following are some clarifications to RFC 7049.
- Section 2.4.2 doesn't specify what happens if a bignum's byte string has a length of 0. This implementation treats a positive bignum with length 0 as having a value of 0 and a negative bignum with length 0 as having a value of -1.
- Section 2.4.1 specifies the number of seconds since the start of 1970. It is based on the POSIX definition of "seconds since the Epoch", which the RFC cites as a normative reference. This definition does not count leap seconds. When this implementation supports date conversion, it won't count leap seconds, either. This implementation treats values of infinity and NaN as invalid.
- For tag 32, this implementation accepts strings that are valid Internationalized Resource Identifiers (IRIs) in addition to URIs. IRI are like URIs except that they also allow non-ASCII characters.
Release Notes
Version 3.0.2
Fixes unforeseen issue on loading the library
Version 3.0.0
Version 3.0.0
- Moved from .NET Portable to .NET Standard 1.0.
- Deprecated arbitrary-precision classes in PeterO namespace; use the classes from the "PeterO.Numbers" library and namespace instead. In particular, methods that used the former classes were deprecated and often replaced with versions that use the newer classes.
- Change JSON output behavior slightly, including preserving negative zero
- Hash code calculation was changed in this version
- Deprecated OutermostTag in favor of MostOuterTag in CBORObject
- Deprecated InnermostTag in favor of MostInnerTag in CBORObject
- Bug fixes
See History.md for release notes for older versions.