Fast.Consul

版本 3.5.9；目标 net8.0、net9.0、net10.0；依赖 Fast.Runtime 与 Consul。提供服务注册、健康检查及 KV 访问。

bash

dotnet add package Fast.Consul

注册 API

以下为消费端 Program.cs，使用 Microsoft.NET.Sdk.Web，目标选择本页列出的 .NET 8、9 或 10，并安装上方指定包。app.Run() 表示正常宿主启动；本次文档维护不会执行它。

csharp

using Fast.Consul;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.AspNetCore.Builder;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFastConsul(builder.Configuration, "ConsulSettings");

var app = builder.Build();
app.MapGet("/healthCheck", () => "healthy");
app.Run();

AddFastConsul(IServiceCollection, IConfiguration, string section = "ConsulSettings") 返回服务集合。services/configuration 为 null 时抛 ArgumentNullException，节点名空白时抛 ArgumentException。配置绑定后执行后配置，并注册启动过滤器；完整启动宿主可能向 Consul 注册服务。

ConsulSettingsOptions

字段	后配置默认值与约束
`Enable`	`true`
`Address`	`http://127.0.0.1:8500`；必须是 HTTP/HTTPS 绝对地址
`ServiceAddress`	无默认值；为空时从实际监听地址获取，容器/代理下宜明确给出 Consul 可访问地址
`HealthCheck`	`/healthCheck`；不能空白，缺少前导 `/` 时补齐
`DeregisterCriticalServiceAfter`	`60` 秒；健康检查持续失败后的摘除阈值，不是启动等待时间
`HealthCheckInterval`	`10` 秒
`HealthCheckTimeout`	`5` 秒

后三个时长必须大于 0；非法地址或时长由后配置抛 InvalidOperationException。不要仅凭选项上的旧摘要把摘除阈值解释成注册延迟。

KV 服务

IKeyValueService 的默认实现为 KeyValueService，按 Transient 注册。

签名	行为
`Task<string> GetKeyValue(string settingPath, string dcName)`	读取指定数据中心的键路径并解码为文本
`Task<T> GetKeyValue<T>(string settingPath, string dcName)`	解码后反序列化为 T
`Task<bool> EditKeyValue(string settingPath, string dcName, string data)`	对远端 KV 执行写入；bool 表示 Consul 是否确认成功

空路径/数据中心抛 ArgumentException；缺失键抛 KeyNotFoundException；非法 Base64 抛 FormatException；泛型解析还可能抛 JSON 异常。调用方法没有 CancellationToken 参数，不应在文档中承诺可取消重载。

读取强类型配置

下面的消费者使用上面的 AddFastConsul 注册结果。在 builder.Build() 前增加 builder.Services.AddTransient<FeatureReader>()，由端点或业务服务注入它；不要自行创建第二个根容器。

csharp

using Fast.Consul;

public sealed class FeatureSettings
{
    public bool EnablePreview { get; set; }
}

public sealed class FeatureReader(IKeyValueService values)
{
    public Task<FeatureSettings> ReadAsync() =>
        values.GetKeyValue<FeatureSettings>("sample/features", "dc1");
}

sample/features 与 dc1 是应用选定的 KV 键和数据中心标识，部署前按实际环境配置。调用返回反序列化后的对象，不是订阅流。缺失键抛 KeyNotFoundException，非法 Base64/JSON 会继续抛对应解析异常。非泛型重载返回文本；EditKeyValue(path, dc, data) 返回 Consul 确认的 bool，属于远程写操作，本示例不调用。

来源与验证

依据注册、配置、KV 合同。本轮不启动服务、不访问 Consul、不执行 KV 写入；片段未编译。

Fast.Consul ​

注册 API ​

ConsulSettingsOptions ​

KV 服务 ​

读取强类型配置 ​