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:
Using .NET CLI (Recommended)
Open your terminal and run:
dotnet add package ToonFormat
Using Package Manager Console
In Visual Studio, open Package Manager Console and run:
Install-Package ToonFormat
Using Visual Studio NuGet UI
- 1.Right-click on your project → Manage NuGet Packages
- 2.Search for "ToonFormat"
- 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:
{
"customers": [
{
"id": 1,
"name": "Tower Site A",
"email": "[email protected]",
"active": true
},
{
"id": 2,
"name": "Tower Site B",
"email": "[email protected]",
"active": false
}
]
}customers[2]{id,name,email,active}:
1,Tower Site A,[email protected],true
2,Tower Site B,[email protected],falseC# 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,42OpenAI 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
| Recommended | Avoid |
|---|---|
| Use structured arrays for lists of objects | Using TOON for public-facing APIs |
| Validate TOON data before sending to AI APIs | Manually building TOON strings |
| Cache serialized TOON for repeated use | Ignoring parsing errors |
| Use async methods for better performance | Forgetting 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:
- 📖What is TOON Format?
Learn the basics of TOON
- ⚡TOON vs JSON Comparison
See detailed token savings analysis
- 🤖TOON for LLM Prompts
Best practices for AI applications
- 💻TOON C# GitHub Repository
Source code and more examples
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
- •TOON .NET Library on GitHub
Official C# implementation with examples
- •System.Text.Json Documentation
Official Microsoft JSON serialization documentation
- •OpenAI API Documentation
Official OpenAI API reference
- •NuGet Package Manager
Official .NET package repository
- •OpenAI Tokenizer Tool
Test and compare TOON vs JSON token counts
- •Azure OpenAI Service Documentation
Official Azure OpenAI integration guide
- •TOON vs JSON Comparison
Detailed performance comparison
- •TOON Format Specification
Complete syntax and structure guide