How to Use TOON Format in C# - Complete Tutorial

Step-by-step guide with code examples to implement TOON in your .NET applications

Published: January 2025 • 12 min read • For C# Developers

TOON format reduces token usage by approximately 50% compared to JSON when working with OpenAI, Claude, or other LLM APIs. This guide shows you how to implement TOON in C# applications.

Contents:

  • Installation via NuGet
  • Parsing and serializing TOON data
  • JSON to TOON conversion
  • OpenAI and Azure OpenAI integration
  • Error handling

Requirements

  • .NET 6.0 or higher
  • NuGet Package Manager
  • Optional: OpenAI or Azure OpenAI API key for integration examples

Step 1: Installation

Let's install the TOON library for C#. You have three options:

1.

Using .NET CLI (Recommended)

Open your terminal and run:

dotnet add package ToonFormat
2.

Using Package Manager Console

In Visual Studio, open Package Manager Console and run:

Install-Package ToonFormat
3.

Using Visual Studio NuGet UI

  1. 1.Right-click on your project → Manage NuGet Packages
  2. 2.Search for "ToonFormat"
  3. 3.Click Install

The package includes parser, serializer, JSON converter, and OpenAI integration helpers.

Step 2: Your First TOON Program 🚀

Let's start with a simple "Hello World" example. Here's how to parse and generate TOON data:

📝 Example: Parsing TOON Data

using ToonFormat;

// Sample TOON data
string toonData = @"
name: "Sarah Wilson"
age: 32
email: "[email protected]"
active: true
";

// Parse TOON to C# object
var parser = new ToonParser();
var data = parser.Parse<Person>(toonData);

Console.WriteLine($"Name: {data.Name}");
Console.WriteLine($"Age: {data.Age}");
Console.WriteLine($"Email: {data.Email}");
Console.WriteLine($"Active: {data.Active}");

// Define your C# class
public class Person
{
    public string Name { get; set; }
    public int Age { get; set; }
    public string Email { get; set; }
    public bool Active { get; set; }
}

Output:

Name: Sarah Wilson
Age: 32
Email: [email protected]
Active: True

Generating TOON Data

using ToonFormat;

// Create a C# object
var person = new Person
{
    Name = "Mike Chen",
    Age = 28,
    Email = "[email protected]",
    Active = true
};

// Convert to TOON format
var serializer = new ToonSerializer();
string toonOutput = serializer.Serialize(person);

Console.WriteLine(toonOutput);

Output:

name: "Mike Chen"
age: 28
email: "[email protected]"
active: true

JSON to TOON Conversion

Already have JSON data? No problem! Here's how to convert it to TOON:

INPUT (JSON)
{
  "customers": [
    {
      "id": 1,
      "name": "Tower Site A",
      "email": "[email protected]",
      "active": true
    },
    {
      "id": 2,
      "name": "Tower Site B",
      "email": "[email protected]",
      "active": false
    }
  ]
}
OUTPUT (TOON)
customers[2]{id,name,email,active}:
  1,Tower Site A,[email protected],true
  2,Tower Site B,[email protected],false

C# Code to Convert:

using ToonFormat;
using Newtonsoft.Json;

// Your JSON string
string jsonData = @"{
  ""customers"": [
    {""id"": 1, ""name"": ""Tower Site A"", ""email"": ""[email protected]"", ""active"": true},
    {""id"": 2, ""name"": ""Tower Site B"", ""email"": ""[email protected]"", ""active"": false}
  ]
}";

// Convert JSON to TOON
var converter = new JsonToToonConverter();
string toonData = converter.Convert(jsonData);

Console.WriteLine(toonData);

// Count tokens saved
int jsonTokens = TokenCounter.Count(jsonData);
int toonTokens = TokenCounter.Count(toonData);
int saved = jsonTokens - toonTokens;
double percentage = (saved / (double)jsonTokens) * 100;

Console.WriteLine($"\nJSON tokens: {jsonTokens}");
Console.WriteLine($"TOON tokens: {toonTokens}");
Console.WriteLine($"Saved: {saved} tokens ({percentage:F1}%)");

Typical token reduction: 48-52%

That means your OpenAI API costs are cut in half.

Working with Collections

TOON really shines when working with lists and arrays. Here's how to handle collections in C#:

Example: Parsing Array Data

using ToonFormat;

string toonData = @"
products[3]{id,name,price,stock}:
  101,Laptop,999.99,15
  102,Mouse,29.99,50
  103,Keyboard,79.99,30
";

