Volcengine.TLS.SDK.NetCore 1.0.1

火山引擎日志服务 .NET SDK

Volcengine TLS（日志服务）.NET Core SDK，支持 .NET 5.0 / 6.0 / 7.0 / 8.0 跨平台框架，提供日志采集、传输、上报等核心能力，帮助开发者快速集成火山引擎 TLS 服务。

版本历史

• 1.0.1（初始版本）：支持 PutLogs / PutLogsV2 核心接口以及 Producer 日志上传，适配 net5.0 / net6.0 / net7.0 / net8.0。

特性

• 多框架兼容：支持 net5.0、net6.0、net7.0、net8.0，适配 Windows / macOS / Linux 跨平台环境
• 核心功能完备：包含日志上报（PutLogs / PutLogsV2 / Producer）、重试机制、连接池管理等
• 高性能设计：异步发送、批量处理、自动重试，保障日志传输高效可靠
• 轻量无冗余：仅依赖必要第三方库，避免依赖冲突

安装

方式一：通过 .NET CLI 安装

dotnet add package Volcengine.TLS.SDK.NetCore --version 1.0.1

方式二：通过 NuGet 包管理器安装

1. 打开 Visual Studio / JetBrains Rider 的 NuGet 包管理器
2. 搜索 Volcengine.TLS.SDK.NetCore
3. 选择版本 1.0.1，点击「安装」

快速入门

1. 前置准备

服务开通
请确保您已开通要使用的火山引擎 TLS 服务，可前往火山引擎控制台开通。

获取安全凭证
Access Key（访问密钥）包含 Access Key ID (AK) 和 Secret Access Key (SK)。可在火山引擎控制台的「访问控制」-「访问密钥」中创建与管理。

环境检查
确保运行环境已安装对应版本的 .NET SDK (>= net5.0)。

配置说明

VolcengineConfig 核心参数
可通过 环境变量 获取（例如：VOLCENGINE_REGION、VOLCENGINE_ENDPOINT、VOLCENGINE_ACCESS_KEY_ID、VOLCENGINE_ACCESS_KEY_SECRET、VOLCENGINE_SECURITY_TOKEN、TOPIC_ID）。

2. 初始化上报日志示例（PutLogs）

using VolcengineTls.Request;
using VolcengineTls.Response;

namespace VolcengineTls.Examples
{
    public class PutLogsExample
    {
        public async Task RunAsync()
        {
            // 设置火山云权限配置
            var vcConfig = new VolcengineConfig(
                region: Environment.GetEnvironmentVariable("VOLCENGINE_REGION"),
                endpoint: Environment.GetEnvironmentVariable("VOLCENGINE_ENDPOINT"),
                accessKeyId: Environment.GetEnvironmentVariable("VOLCENGINE_ACCESS_KEY_ID"),
                accessKeySecret: Environment.GetEnvironmentVariable("VOLCENGINE_ACCESS_KEY_SECRET"),
                securityToken: Environment.GetEnvironmentVariable("VOLCENGINE_SECURITY_TOKEN")
            );

            // 实例化tls sdk client
            var client = new Client(vcConfig);

            // 构建日志数据
            var logGroupList = new Pb.LogGroupList();
            var logGroup = new Pb.LogGroup();

            // 单个logGroup不超过10000条
            var num = 100;
            while (num > 0)
            {
                var log = new Pb.Log
                {
                    Time = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
                };

                var logContents = new List<Pb.LogContent>
                {
                    new Pb.LogContent { Key = "k1", Value = $"value{num}" },
                    new Pb.LogContent { Key = "k2", Value = $"value{num}" }
                };

                log.Contents.Add(logContents);

                logGroup.Logs.Add(log);

                num--;
            }

            logGroupList.LogGroups.Add(logGroup);

            // 构建请求
            var putLogsRequest = new PutLogsRequest(
                logGroupList: logGroupList,
                topicId: Environment.GetEnvironmentVariable("TOPIC_ID")
            );

            PutLogsResponse putLogsResponse = await client.PutLogs(putLogsRequest);
        }
    }
}

3. 初始化上报日志示例（PutLogsV2）

using System;
using System.Collections.Generic;
using System.Threading.Tasks;
using VolcengineTls.Request;
using VolcengineTls.Response;

namespace VolcengineTls.Examples
{
    public class PutLogsV2Example
    {
        public async Task RunAsync()
        {
            // 设置火山云权限配置
            var vcConfig = new VolcengineConfig(
                region: Environment.GetEnvironmentVariable("VOLCENGINE_REGION"),
                endpoint: Environment.GetEnvironmentVariable("VOLCENGINE_ENDPOINT"),
                accessKeyId: Environment.GetEnvironmentVariable("VOLCENGINE_ACCESS_KEY_ID"),
                accessKeySecret: Environment.GetEnvironmentVariable("VOLCENGINE_ACCESS_KEY_SECRET"),
                securityToken: Environment.GetEnvironmentVariable("VOLCENGINE_SECURITY_TOKEN")
            );

            // 实例化tls sdk client
            var client = new Client(vcConfig);

            /// 构建日志数据（封装的Pb数据）
            var logs = new List<Log>();
            // 单个logGroup不超过10000条
            var num = 100;
            while (num > 0)
            {
                var log = new Log(
                    time: DateTimeOffset.UtcNow.ToUnixTimeSeconds(),
                    contents: new List<LogContent>{
                        new LogContent("k1", $"value{num}"),
                        new LogContent("k2", $"value{num}"),
                    }
                );

                logs.Add(log);

                num--;
            }

            // 构建请求
            var putLogsV2Request = new PutLogsV2Request(
                logs: logs,
                topicId: Environment.GetEnvironmentVariable("TOPIC_ID"),
                compressType: Consts.CompressLz4,
                hashKey: "",
                source: "your log source",
                fileName: "your log filename"
            );

            PutLogsResponse putLogsV2Response = await client.PutLogsV2(putLogsV2Request);
        }
    }
}

