---
code: csharp_sdk_installation
name: "C#"
wikiToken: HF7Dwv171ibMQtkmV1UcOhownPc
parentWikiToken: O3YxwgHGiiEnvYkHCcIcX51inkf
updateTime: 1756884342000
sourceUrl: https://docs-v2.thinkingdata.cn/?version=v5.0&lan=zh-CN&code=csharp_sdk_installation
---
# C#

::: tip 提示

 在接入前, 请先阅读接入前准备。

 :::

**最新版本为**：v2.0.3

**更新时间为**：2025-09-03

**资源下载****：**源代码

::: warning 注意

当前文档适用于 v2.0.0 及以后的版本，历史版本请参考 C# SDK 接入指南（V1）

::: 

### 一、集成SDK

#### 方式一：NuGet 集成

1. 在 NuGet 中搜索 ThinkingDataAnalytics 库，安装到你的项目中
1. ThinkingDataAnalytics 库同时会自动安装 Newtonsoft.Json 库
#### 方式二：集成 dll 文件

1. 下载 SDK 源码
1. 打开源码中的解决方案，手动编译出 SDK 的 dll 文件
1. 将 ThinkingDataAnalytics SDK 的 dll 文件引入到你的工程
1. SDK 依赖 Newtonsoft.Json 框架用作json解析，请手动添加 Newtonsoft.Json 库到你的项目。
#### 安装Logbus

我们推荐使用SDK+LogBus的形式，完成服务端数据的采集上报.您可以参考以下文档完成Logbus的安装:LogBus使用指南

### 二、初始化

以下是SDK初始化的示例代码:

```
using ThinkingData.Analytics

TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"));
```

`LOG_DIRECTORY`为写入本地的文件夹地址。您只需将 LogBus 的监听文件夹地址设置为此处的地址，即可使用 LogBus 进行数据的监听上传。

### 三、常用功能

为了保证访客 ID 与账号 ID 能够顺利进行绑定，如果您的游戏中会用到访客 ID 与账号 ID，我们极力建议您同时上传这两个 ID，否则将会出现账号无法匹配的情况，导致用户重复计算，具体的 ID 绑定规则可参考用户识别规则一章。

#### 3.1 发送事件

您可以调用`track`来上传事件，建议您根据先前梳理的文档来设置事件的属性以及发送信息的条件，以下是发送事件的示例代码:

```
Dictionary<string, object> properties = new Dictionary<string, object>();
// 设置用户的ip地址，TE系统会根据IP地址解析用户的地理位置信息
properties.Add("#ip", "123.123.123.123");
//设置事件属性
properties.Add("channel", "TE");//字符串
properties.Add("age", 1);//数字
properties.Add("is_success", true);//布尔value
List<string> list = new List<string>();
list.Add("value");
properties.Add("array", list);//数组
//对象
Dictionary<string, Object> objectTest = new Dictionary<string, object>();
objectTest.Add("key", "vale");
properties.Add("object", objectTest);
//对象组
List<Object> object_arr = new List<Object>();
object_arr.Add(objectTest);
properties.Add("object_arr", object_arr);

//上报带有自定义属性的事件，accountId 和 distinctId至少一个不为空
te.Track("accountId", "distinctId", "Payment", properties);
```

- 事件的名称是字符串类型，只能以字母开头，可包含数字，字母和下划线 "_"，长度最大为 50 个字符。
- Key 为该属性的名称，为字符串类型，规定只能以字母开头，包含数字，字母和下划线 "_"，长度最大为 50 个字符，对字母大小写不敏感,TE会统一转化为小写字母
- Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组
<!-- unsupported block: 34 -->

**用户属性的要求与事件属性保持一致**

#### 3.2 设置用户属性

对于一般的用户属性，您可以调用 `UserSet` 来进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性，类型与传入属性的类型一致，此处以设置用户名为例：

```
//此时username为TA
Dictionary<string, object> properties= new Dictionary<string, object>();
properties.Add("user_name","TA");
te.UserSet("accountId","distinctId", properties);
//此时userName为TE
Dictionary<string, object> newProperties= new Dictionary<string, object>();
newProperties.Add("user_name","TE");
//设置用户属性，accountId 和 distinctId 必须至少设置其中一个
te.UserSet("accountId","distinctId", newProperties);
```

#### 3.3 数据上报

使用 TDLoggerConsumer 时，采集到的事件会先编码成 json 字符串，然后添加到缓存字符串中。当缓存字符串长度超出设置的长度时才会将数据写入磁盘。默认最大长度为 8192。

在某些业务场景下，如果您期望数据立即上报到TE服务器，可以通过调用`flush()`接口完成。需要注意，频繁调用`flush()`会导致服务性能下降。

```
te.Flush();
```

#### 3.4 关闭SDK

```
te.Close();
```

<!-- unsupported block: 34 -->

关闭并退出 SDK，请在关闭服务器前调用本接口，以避免缓存内的数据丢失

### 四、最佳实践

以下示例代码包含以上所有操作，我们推荐按照如下步骤使用:

```
using ThinkingData.Analytics
//初始化SDK
TDAnalytics te = new TDAnalytics(new TDLoggerConsumer("LOG_DIRECTORY"));

Dictionary<string, object> properties = new Dictionary<string, object>();
// 设置用户的ip地址，TE系统会根据IP地址解析用户的地理位置信息
properties.Add("#ip", "123.123.123.123");
//设置事件属性
properties.Add("channel", "TE");//字符串
properties.Add("age", 1);//数字
properties.Add("is_success", true);//布尔value
List<string> list = new List<string>();
list.Add("value");
properties.Add("array", list);//数组
Dictionary<string, Object> objectTest = new Dictionary<string, object>();
objectTest.Add("key", "vale");
properties.Add("object", objectTest);
//对象组
List<Object> object_arr = new List<Object>();
object_arr.Add(objectTest);
properties.Add("object_arr", object_arr);

//上报带有自定义属性的事件，accountId 和 distinctId至少一个不为空
te.Track("accountId", "distinctId", "Payment", properties);

//此时username为TA
Dictionary<string, object> userProperties = new Dictionary<string, object>();
userProperties.Add("user_name", "TA");
te.UserSet("accountId", "distinctId", userProperties);

//调用flush接口数据会立即写入文件，生产环境注意避免频繁调用flush引发IO或网络开销问题
te.Flush();
```
