Refactor C# client documentation

[bernardlim]

Summary

This PR improves the C# Driver documentation by combining content from the current docs and the legacy wiki, fixing errors, and adding missing information to provide developers with complete and accurate guidance.

Key improvements:

Fixed Issues

• Corrected namespace references from ClickHouse.Client.ADO to ClickHouse.Driver.ADO throughout all examples
• Fixed connection string parameter descriptions (port defaults)

Enhanced Documentation

Connection & Pooling:

• Expanded "Connection Lifetime & Pooling" section with comprehensive details about HttpClient behavior
• Added explanation of 1:1 vs multiplexed TCP connections
• Included recommendations for connection lifetime management
• Documented IHttpClientFactory usage for DI scenarios

Connection String Parameters:

• Enhanced table with accurate default values
• Added detailed session behavior notes
• Included practical connection string example

Data Types:

• Added complete .NET type mappings for all ClickHouse types (e.g., Int8 → sbyte, UInt64 → ulong)
• Added missing types: Decimal128 → decimal, Map(K, V) → Dictionary<K, V>
• Reorganized numeric types into logical subcategories (Signed/Unsigned Integers, Floating Point, Decimal)

SQL Parameters:

• Expanded section with proper parameter formatting syntax: {<name>:<data type>}
• Added multiple practical examples (Arrays, Tuples, nested Tuples)
• Documented HTTP query parameter limitations

Bulk Insert:

• Added InitAsync() method call (from legacy wiki)
• Included comprehensive requirements list
• Enhanced notes about TPL parallel processing, ColumnNames property, and session incompatibility
• Improved example with realistic batch sizes (100,000 rows, 1M total)

DateTime Handling:

• Expanded with complete timezone behavior explanation
• Added ToLocalTime() method documentation
• Documented legacy client timezone behavior and UseServerTimezone flag usage

Migrated from Legacy Wiki

• Connection lifetime and pooling behavior
• Session management details
• SQL parameter formatting syntax and examples
• Bulk insert requirements and constraints
• Comprehensive DateTime handling rules

Related Issue: N/A (documentation improvement)

Checklist

• Updated documentation content only (no URL changes required)
• Fixed all namespace inconsistencies (ClickHouse.Client → ClickHouse.Driver)
• Added missing data type mappings for developer reference
• Migrated relevant content from legacy wiki
• Enhanced connection pooling documentation
• Improved SQL parameters section with examples
• Maintained existing anchor IDs to preserve external links

Testing

• Verified YAML front matter parses correctly
• Reviewed all code examples for syntax correctness and namespace consistency
• Confirmed data type mappings align with ClickHouse.Driver source
• Cross-referenced with legacy wiki to ensure no information loss
• Validated all parameter formatting examples against ClickHouse syntax

Migration Path

This update provides a clear migration path for users moving from the old ClickHouse.Client package:

1. Simple namespace changes (ClickHouse.Client → ClickHouse.Driver)
2. Behavioral changes clearly documented (e.g., Compression=true by default)
3. New features documented (UseServerTimezone, UseCustomDecimals)

---

Documentation Completeness: This PR combines the best of the current documentation and the legacy wiki, ensuring developers have access to comprehensive, accurate, and well-organized information about the ClickHouse C# Driver.

Thank you.

[vercel]

@bernardlim is attempting to deploy a commit to the ClickHouse Team on Vercel.

A member of the Team first needs to authorize it.