Pole C# Thin SDK

pole-client-csharp 是框架无关的 Pole C# Thin SDK。它负责：

• 通过 Unix Domain Socket 与本 Pod Sidecar 建立内部双向 OpenControlSession；
• 首个服务端事件原子安装 HTTP、gRPC、Dubbo、Thrift listener 快照；
• 注册或注销本地服务；SDK 在重连后重放仍处于 desired 状态的注册；
• 为业务请求生成 latticehub-target-namespace 与 latticehub-target-service 元信息。
• 传播可选 TrafficContext 的 campaign、lane、bucket 流量标签。

业务请求不会经过 bootstrap gRPC；应用仍按原协议访问 SDK 返回的 127.0.0.1:<listener-port>，由 Sidecar 代理到真实服务实例。

仓库通过 NuGet 固定引用官方 LatticeHub.Pole.Specification 0.1.0-ALPHA.48，不复制生成代码或引用 Specification 源码工程：

git clone https://github.com/lattice-hub/pole-client-csharp.git
dotnet test tests/LatticeHub.Pole.Client.Tests/LatticeHub.Pole.Client.Tests.csproj
dotnet pack src/LatticeHub.Pole.Client/LatticeHub.Pole.Client.csproj

默认 UDS 为 /var/run/pole/sidecar/bootstrap.sock，仅支持通过 SidecarSessionOptions.SocketPath 或 POLE_SIDECAR_SOCKET 覆盖。SDK 不硬编码 任何业务 listener 端口；会话断开后快照立即失效，重连并收到完整首帧后恢复。

await using var session = await SidecarSession.ConnectAsync();
var grpcAddress = session.ListenerAddress(SidecarProtocol.Grpc);

var registrationId = await session.RegisterLocalServiceAsync(
    new LocalServiceRegistration("default", "orders", SidecarProtocol.Grpc, 50051));
await session.UnregisterLocalServiceAsync(registrationId);

var target = new TargetService("default", "orders");
var metadata = target.EncodeGrpcMetadata();

TargetService v1 只有 namespace 与 service。SDK 去除契约定义的首尾空白、 拒绝 Unicode Cc 控制字符和非法 UTF-16，并执行 canonical UTF-8 %HH 编码。

TrafficContext.Current 从原生 AsyncLocal 读取当前调用链； TrafficContext.Attach(context) 返回 IDisposable，释放后严格恢复嵌套前的上下文。 TargetService.EncodeMetadata 与 EncodeGrpcMetadata 接受可选显式 context，显式值优先于 Current，并在同一出站装配点更新 baggage：覆盖 latticehub.traffic.*、保留外部 Baggage，若结果为空则删除 carrier。它不以 Activity.TraceId 反查或关联灰度标签。 TrafficContextException.DiagnosticCode 与 vendored conformance diagnostics 对齐；测试会执行 全部 inject、有效 receive 和无效 receive 向量，而不是只检查资产校验和。

启用标准 OpenTelemetry .NET 传播时，调用 TrafficContext.InstallOpenTelemetryBaggageStorage()； 内置 adapter 直接读写 OpenTelemetry.Api 的 OpenTelemetry.Baggage.Current，作用域退出时 恢复完整旧 Baggage，因此标准 OTel BaggagePropagator 可读取标签。ActivityTrafficContextStorageAdapter 仅是调用方自定义 delegate seam，不等价于标准 OTel Baggage；SDK 不使用 System.Diagnostics.Activity.AddBaggage 冒充标准传播。未安装时继续使用 AsyncLocal fallback。 此版本不提供 ASP.NET、gRPC、Dubbo、HTTP client 的自动入口/出站 hook，也不重复 inject。

contract/traffic-context/v1 vendoring 当前 TrafficContext v1 README、schema、conformance vectors 与校验和。