.NET Aspire Seq 集成

2025-04-21

包含： - Client 集成

Seq 是一种自承载搜索和分析服务器，用于处理结构化应用程序日志和跟踪文件。它包括 JSON 事件存储和简单的查询语言，使它易于使用。可以使用 .NET AspireSeq 集成将 OpenTelemetry 协议（OTLP）数据发送到 Seq。集成支持在应用程序重启期间实现日志和跟踪的持久性。

在开发期间，.NET.NET Aspire 运行并连接到 datalust/seq 容器镜像。

托管集成

托管集成 Seq 将服务器建模为 SeqResource 类型。若要访问此类型和 API，请在 📦 项目中添加 AspireSeq.Hosting. NuGet 包。

.NET 命令行界面
包引用

dotnet add package Aspire.Hosting.Seq

<PackageReference Include="Aspire.Hosting.Seq"
                  Version="*" />

有关详细信息，请参阅 dotnet add package 或管理 .NET 应用程序中的包依赖项。

添加 Seq 资源

在应用主机项目中，调用 AddSeq 添加并返回 Seq 资源生成器。

var builder = DistributedApplication.CreateBuilder(args);

var seq = builder.AddSeq("seq")
                 .ExcludeFromManifest()
                 .WithLifetime(ContainerLifetime.Persistent)
                 .WithEnvironment("ACCEPT_EULA", "Y");

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(seq)
                       .WaitFor(seq);

// After adding all resources, run the app...

注意

Seq 容器启动速度可能很慢，因此最好使用 持久性 生存期以避免不必要的重启。有关详细信息，请参阅容器资源生存期。

接受 Seq 最终用户许可协议（EULA）

必须接受 Seq EULA 才能启动 Seq。若要在代码中接受协议，请将环境变量 ACCEPT_EULA 传递给 Seq 容器，并将其值设置为 Y。上述代码在链式调用中传递此变量到 WithEnvironment。

Seq 在 .NET Aspire 清单中

Seq 不应是 .NET Aspire部署清单的一部分，因此，进行了对 ExcludeFromManifest的链式调用。建议为生产环境在 Seq 外部设置一个安全的生产 .NET Aspire 服务器。

持久日志和跟踪记录

将 Seq 注册到应用主机项目中的数据目录，以便在应用程序重启时保留 Seq的数据和配置：

var seq = builder.AddSeq("seq", seqDataDirectory: "./seqdata")
                 .ExcludeFromManifest()
                 .WithLifetime(ContainerLifetime.Persistent);

指定的目录必须已存在。

添加带有数据卷的 Seq 资源

若要将数据卷添加到 Seq 资源，请在 WithDataVolume 资源上调用 Seq 方法：

var builder = DistributedApplication.CreateBuilder(args);

var seq = builder.AddSeq("seq")
                 .WithDataVolume()
                 .ExcludeFromManifest()
                 .WithLifetime(ContainerLifetime.Persistent);

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(seq)
                       .WaitFor(seq);

数据卷用于在容器的生命周期之外保留 Seq 数据。数据卷装载在 /data 路径的 Seq 容器中，如果未提供 name 参数，则会随机生成名称。有关数据卷的信息，以及它们为何优于绑定挂载的原因，请参阅Docker文档：卷。

添加具有数据绑定挂载的 Seq 资源

若要将数据绑定挂载添加到 Seq 资源，请调用 WithDataBindMount 方法。

var builder = DistributedApplication.CreateBuilder(args);

var seq = builder.AddSeq("seq")
                 .WithDataBindMount(source: @"C:\Data")
                 .ExcludeFromManifest()
                 .WithLifetime(ContainerLifetime.Persistent);

var myService = builder.AddProject<Projects.ExampleProject>()
                       .WithReference(seq)
                       .WaitFor(seq);

重要

与卷相比，数据绑定挂载的功能有限，卷提供更好的性能、可移植性和安全性，因此更适用于生产环境。但是，绑定装载允许直接访问和修改主机系统上的文件，非常适合在需要实时更改的情况下进行开发和测试。

数据绑定装载依赖于主机的文件系统在容器重启时保留 Seq 数据。在主机机器上的 C:\Data 容器中，数据绑定挂载位于 Windows 系统的 /Data 路径（或在 Unix 上的 Seq 路径）。有关数据绑定挂载的详细信息，请参阅 Docker 文档：数据绑定挂载。

Client 集成

若要开始 .NET AspireSeq 客户端集成，请在客户端消费项目中安装 📦.Aspire NuGet 包，也就是应用程序使用 Seq 客户端的项目。

.NET 命令行界面
包引用

dotnet add package Aspire.Seq

<PackageReference Include="Aspire.Seq"
                  Version="*" />

添加 Seq 客户端

在客户端使用项目的 Program.cs 文件中，调用 AddSeqEndpoint 扩展方法以注册 OpenTelemetry 协议导出程序以将日志和跟踪发送到 Seq 和 .NET Aspire 仪表板。该方法采用连接名称参数。

builder.AddSeqEndpoint(connectionName: "seq");

提示

connectionName 参数必须与在应用主机项目中添加 Seq 资源时使用的名称匹配。换句话说，当调用 AddSeq 并提供 seq 的名称时，应在调用 AddSeqEndpoint 时使用相同的名称。有关详细信息，请参阅添加 Seq 资源。

配置

.NET Aspire Seq 集成提供了多个选项，用于根据项目的要求和约定配置与 Seq 的连接。

使用配置提供程序

.NET Aspire Seq 集成支持 Microsoft.Extensions.Configuration。它使用 SeqSettings 键从配置中加载 Aspire:Seq。以下代码片段是配置某些选项的 appsettings.json 文件的示例：

{
  "Aspire": {
    "Seq": {
      "DisableHealthChecks": true,
      "ServerUrl": "http://localhost:5341"
    }
  }
}

有关完整的 Seq 客户端集成 JSON 架构，请参阅 Aspire。Seq/ConfigurationSchema.json。

使用内联委托

您还可以传递 Action<SeqSettings> configureSettings 委托来直接在代码中设置某些或所有选项，例如通过代码禁用运行状况检查：

builder.AddSeqEndpoint("seq", static settings => 
{
    settings.DisableHealthChecks  = true;
    settings.ServerUrl = "http://localhost:5341"
});

Client 整合健康检查

默认情况下，所有服务的.NET.NET Aspire客户端集成都启用了状态检查。同样，许多托管集成 .NET.NET Aspire 也启用健康检查端点。有关详细信息，请参阅：

在 C# .NET 应用运行状况检查
健康检查ASP.NET Core

.NET Aspire Seq 集成处理以下内容：

当 SeqSettings.DisableHealthChecks 是 false 时，添加健康检查，尝试连接 Seq 服务器的 /health 终结点。
与 /health HTTP 端点集成，该端点规定所有注册的健康检查都必须通过，应用才能开始接受流量。

可观测性和遥测

.NET .NET Aspire 集成会自动设置日志记录、跟踪和指标配置，这些配置有时称为 可观测性的支柱。有关集成可观测性和遥测的详细信息，请参阅 .NET.NET Aspire 集成概述。根据支持服务，某些集成可能仅支持其中一些功能。例如，某些集成支持日志记录和跟踪，但不支持指标。也可以使用配置部分中介绍的技术禁用遥测功能。

伐木

.NET Aspire Seq 集成使用以下日志类别：

Seq

跟踪和指标

.NET Aspire Seq 集成不会发出跟踪活动和/或指标，因为它是遥测接收器，而不是遥测源。

通过