4. 初始化 Producer 上报日志示例

using System;
using System.Threading;
using VolcengineTls.Producer;

namespace VolcengineTls.Examples
{
    public class DefaultCallBackImp : ICallBack
    {
        public void Fail(ProducerResult result)
        {
            Console.WriteLine("put log to tls failed");
        }

        public void Success(ProducerResult result)
        {
            Console.WriteLine("put log to tls success");
        }
    }

    public class ProducerExample
    {
        public void Run()
        {
            // 设置火山云权限配置
            var vc = new VolcengineConfig(
                region: Environment.GetEnvironmentVariable("VOLCENGINE_REGION"),
                endpoint: Environment.GetEnvironmentVariable("VOLCENGINE_ENDPOINT"),
                accessKeyId: Environment.GetEnvironmentVariable("VOLCENGINE_ACCESS_KEY_ID"),
                accessKeySecret: Environment.GetEnvironmentVariable("VOLCENGINE_ACCESS_KEY_SECRET"),
                securityToken: Environment.GetEnvironmentVariable("VOLCENGINE_SECURITY_TOKEN")
            );

            // 设置火山云配置，当前获取默认配置
            var config = new ProducerConfig(vc);
            // 实例化
            var producer = new ProducerImp(config);
            // 启动生产者
            producer.Start();

            /// 发送单条
            // 构造日志
            var keyNum = 2;
            var log = new Pb.Log
            {
                Time = DateTimeOffset.UtcNow.ToUnixTimeMilliseconds(),
            };

            for (var i = 0; i < keyNum; i++)
            {
                var logContent = new Pb.LogContent
                {
                    Key = $"key{i}",
                    Value = $"c#-value-test-{i}",
                };

                log.Contents.Add(logContent);
            }

            // 发送单条 或者使用SendLogV2
            producer.SendLog(
                topicId: Environment.GetEnvironmentVariable("TOPIC_ID"),
                log: log,
                source: "your log source",
                filename: "your log filename",
                shardHash: null,
                callback: new DefaultCallBackImp() // 不需要的话可以传null
            );

            /// 发送多条
            var logNum = 1000;
            var logGroup = new Pb.LogGroup();

            for (var j = 0; j < logNum; j++)
            {
                log = new Pb.Log
                {
                    Time = DateTimeOffset.Now.ToUnixTimeSeconds(),
                };

                for (var i = 0; i < keyNum; i++)
                {
                    var logContent = new Pb.LogContent
                    {
                        Key = $"no-{j}-key{i}",
                        Value = $"no-{j}-c#-value-test-{i}",
                    };

                    log.Contents.add(logContent);
                }

                logGroup.Logs.Add(log);
            }

            producer.SendLogs(
                topicId: Environment.GetEnvironmentVariable("TOPIC_ID"),
                logs: logGroup,
                source: "your log source",
                filename: "your log filename",
                shardHash: null,
                callback: new DefaultCallBackImp() // 不需要的话可以传null
            );

            // 模拟其他任务处理
            Thread.Sleep(TimeSpan.FromSeconds(20));

            // 生产者关闭
            producer.Close();
        }
    }
}

5. 运行 example 示例

using System;

namespace VolcengineTls.Examples
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                Console.WriteLine("Starting example...");

                var example = new ProducerExample();

                example.Run(); // 同步方法
                // example.RunAsync().Wait(); // 异步方法

                Console.WriteLine("Example completed successfully.");
            }
            catch (AggregateException ex)
            {
                foreach (var innerEx in ex.InnerExceptions)
                {
                    Console.WriteLine($"Error: {innerEx.Message}");
                    if (innerEx.InnerException != null)
                    {
                        Console.WriteLine($"Inner Error: {innerEx.InnerException.Message}");
                    }
                }
            }
            catch (Exception ex)
            {
                Console.log($"Error: {ex.Message}");
                if (ex.InnerException != null)
                {
                    Console.WriteLine($"Inner Error: {ex.InnerException.Message}");
                }
            }

            Console.WriteLine("Press any key to exit...");
            Console.ReadKey();
        }
    }
}

异常处理

SDK 自定义异常 TlsError 包含以下核心属性，便于问题排查：

• HttpCode：HTTP 状态码
• Code：错误码（如 "InvalidParameter"）
• ErrorMessage：错误描述
• RequestId：请求 ID（用于火山引擎技术支持排查）

try
{
    // 上传日志
}
catch (TlsError e)
{
    // 打印错误详情
    Console.WriteLine($"错误码：{ex.HttpCode}");
    Console.WriteLine($"错误码：{ex.Code}");
    Console.WriteLine($"错误描述：{ex.ErrorMessage}");
    Console.WriteLine($"请求ID：{ex.RequestId}");

    // 根据错误码处理重试逻辑
    if (ex.Code == "RequestTimeout"){
         // 自定义超时重试逻辑
    }
}

注意事项

• 敏感信息保护：AccessKeyId 与 AccessKeySecret 请勿硬编码，建议通过环境变量或安全配置加载
• 日志格式：日志内容的 Key-Value 需符合 TLS Topic 配置的字段类型（字符串 / 整数 / 浮点数等）
• 资源释放：应用退出时，调用 tlsClient.Dispose() 释放连接池等资源
• 框架兼容性：若项目使用 .NET 5.0，需确保运行环境已安装相应 .NET SDK/Runtime

许可证

本项目基于 Apache License 2.0 开源协议，详情见 LICENSE。