YuanXuan.TrackingSystem.SDK
1.0.0
There is a newer version of this package available.
See the version list below for details.
See the version list below for details.
dotnet add package YuanXuan.TrackingSystem.SDK --version 1.0.0
NuGet\Install-Package YuanXuan.TrackingSystem.SDK -Version 1.0.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="YuanXuan.TrackingSystem.SDK" Version="1.0.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="YuanXuan.TrackingSystem.SDK" Version="1.0.0" />
<PackageReference Include="YuanXuan.TrackingSystem.SDK" />
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add YuanXuan.TrackingSystem.SDK --version 1.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
#r "nuget: YuanXuan.TrackingSystem.SDK, 1.0.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package YuanXuan.TrackingSystem.SDK@1.0.0
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=YuanXuan.TrackingSystem.SDK&version=1.0.0
#tool nuget:?package=YuanXuan.TrackingSystem.SDK&version=1.0.0
The NuGet Team does not provide support for this client. Please contact its maintainers for support.
📦 TrackingSystem.SDK 使用文档
版本：v1.0.0
框架：netstandard2.1
作者：胡船辉
说明：TrackingSystem.SDK 是用于埋点日志与 API 日志自动收集、缓存、批量推送的客户端 SDK。
🚀 一、安装与配置
1. 安装方式
✅ NuGet 安装
dotnet add package TrackingSystem.SDK
✅ 或者手动引用
将 TrackingSystem.SDK.dll 引入你的 WebAPI / 控制台项目。
⚙️ 二、快速开始
1. 初始化客户端
using TrackingSystem.SDK;
var client = new TrackingSystemClient("SystemA", batchSize: 50);
TrackingSystemClient会自动从系统中心同步系统信息，并初始化日志推送通道。
| 参数 | 类型 | 说明 |
|---|---|---|
System_code |
string |
系统编码（必填） |
batchSize |
int |
每批推送条数，默认 20 |
flushInterval |
TimeSpan? |
自动推送间隔，默认 5 秒 |
errPushStorageInterval |
TimeSpan? |
推送失败数据的持久化保留时间，默认永久 |
IsMQDirectPush |
bool? |
是否MQ直推，仅PushApiLogAsync方法支持 |
🧩 三、功能说明
1. 获取系统信息
var sysInfo = await client.GetDimSystem();
返回系统注册信息，用于验证接入合法性。
2. 获取系统事件类型
var types = await client.GetDimEventTypes();
- 若缓存存在，默认返回缓存；
- 传入
IsRefresh: true强制调用 API 刷新。
3. 获取系统自定义标签
var tags = await client.GetDimCustomTags();
与事件类型逻辑相同，用于埋点分类。
4. 检查服务健康状态
bool isAlive = await client.GetHealthStatus();
若返回 false，表示系统未注册或服务不可用。
5. 推送埋点日志
await client.PushEventLogAsync(new EventlogAddDto
{
System_code = "SystemA",
EventType = "Click",
UserId = "U10001",
EventTime = DateTime.Now
});
SDK 会自动缓存、批量推送，支持：
- 达到阈值自动推送；
- 超过时间间隔自动推送；
- 程序退出前自动落盘与恢复。
6. 推送 API 日志
如果初始化时 IsMQDirectPush 为 true，则会直接将日志推送到 MQ。
await client.PushApiLogAsync(new ApiLogAddDto
{
Endpoint = "/api/test",
Method = "POST",
ResponseInfo = new ApiLog_ResponseInfo { StatusCode = 200 }
});
支持自动附加系统编码与推送策略，与埋点逻辑独立。
7. 上传文件
var file = await client.UploadFile(new UploadFileDto
{
FileName = "report.log",
FileStream = Stream流
});
返回 ApiLog_FileInfo：
{
"FileId": "650a1b2c...",//文件id
"FileName": "report.log",//文件名称
"FileExt":".log", //文件后缀
"FileLength":15320,//文件大小 单位KB
"BucketName": "TrackingSystem.Apiapi_log" //存储桶名称
}
🧠 四、生命周期与资源释放
TrackingSystemClient 实现了 IAsyncDisposable：
await using var client = new TrackingSystemClient("SystemA");
或手动调用：
await client.DisposeAsync();
SDK 会在释放时自动推送缓存中未发送的日志，并释放内部资源。
🧾 五、异常与重试机制
| 场景 | 行为 |
|---|---|
| API 调用失败 | 自动重试，重试后仍失败则持久化到本地文件 |
| 程序崩溃 | 通过进程事件自动捕获并落盘缓存 |
| 下次启动 | 自动扫描缓存文件并重试推送 |
📚 六、最佳实践
✅ 建议以 单例模式 注册：
builder.Services.AddSingleton(new TrackingSystemClient("SystemA"));
✅ 不建议频繁创建销毁客户端对象。
✅ 可在 WebAPI 全局过滤器或中间件中统一封装日志调用。
📄 七、命名空间
using TrackingSystem.SDK;
using TrackingSystem.SDK.Dto;
🧩 八、更新记录
| 版本 | 日期 | 内容 |
|---|---|---|
| 1.0.0 | 2025-11 | 初版发布，支持事件日志与 API 日志批量推送 |
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.1 is compatible. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
-
.NETStandard 2.1
- Newtonsoft.Json (>= 13.0.1)
- RabbitMQ.Client (>= 6.4.0)
- System.Threading.Channels (>= 5.0.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.