Home

ConcordIO Documentation

Welcome to the ConcordIO documentation! This comprehensive guide will help you understand, install, and use ConcordIO's contract management toolchain for .NET.

💡 Tip: This documentation is also available on GitHub Wiki for easier browsing. The Wiki is automatically synced with the repository.

⚠️ Important: Development-Time Toolchain Only
ConcordIO is strictly a development and build-time dependency. It consists of:

• CLI tool for generating contract packages
• MSBuild tasks that run during compilation to generate code

ConcordIO does NOT:

• ❌ Get bundled into your application binaries
• ❌ Deploy to production environments
• ❌ Run at application runtime
• ❌ Leak into your production code

All code generation happens at build time, and only the generated output (client code, types) is compiled into your application—not ConcordIO itself.

📚 Table of Contents

Getting Started

• 🚀 Quick Start Guide - Get up and running in 5 minutes
• 📦 Installation - Detailed installation instructions
• 🎯 When to Use ConcordIO - Use cases and scenarios
• 🏗️ Core Concepts - Understanding contract packages, clients, and breaking changes

User Guides

• 🛠️ CLI Tool Guide - Complete reference for the concordio CLI
• 📄 AsyncAPI Client Package - MSBuild task for generating C# from AsyncAPI specs
• ⚡ AsyncAPI Server Package - MSBuild task for generating AsyncAPI specs from .NET types
• 📚 AsyncAPI Library - Shared AsyncAPI generation library

Tutorials

• 📝 Tutorial: Publishing Your First API Contract
• 🔄 Tutorial: Consuming a Contract Package
• 🚦 Tutorial: Setting Up CI/CD with Breaking Change Detection

Examples

• 💡 Example Projects - Complete working examples
  • REST API with OpenAPI
  • Messaging with AsyncAPI
  • gRPC Service with Protocol Buffers
  • Multi-Protocol Service

AI & Automation

• 🤖 AI Prompts - Ready-to-use prompts for AI assistants
  • Adding ConcordIO to Projects
  • Generating Contracts
  • Troubleshooting Issues
  • Code Reviews

Architecture & Design

• 🏗️ CLI Tool Architecture - Internal design of the CLI tool
• 🏗️ AsyncAPI Library Architecture - Core AsyncAPI generation design
• 🏗️ AsyncAPI Client Architecture - MSBuild task design for client generation
• 🏗️ AsyncAPI Server Architecture - MSBuild task design for spec generation

Troubleshooting

• ❓ FAQ - Frequently asked questions
• 🐛 Common Issues - Known problems and solutions
• ⚠️ Known Limitations - Current limitations and workarounds

Contributing

• 🤝 Contributing Guide - How to contribute to ConcordIO

🔗 Quick Links

• GitHub Repository
• Report Issues
• Release Notes

📖 Documentation Format

This documentation is organized to help you:

• Learn the basics quickly with getting started guides
• Reference specific commands and options when needed
• Solve problems with troubleshooting guides
• Extend your usage with advanced topics
• Automate with AI prompts and templates

Each guide includes:

• ✅ Prerequisites - What you need before starting
• 📝 Step-by-step instructions - Clear, actionable steps
• 💡 Examples - Real-world code samples
• ⚠️ Common pitfalls - What to watch out for
• 🔗 Related topics - Where to learn more

🆘 Getting Help

If you can't find what you're looking for:

1. Check the FAQ
2. Search existing GitHub Issues
3. Open a new issue with the documentation label

📄 License

This documentation is part of the ConcordIO project and is licensed under the Apache License 2.0.