Quick Start

Quick Start Guide

This guide will help you get started with FLEXON quickly. We'll cover basic usage, common patterns, and essential features.

Basic Usage

1. Simple Serialization

using FlexonCLI;

// Create a serializer
var serializer = new FlexonSerializer();

// Serialize an object
var data = new { Name = "John", Age = 30 };
byte[] binary = serializer.Serialize(data);

// Deserialize
var restored = serializer.Deserialize<dynamic>(binary);
Console.WriteLine($"{restored.Name} is {restored.Age} years old");

2. File Operations

// Save to file
await serializer.SerializeToFileAsync(data, "person.flexon");

// Load from file
var loaded = await serializer.DeserializeFromFileAsync<Person>("person.flexon");

3. Stream Processing

using var stream = new MemoryStream();

// Write to stream
await serializer.SerializeAsync(data, stream);

// Read from stream
stream.Position = 0;
var result = await serializer.DeserializeAsync<Person>(stream);

Common Patterns

1. Configuration Options

var options = new FlexonOptions
{
    EnableCompression = true,
    ValidationMode = ValidationMode.Strict,
    UsePooledBuffers = true,
    BufferSize = 8192
};

var serializer = new FlexonSerializer(options);

2. Type Registration

// Register custom type
FlexonConfiguration.RegisterType<GeoPoint>();

// Use in serialization
var location = new GeoPoint { Lat = 40.7128, Lon = -74.0060 };
byte[] binary = serializer.Serialize(location);

3. Schema Validation

var schema = @"{
    'type': 'object',
    'properties': {
        'name': { 'type': 'string' },
        'age': { 'type': 'integer', 'minimum': 0 }
    },
    'required': ['name', 'age']
}";

var options = new FlexonOptions
{
    EnableValidation = true,
    Schema = FlexonSchema.FromString(schema)
};

var serializer = new FlexonSerializer(options);

Essential Features

1. Compression

// Enable compression
var options = new FlexonOptions
{
    EnableCompression = true,
    CompressionLevel = System.IO.Compression.CompressionLevel.Optimal
};

var serializer = new FlexonSerializer(options);

// Serialize with compression
byte[] compressed = serializer.Serialize(largeObject);

2. Error Handling

try
{
    var result = serializer.Deserialize<Person>(invalidData);
}
catch (FlexonValidationException ex)
{
    Console.WriteLine($"Validation error: {ex.Message}");
    foreach (var error in ex.ValidationErrors)
    {
        Console.WriteLine($"- {error.Path}: {error.Message}");
    }
}
catch (FlexonSerializationException ex)
{
    Console.WriteLine($"Serialization error: {ex.Message}");
}

3. Performance Optimization

// Use buffer pooling
var options = new FlexonOptions
{
    UsePooledBuffers = true,
    BufferSize = 8192
};

// Use batch processing
using var writer = new FlexonWriter(stream, options);
foreach (var item in items)
{
    writer.WriteValue(item);
    await writer.FlushAsync();
}

CLI Usage

1. Basic Commands

# Convert JSON to FLEXON
flexon convert input.json output.flexon

# View FLEXON content
flexon view data.flexon

# Validate FLEXON file
flexon validate data.flexon schema.json

2. Batch Processing

# Convert multiple files
flexon convert-batch *.json --output-dir ./flexon

# Validate multiple files
flexon validate-batch *.flexon schema.json

3. Schema Operations

# Generate schema from FLEXON file
flexon generate-schema data.flexon schema.json

# Validate against schema
flexon validate data.flexon schema.json

Web API Integration

1. ASP.NET Core

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers()
        .AddFlexonFormatters();
}

[ApiController]
[Route("[controller]")]
public class DataController : ControllerBase
{
    [HttpPost]
    [Consumes("application/x-flexon")]
    [Produces("application/x-flexon")]
    public async Task<IActionResult> Post([FromBody] Data data)
    {
        // Process data
        return Ok(result);
    }
}

2. HTTP Client

using var client = new HttpClient();
client.DefaultRequestHeaders.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/x-flexon"));

var response = await client.PostAsync(
    "api/data",
    new FlexonContent(data));

Next Steps

1. Explore Advanced Examples
2. Read the API Reference
3. Learn about Performance Optimization
4. Understand the Binary Format

Tips and Best Practices

1. Memory Management

   • Use buffer pooling for better performance
   • Dispose of resources properly
   • Consider using value types for small objects

2. Performance

   • Enable compression for large data
   • Use batch processing for multiple items
   • Profile your application

3. Security

   • Always validate input data
   • Use schema validation
   • Handle errors appropriately

4. Development

   • Use source control
   • Write unit tests
   • Document your code

Common Issues

1. Performance

   • Large object serialization is slow
   • Memory usage is high
   • Network bottlenecks

2. Compatibility

   • Version mismatches
   • Schema validation failures
   • Type conversion errors

3. Integration

   • Framework conflicts
   • Configuration issues
   • Dependency problems

Getting Help

• Check the FAQ
• Search Stack Overflow
• File issues on GitHub