Skip to content

Commit 9717f53

Browse files
ti-chi-botti-chi-bot
authored
Add C# / .NET example (#21206) (#21274)
1 parent b95538b commit 9717f53

File tree

3 files changed

+127
-0
lines changed

3 files changed

+127
-0
lines changed

‎TOC-tidb-cloud.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,8 @@
5656
- Ruby
5757
- [mysql2](/develop/dev-guide-sample-application-ruby-mysql2.md)
5858
- [Rails](/develop/dev-guide-sample-application-ruby-rails.md)
59+
- C#
60+
- [C#](/develop/dev-guide-sample-application-cs.md)
5961
- [WordPress](/tidb-cloud/dev-guide-wordpress.md)
6062
- Serverless Driver (Beta)
6163
- [TiDB Cloud Serverless Driver](/tidb-cloud/serverless-driver.md)

‎TOC.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@
4848
- Ruby
4949
- [mysql2](/develop/dev-guide-sample-application-ruby-mysql2.md)
5050
- [Rails](/develop/dev-guide-sample-application-ruby-rails.md)
51+
- C#
52+
- [C#](/develop/dev-guide-sample-application-cs.md)
5153
- Connect to TiDB
5254
- GUI Database Tools
5355
- [JetBrains DataGrip](/develop/dev-guide-gui-datagrip.md)

‎develop/dev-guide-sample-application-cs.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: Connect to TiDB with C#
3+
summary: Learn how to connect to TiDB using C#. This tutorial provides sample C# code snippets for interacting with TiDB.
4+
---
5+
6+
# Connect to TiDB with C\#
7+
8+
C# (pronounced "C-Sharp") is one of the programming languages in the .NET family, developed by Microsoft. Other .NET languages include VB.NET and F#. In this tutorial, you will use C# along with MySQL Connector/NET to connect a C# application to TiDB using the MySQL protocol. This works because TiDB is highly [compatible with MySQL](/mysql-compatibility.md).
9+
10+
While .NET is commonly used on Windows, it is also available for macOS and Linux. Across all platforms, the commands and code are largely the same, with only minor differences in prompts and file paths.
11+
12+
## Prerequisites
13+
14+
- Download the [.NET 9.0 SDK](https://dotnet.microsoft.com/en-us/download).
15+
- This tutorial uses the `dotnet` command-line tool. Alternatively, you can use the Visual Studio Code IDE to work with C# code.
16+
- To complete this tutorial, you need access to a TiDB instance. You can use a [TiDB Cloud Serverless](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-serverless) or [TiDB Cloud Dedicated](https://docs.pingcap.com/tidbcloud/select-cluster-tier/#tidb-cloud-dedicated) cluster on TiDB Cloud, or a TiDB Self-Managed cluster, such as one started using `tiup playground`.
17+
18+
## Step 1. Set up a console project
19+
20+
Create a new project using the `console` template. This will generate a new directory named `tidb_cs`. Before running the following command, either navigate to the location where you want this directory to be created, or specify a full path.
21+
22+
```
23+
$ dotnet new console -o tidb_cs
24+
The template "Console App" was created successfully.
25+
26+
Processing post-creation actions...
27+
Restoring /home/dvaneeden/tidb_cs/tidb_cs.csproj:
28+
Restore succeeded.
29+
```
30+
31+
## Step 2. Add the MySql.Data package
32+
33+
The package manager for .NET is called NuGet. The NuGet package name for MySQL Connector/NET is [MySql.Data](https://www.nuget.org/packages/MySql.Data), which provides support for the MySQL protocol in .NET applications. If you do not specify a version, NuGet installs the latest stable version (for example, version 9.3.0).
34+
35+
```
36+
$ cd tidb_cs
37+
$ dotnet add package MySql.Data
38+
39+
Build succeeded in 1.0s
40+
info : X.509 certificate chain validation will use the system certificate bundle at '/etc/pki/ca-trust/extracted/pem/objsign-ca-bundle.pem'.
41+
info : X.509 certificate chain validation will use the fallback certificate bundle at '/usr/lib64/dotnet/sdk/9.0.106/trustedroots/timestampctl.pem'.
42+
info : Adding PackageReference for package 'MySql.Data' into project '/home/dvaneeden/tidb_cs/tidb_cs.csproj'.
43+
info : GET https://api.nuget.org/v3/registration5-gz-semver2/mysql.data/index.json
44+
info : OK https://api.nuget.org/v3/registration5-gz-semver2/mysql.data/index.json 133ms
45+
info : Restoring packages for /home/dvaneeden/tidb_cs/tidb_cs.csproj...
46+
info : GET https://api.nuget.org/v3/vulnerabilities/index.json
47+
info : OK https://api.nuget.org/v3/vulnerabilities/index.json 98ms
48+
info : GET https://api.nuget.org/v3-vulnerabilities/2025.06.18.05.40.02/vulnerability.base.json
49+
info : GET https://api.nuget.org/v3-vulnerabilities/2025.06.18.05.40.02/2025.06.19.11.40.05/vulnerability.update.json
50+
info : OK https://api.nuget.org/v3-vulnerabilities/2025.06.18.05.40.02/vulnerability.base.json 32ms
51+
info : OK https://api.nuget.org/v3-vulnerabilities/2025.06.18.05.40.02/2025.06.19.11.40.05/vulnerability.update.json 64ms
52+
info : Package 'MySql.Data' is compatible with all the specified frameworks in project '/home/dvaneeden/tidb_cs/tidb_cs.csproj'.
53+
info : PackageReference for package 'MySql.Data' version '9.3.0' added to file '/home/dvaneeden/tidb_cs/tidb_cs.csproj'.
54+
info : Generating MSBuild file /home/dvaneeden/tidb_cs/obj/tidb_cs.csproj.nuget.g.targets.
55+
info : Writing assets file to disk. Path: /home/dvaneeden/tidb_cs/obj/project.assets.json
56+
log : Restored /home/dvaneeden/tidb_cs/tidb_cs.csproj (in 551 ms).
57+
```
58+
59+
## Step 3. Update the code
60+
61+
Replace the "Hello World" example in `Program.cs` with the following code.
62+
63+
```cs
64+
using System;
65+
using MySql.Data.MySqlClient;
66+
public class Tutorial1
67+
{
68+
public static void Main()
69+
{
70+
// For production, always use strong, unique passwords.
71+
string connStr = "server=127.0.0.1;user=root;database=test;port=4000;AllowUserVariables=true";
72+
MySqlConnection conn = new MySqlConnection(connStr);
73+
try
74+
{
75+
Console.WriteLine("Connecting to TiDB...\n");
76+
conn.Open();
77+
}
78+
catch (Exception ex)
79+
{
80+
Console.WriteLine(ex.ToString());
81+
Environment.Exit(1);
82+
}
83+
84+
Console.WriteLine("Connected to: " + conn.ServerVersion);
85+
86+
MySqlCommand cmd = new MySqlCommand("SELECT TIDB_VERSION()", conn);
87+
88+
MySqlDataReader rdr = cmd.ExecuteReader();
89+
90+
rdr.Read();
91+
Console.WriteLine("\nVersion details:\n" + rdr[0]);
92+
rdr.Close();
93+
94+
conn.Close();
95+
Console.WriteLine("Done.");
96+
}
97+
}
98+
```
99+
100+
This connects to a TiDB instance on the specified IP and port. If you use TiDB Cloud, replace connection string parameters (such as hostname, port, user, and password) with the details provided in the [TiDB Cloud console](https://tidbcloud.com/).
101+
102+
The code connects to the database, prints its version, then executes a SQL query using [`TIDB_VERSION()`](/functions-and-operators/tidb-functions.md#tidb_version) to retrieve more detailed version information, and finally prints this result.
103+
104+
## Step 4. Run the program
105+
106+
```
107+
$ dotnet run
108+
Connecting to TiDB...
109+
110+
Connected to: 8.0.11-TiDB-v8.5.2
111+
112+
Version details:
113+
Release Version: v8.5.2
114+
Edition: Community
115+
Git Commit Hash: f43a13324440f92209e2a9f04c0bbe9cf763978d
116+
Git Branch: HEAD
117+
UTC Build Time: 2025-05-29 03:30:55
118+
GoVersion: go1.23.8
119+
Race Enabled: false
120+
Check Table Before Drop: false
121+
Store: tikv
122+
Done.
123+
```

0 commit comments

Comments
 (0)