// Parse to List<Product>
var parser = new ToonParser();
var result = parser.Parse<ProductList>(toonData);

foreach (var product in result.Products)
{
    Console.WriteLine($"{product.Name}: ${product.Price} ({product.Stock} in stock)");
}

public class ProductList
{
    public List<Product> Products { get; set; }
}

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public int Stock { get; set; }
}

Example: Generating Array Data

using ToonFormat;

// Create a list of products
var products = new List<Product>
{
    new Product { Id = 1, Name = "Phone", Price = 699.99m, Stock = 25 },
    new Product { Id = 2, Name = "Tablet", Price = 399.99m, Stock = 18 },
    new Product { Id = 3, Name = "Watch", Price = 299.99m, Stock = 42 }
};

// Serialize to TOON
var serializer = new ToonSerializer();
var options = new ToonSerializerOptions
{
    UseStructuredArrays = true // Enable TOON's efficient array format
};

string toonOutput = serializer.Serialize(products, options);
Console.WriteLine(toonOutput);

// Output:
// [3]{id,name,price,stock}:
//   1,Phone,699.99,25
//   2,Tablet,399.99,18
//   3,Watch,299.99,42

OpenAI API Integration

Integrating TOON with the OpenAI API to reduce token usage:

Cost Savings

By using TOON instead of JSON in your prompts, you'll cut token usage by ~50%, which means your API costs are cut in half too.

Complete OpenAI Example:

using OpenAI_API;
using ToonFormat;

public class OpenAIToonExample
{
    private readonly OpenAIAPI api;
    private readonly ToonSerializer serializer;

    public OpenAIToonExample(string apiKey)
    {
        api = new OpenAIAPI(apiKey);
        serializer = new ToonSerializer();
    }

    public async Task<string> AnalyzeCustomersAsync(List<Customer> customers)
    {
        // Convert customers to TOON format (saves 50% tokens!)
        string customerData = serializer.Serialize(customers, new ToonSerializerOptions
        {
            UseStructuredArrays = true
        });

        // Create prompt with TOON data
        string prompt = $@"Analyze these customers and provide insights.

Customer Data (TOON format):
{customerData}

Provide:
1. Total active vs inactive customers
2. Most common email domains
3. Any patterns you notice";

        // Send to OpenAI
        var result = await api.Completions.CreateCompletionAsync(
            prompt,
            model: "gpt-4",
            max_tokens: 500
        );

        return result.Completions[0].Text;
    }
}

// Usage
var customers = new List<Customer>
{
    new Customer { Id = 1, Name = "Metro Wireless", Email = "[email protected]", Active = true },
    new Customer { Id = 2, Name = "5G Networks Inc", Email = "[email protected]", Active = true },
    new Customer { Id = 3, Name = "FiberNet Solutions", Email = "[email protected]", Active = false }
};

var example = new OpenAIToonExample("your-api-key");
string analysis = await example.AnalyzeCustomersAsync(customers);
Console.WriteLine(analysis);

Azure OpenAI Example:

using Azure.AI.OpenAI;
using Azure;
using ToonFormat;

public class AzureOpenAIToonExample
{
    private readonly OpenAIClient client;
    private readonly ToonSerializer serializer;

    public AzureOpenAIToonExample(string endpoint, string apiKey)
    {
        client = new OpenAIClient(
            new Uri(endpoint),
            new AzureKeyCredential(apiKey)
        );
        serializer = new ToonSerializer();
    }

    public async Task<string> ProcessDataAsync(object data)
    {
        // Convert to TOON
        string toonData = serializer.Serialize(data, new ToonSerializerOptions
        {
            UseStructuredArrays = true,
            IndentSize = 2
        });

        var chatCompletionsOptions = new ChatCompletionsOptions
        {
            Messages =
            {
                new ChatMessage(ChatRole.System, "You understand TOON format data efficiently."),
                new ChatMessage(ChatRole.User, $"Process this data:\n{toonData}")
            },
            MaxTokens = 800,
            Temperature = 0.7f
        };

        var response = await client.GetChatCompletionsAsync(
            "gpt-4",
            chatCompletionsOptions
        );

        return response.Value.Choices[0].Message.Content;
    }
}

Best Practices

RecommendedAvoid
Use structured arrays for lists of objectsUsing TOON for public-facing APIs
Validate TOON data before sending to AI APIsManually building TOON strings
Cache serialized TOON for repeated useIgnoring parsing errors
Use async methods for better performanceForgetting to dispose streams and readers

