StructStreamKit.Web 0.9.23

Struct Streaming Kit

A comprehensive .NET library designed to simplify serialization and deserialization of objects to and from multiple well-known formats. It provides a consistent API across different serialization technologies while optimizing for performance and flexibility.

Overview

Struct Streaming Kit offers a unified approach to data serialization with support for both value types (structs) and reference types (classes). The library handles individual objects as well as collections, making it versatile for a wide range of use cases from data storage to API communication.

Supported Formats

• JSON: Uses System.Text.Json for high-performance JSON serialization
• Protocol Buffers: Implements Google's Protocol Buffers binary format using protobuf-net
• XML: XML serialization using .NET's built-in capabilities
• MessagePack: Compact binary serialization format optimized for performance

Key Features

• Unified API across all supported formats
• Support for both structs and classes
• Collections support (List<T>) for both structs and classes
• Schema generation for supported formats
• Seamless ASP.NET Core integration via output formatters
• Content negotiation based on Accept headers for responses and Content-Type for requests
• Full support for input and output formatting in ASP.NET Core applications
• Performance optimized serialization and deserialization

Target Frameworks

• Core Library: Targets .NET7
• Web Extensions: Built for ASP.NET Core applications
• Compatible .NET 7, .NET 8, .NET 9

Installation

NuGet Package Manager (coming soon)

dotnet add package StructStreamKit
dotnet add package StructStreamKit.Web # For ASP.NET Core applications

Manual Installation

Clone the repository and reference the projects directly:

git clone https://github.com/Elixeum/lab-struct-stream-kit.git

Getting Started

Basic Usage

// Create a serializer instance
var jsonSerializer = SerializerFactory.CreateJsonSerializer();
var protoSerializer = SerializerFactory.CreateProtoSerializer();
var xmlSerializer = SerializerFactory.CreateXmlSerializer();
var messagePackSerializer = SerializerFactory.CreateMessagePackSerializer();

// Serialize an object
var person = new Person { 
    FirstName = "John", 
    LastName = "Doe", 
    Age = 30 
};

// Serialize to the desired format
(byte[] bytes, string schema) = jsonSerializer.SerializeStruct(person);

// Deserialize back to object
Person deserializedPerson = jsonSerializer.DeserializeStruct<Person>(bytes);

Working with Collections

var people = new List<Person> {
    new Person { FirstName = "John", LastName = "Doe", Age = 30 },
    new Person { FirstName = "Jane", LastName = "Smith", Age = 28 }
};

// Serialize list
(byte[] bytes, string schema) = jsonSerializer.SerializeStructList(people);

// Deserialize back to list
List<Person> deserializedList = jsonSerializer.DeserializeStructList<Person>(bytes);

Examples

Console Application

The Terminal example demonstrates serializing and deserializing both individual objects and collections in all supported formats, with comparison of serialized data size and performance.

# Build and run the Console example
./build_run.sh    # For Unix/Linux/macOS
build_run.ps1     # For Windows

The example:

• Creates sample Person objects and collections
• Serializes them to all supported formats
• Reports on serialized data size
• Deserializes back to objects
• Validates data integrity by comparing with original objects

ASP.NET Core Web API

The WebAPI example demonstrates how to integrate StructStreamKit into an ASP.NET Core application with automatic content negotiation based on Accept headers.

Setup in Program.cs

// Register StructStreamKit formatters in your ASP.NET Core application
builder.Services.AddControllers()
    .AddStructStreamFormattersAndInputFormatters(); // Adds both input and output formatters

Usage in Controllers

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    [HttpGet("{id}")]
    public IActionResult GetBook(int id)
    {
        var book = new Book { 
            Title = "The Great Gatsby", 
            YearPublished = 1925, 
            ISBN = "9780743273565", 
            Price = 10.99m 
        };
        
        // Return the object directly - the formatter will handle serialization
        // based on the client's Accept header
        return Ok(book);
    }
    
    [HttpGet]
    public IActionResult GetBooks()
    {
        var books = new List<Book> {
            new Book { Title = "The Great Gatsby", YearPublished = 1925, ISBN = "9780743273565", Price = 10.99m },
            new Book { Title = "To Kill a Mockingbird", YearPublished = 1960, ISBN = "9780061120084", Price = 12.99m }
        };
        
        // Collections are also supported
        return Ok(books);
    }
}

Client Usage

Receiving Data

Clients can request specific response formats using the HTTP Accept header:

GET /api/books HTTP/1.1
Host: localhost:5000
Accept: application/json

GET /api/books HTTP/1.1
Host: localhost:5000
Accept: application/protobuf

Sending Data

Clients can send data in specific formats using the Content-Type header:

POST /api/books HTTP/1.1
Host: localhost:5000
Content-Type: application/json
Accept: application/json

{
  "title": "The Great Gatsby",
  "author": {
    "id": "12345678-1234-1234-1234-123456789012",
    "name": "F. Scott Fitzgerald",
    "biography": "American novelist",
    "dateOfBirth": "1896-09-24"
  },
  "yearPublished": 1925,
  "genre": "Fiction",
  "isbn": "9780743273565",
  "pages": 180,
  "publisher": "Scribner",
  "language": "English",
  "price": 10.99
}

POST /api/books HTTP/1.1
Host: localhost:5000
Content-Type: application/protobuf
Accept: application/protobuf

[Binary Protocol Buffer data]

Performance Considerations

• JSON: Best for human-readable data and web APIs
• Protocol Buffers: Most efficient for binary serialization with schema evolution support
• MessagePack: Best for high-speed, compact serialization when schema evolution is not required
• XML: Best for interoperability with older systems and when human readability is important