Performance Tips

  • 1.
    Reuse serializer instances: Create once, use multiple times
    private static readonly ToonSerializer _serializer = new();
  • 2.
    Use streaming for large files: Don't load everything into memory
    await parser.ParseStreamAsync<T>(fileStream);
  • 3.
    Enable compression for network transfer: TOON compresses very well

Error Handling 🛡️

Always handle errors gracefully. Here's a production-ready example:

using ToonFormat;
using ToonFormat.Exceptions;

public class SafeToonHandler
{
    private readonly ToonParser parser;
    private readonly ILogger<SafeToonHandler> logger;

    public SafeToonHandler(ILogger<SafeToonHandler> logger)
    {
        this.parser = new ToonParser();
        this.logger = logger;
    }

    public async Task<T?> ParseSafelyAsync<T>(string toonData) where T : class
    {
        try
        {
            return await Task.Run(() => parser.Parse<T>(toonData));
        }
        catch (ToonSyntaxException ex)
        {
            logger.LogError(ex, "TOON syntax error at line {Line}: {Message}", 
                ex.LineNumber, ex.Message);
            return null;
        }
        catch (ToonValidationException ex)
        {
            logger.LogError(ex, "TOON validation failed: {Message}", ex.Message);
            return null;
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Unexpected error parsing TOON data");
            return null;
        }
    }

    public string SerializeSafely<T>(T obj)
    {
        try
        {
            var serializer = new ToonSerializer();
            return serializer.Serialize(obj);
        }
        catch (Exception ex)
        {
            logger.LogError(ex, "Failed to serialize object to TOON");
            throw new InvalidOperationException("Serialization failed", ex);
        }
    }
}

Complete Working Example

Here's a full console application that puts it all together:

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using ToonFormat;
using OpenAI_API;

namespace ToonDemo
{
    class Program
    {
        static async Task Main(string[] args)
        {
            Console.WriteLine("TOON Format C# Demo\n");

            // 1. Create sample data
            var customers = new List<Customer>
            {
                new Customer { Id = 1, Name = "Metro Wireless", Email = "[email protected]", Active = true },
                new Customer { Id = 2, Name = "5G Networks Inc", Email = "[email protected]", Active = true },
                new Customer { Id = 3, Name = "FiberNet Solutions", Email = "[email protected]", Active = false }
            };

            // 2. Serialize to TOON
            var serializer = new ToonSerializer();
            string toonData = serializer.Serialize(customers, new ToonSerializerOptions
            {
                UseStructuredArrays = true
            });

            Console.WriteLine("📊 Customer Data in TOON format:");
            Console.WriteLine(toonData);
            Console.WriteLine();

            // 3. Compare token counts
            string jsonData = System.Text.Json.JsonSerializer.Serialize(customers);
            int jsonTokens = TokenCounter.Count(jsonData);
            int toonTokens = TokenCounter.Count(toonData);
            
            Console.WriteLine($"📈 Token Comparison:");
            Console.WriteLine($"   JSON: {jsonTokens} tokens");
            Console.WriteLine($"   TOON: {toonTokens} tokens");
            Console.WriteLine($"   Saved: {jsonTokens - toonTokens} tokens ({(jsonTokens - toonTokens) * 100.0 / jsonTokens:F1}%)");
            Console.WriteLine();

            // 4. Send to OpenAI (if API key is set)
            if (!string.IsNullOrEmpty(Environment.GetEnvironmentVariable("OPENAI_API_KEY")))
            {
                Console.WriteLine("🤖 Sending to OpenAI...");
                var api = new OpenAIAPI(Environment.GetEnvironmentVariable("OPENAI_API_KEY"));
                
                var result = await api.Completions.CreateCompletionAsync(
                    $"Analyze these customers:\n{toonData}",
                    max_tokens: 200
                );

                Console.WriteLine("💬 AI Response:");
                Console.WriteLine(result.Completions[0].Text);
            }
            else
            {
                Console.WriteLine("ℹ️ Set OPENAI_API_KEY environment variable to test OpenAI integration");
            }

            Console.WriteLine("\n✅ Demo complete!");
        }
    }

    public class Customer
    {
        public int Id { get; set; }
        public string Name { get; set; }
        public string Email { get; set; }
        public bool Active { get; set; }
    }
}

Helpful Tools 🛠️

These free online tools will help you work with TOON:

Related Resources

Continue Learning:

Summary

This guide covered TOON format implementation in C#: installation via NuGet, parsing and serialization, JSON conversion, array handling, OpenAI/Azure OpenAI integration, and error handling.

Additional Resources