# 哨兵.NET SDK 独具见解的向导可扫描您的 .NET 项目并指导您完成完整的 Sentry 设置：跨所有主要 .NET 框架的错误监控、分布式跟踪、分析、结构化日志记录和 cron 监控。 ## 调用此技能时 * 用户请求“将 Sentry 添加到 .NET”、“在 C# 中设置 Sentry”或“为 ASP.NET Core 安装 Sentry” * 用户想要 .NET 应用程序的错误监控、跟踪、分析、日志记录或 crons * 用户提及 `SentrySdk.Init`、`UseSentry`、`Sentry.AspNetCore` 或 `Sentry.Maui` * 用户想要捕获 WPF、WinForms、MAUI 或 Azure Functions 中未处理的异常 * 用户询问 `SentryOptions`、`BeforeSend`、`TracesSampleRate` 或符号上传 > **注意：** 下面的 SDK 版本和 API 反映 `Sentry` NuGet 包 ≥6.1.0。在实施之前始终验证 [docs.sentry.io/platforms/dotnet/]()。 ** ** ## 第一阶段：检测在提出任何建议之前，运行以下命令来了解项目： # 检测框架类型 — 查找所有 .csproj 文件找到。 -名称“*.csproj”|头-20 # 检测框架目标 grep -r "TargetFramework\|Project Sdk" --include="*.csproj" 。 # 检查现有的 Sentry 包 grep -r "哨兵" --include="*.csproj" 。 | grep“包参考” # 检查启动文件 ls Program.cs src/Program.cs App.xaml.cs MauiProgram.cs 2>/dev/null # 检查应用程序设置 ls appsettings.json src/appsettings.json 2>/dev/null # 检查日志库 grep -r "Serilog\|NLog\|log4net" --include="*.csproj" 。 # 检查配套前端 ls ../前端../客户端../web 2>/dev/null 猫 ../package.json 2>/dev/null | grep -E '"下一个"|"react"|"vue"' |头-3 **要确定什么：** 问题 |影响 ---|--- 框架类型？ |确定正确的包和初始化模式 .NET 版本？ |推荐.NET 8+；支持 .NET Framework 4.6.2+ 哨兵已经安装了吗？ |跳过安装，转到功能配置日志库（Serilog、NLog）？ |推荐匹配的 Sentry 接收器/目标异步/托管应用程序（ASP.NET Core）？ | `WebHost` 上的 `UseSentry()`；不需要“IsGlobalModeEnabled” 桌面应用程序（WPF、WinForms、WinUI）？ |必须设置 `IsGlobalModeEnabled = true` 无服务器（Azure Functions、Lambda）？ |必须设置`FlushOnCompletedRequest = true` 找到前端目录了吗？ |触发第 4 阶段交叉链接 **框架→包映射：** 检测到 |要安装的包 ---|--- `Sdk="Microsoft.NET.Sdk.Web"` (ASP.NET Core) | `哨兵.AspNetCore` 带有“Application”基础的“App.xaml.cs” | “哨兵”（WPF） `Program.cs` 中的 `[STAThread]` | “哨兵”（WinForms） `MauiProgram.cs` |毛伊岛哨兵 `WebAssemblyHostBuilder` | `Sentry.AspNetCore.Blazor.WebAssembly` `函数启动` | `Sentry.Extensions.Logging` \+ `Sentry.OpenTelemetry` `HttpApplication` / `Global.asax` | `哨兵.AspNet` 通用主机/Worker Service | `Sentry.Extensions.Logging` ** ** ## 第二阶段：推荐根据您的发现提出具体建议。以提案为主导——不要问开放式问题。 **推荐（核心覆盖）：** * ✅ **错误监控** — 始终；捕获未处理的异常、结构化捕获、范围丰富 * ✅ **跟踪** — 始终适用于 ASP.NET Core 和托管应用程序；自动检测 HTTP 请求和 EF Core 查询 * ✅ **日志记录** — 建议所有应用程序使用；将 ILogger / Serilog / NLog 条目作为面包屑和事件路由到 Sentry **可选（增强可观察性）：** * ⚡ **分析** — CPU 分析；推荐用于在 .NET 6+ 上运行的性能关键型服务 * ⚡ **Crons** — 检测错过/失败的预定作业；当检测到 Hangfire、Quartz.NET 或计划端点时建议 **推荐逻辑：** 特色 |推荐当... ---|--- 错误监控 | **始终** — 不可协商的基线追踪 | **始终适用于 ASP.NET Core** — 请求跟踪、EF Core 跨度、HttpClient 跨度具有高价值记录 |应用程序使用“ILogger”、Serilog、NLog 或 log4net 简介 | .NET 6+ 上的性能关键型服务克朗斯 |应用程序使用 Hangfire、Quartz.NET 或预定的 Azure Functions 建议：_“我建议设置错误监控 + 跟踪 + 日志记录。想要我也添加分析或 Cron 吗？”_ ** ** ## 第三阶段：指南 ### 选项 1：向导（推荐） npx @sentry/wizard@latest -i dotnet 该向导将您登录到 Sentry，选择您的组织和项目，配置您的 DSN，并设置 MSBuild 符号上传以在生产中提供可读的堆栈跟踪。 **运行向导后跳至验证。** ** ** ### 选项 2：手动设置 #### 安装正确的包 # ASP.NET 核心 dotnet 添加包 Sentry.AspNetCore -v 6.1.0 # WPF 或 WinForms 或控制台 dotnet 添加包 Sentry -v 6.1.0 # .NET 毛伊岛 dotnet 添加包 Sentry.Maui -v 6.1.0 # Blazor WebAssembly dotnet 添加包 Sentry.AspNetCore.Blazor.WebAssembly -v 6.1.0 # Azure Functions（独立工作线程） dotnet 添加包 Sentry.Extensions.Logging -v 6.1.0 dotnet 添加包 Sentry.OpenTelemetry -v 6.1.0 # 经典 ASP.NET（System.Web / .NET Framework） dotnet 添加包 Sentry.AspNet -v 6.1.0 ** ** #### ASP.NET Core — `Program.cs` var builder = WebApplication.CreateBuilder(args); builder.WebHost.UseSentry(选项 => { options.Dsn = Environment.GetEnvironmentVariable("SENTRY_DSN") ?? “___您的_DSN___”；选项.调试= true; // 在生产中禁用选项.SendDefaultPii = true; // 捕获用户IP、姓名、电子邮件 options.MaxRequestBodySize = RequestSize.Always; 选项.MinimumBreadcrumbLevel = LogLevel.Debug; options.MinimumEventLevel = LogLevel.Warning; 选项.TracesSampleRate = 1.0; // 在生产中调整到 0.1–0.2 options.SetBeforeSend((@event, 提示) => { @event.ServerName = null; // 从事件中清除主机名返回@事件； }); }); var app = builder.Build(); 应用程序.运行(); **`appsettings.json`（替代配置）：** { “哨兵”：{ "Dsn": "___您的_DSN___", “SendDefaultPii”：正确， "MaxRequestBodySize": "始终", "MinimumBreadcrumbLevel": "调试", "MinimumEventLevel": "警告", “AttachStacktrace”：正确， “调试”：正确， “痕迹采样率”：1.0， “环境”：“生产”， "发布": "my-app@1.0.0" } } **环境变量（双下划线作为分隔符）：** 导出 Sentry__Dsn="https://examplePublicKey@o0.ingest.sentry.io/0" 导出 Sentry__TracesSampleRate="0.1" 导出 Sentry__Environment="staging" ** ** #### WPF — `App.xaml.cs` > ⚠️ **关键：** 在 **构造函数** 中初始化，而不是在 `OnStartup()` 中。构造函数更早触发，捕获更多故障模式。使用系统.Windows；使用哨兵；公共部分类App：应用程序 { 公共应用程序() { SentrySdk.Init（选项=> { 选项.Dsn =“___YOUR_DSN___”; 选项.调试= true; 选项.SendDefaultPii = true; 选项.TracesSampleRate = 1.0; 选项.IsGlobalModeEnabled = true; // 所有桌面应用程序都需要 }); // 在 WPF 崩溃对话框出现之前捕获 WPF UI 线程异常 DispatcherUnhandledException += App_DispatcherUnhandledException; } 私有无效App_DispatcherUnhandledException（对象发送者， System.Windows.Threading.DispatcherUnhandledExceptionEventArgs e) { SentrySdk.CaptureException(e.Exception); // 设置 e.Handled = true 以防止崩溃对话框并保持应用程序运行 } } ** ** #### WinForms — `Program.cs` 使用系统；使用 System.Windows.Forms；使用哨兵；静态类程序 { [STA线程] 静态无效Main() { Application.EnableVisualStyles(); Application.SetCompatibleTextRenderingDefault(false); // 必需：允许 Sentry 查看未处理的 WinForms 异常 Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException); 使用 (SentrySdk.Init(new SentryOptions { Dsn =“___您的_DSN___”，调试=真，轨迹采样率 = 1.0, IsGlobalModeEnabled = true, // 桌面应用程序必需 }）） { Application.Run(new MainForm()); } // 处理会刷新所有待处理事件 } } ** ** #### .NET MAUI — `MauiProgram.cs` 公共静态类 MauiProgram { 公共静态 MauiApp CreateMauiApp() { var builder = MauiApp.CreateBuilder(); 建设者 .UseMauiApp<应用程序>() .UseSentry(选项=> { 选项.Dsn =“___YOUR_DSN___”; 选项.调试= true; 选项.SendDefaultPii = true; 选项.TracesSampleRate = 1.0; // MAUI 特定：选择加入面包屑（默认关闭 — PII 风险）选项。 IncludeTextInBreadcrumbs = false; 选项。 IncludeTitleInBreadcrumbs = false; 选项。 IncludeBackgroundingStateInBreadcrumbs = false; }); 返回构建器.Build(); } } ** ** #### Blazor WebAssembly — `Program.cs` var builder = WebAssemblyHostBuilder.CreateDefault(args); builder.UseSentry（选项=> { 选项.Dsn =“___YOUR_DSN___”; 选项.调试= true; 选项.SendDefaultPii = true; 选项.TracesSampleRate = 0.1; }); // 挂钩日志记录管道，无需重新初始化 SDK builder.Logging.AddSentry(o => o.InitializeSdk = false); 等待 builder.Build().RunAsync(); ** ** #### Azure Functions（独立工作线程）— `Program.cs` 使用 Microsoft.Extensions.Hosting；使用 Microsoft.Extensions.Logging；使用 OpenTelemetry.Trace；使用 Sentry.OpenTelemetry； var 主机 = 新的 HostBuilder() .ConfigureFunctionsWorkerDefaults() .ConfigureServices(服务=> { services.AddOpenTelemetry().WithTracing(builder => { 建设者 .AddSentry() // 将 OTel 范围路由到 Sentry .AddHttpClientInstrumentation(); // 捕获传出的 HTTP }); }) .配置日志记录（日志记录=> { 日志记录.AddSentry（选项=> { 选项.Dsn =“___YOUR_DSN___”; 选项.调试= true; 选项.TracesSampleRate = 1.0; 选项.UseOpenTelemetry(); // 让 OTel 驱动跟踪选项.DisableSentryHttpMessageHandler = true; // 防止重复的 HTTP Span }); }) .Build(); 等待主机.RunAsync(); ** ** #### AWS Lambda — `LambdaEntryPoint.cs` 公共类 LambdaEntryPoint ：APIGatewayProxyFunction { protected override void Init（IWebHostBuilder 构建器） { 建设者 .UseSentry(选项=> { 选项.Dsn =“___YOUR_DSN___”; 选项.TracesSampleRate = 1.0; 选项.FlushOnCompletedRequest = true; // Lambda 必需的 }) .UseStartup<启动>(); } } ** ** #### 经典 ASP.NET — `Global.asax.cs` 公共类 MvcApplication ：HttpApplication { 私有 IDisposable _sentry； protected void Application_Start() { _sentry = SentrySdk.Init（选项=> { 选项.Dsn =“___YOUR_DSN___”; 选项.TracesSampleRate = 1.0; 选项.AddEntityFramework(); // EF6 查询面包屑选项.AddAspNet(); // 经典的 ASP.NET 集成 }); } protected void Application_Error() => Server.CaptureLastError(); protected void Application_BeginRequest() => Context.StartSentryTransaction(); protected void Application_EndRequest() => Context.FinishSentryTransaction(); protected void Application_End() => _sentry?.Dispose(); } ** ** ### 符号上传（可读堆栈跟踪）如果没有调试符号，堆栈跟踪仅显示方法名称，而不显示文件名或行号。上传 PDB 文件以解锁完整的源上下文。 **第 1 步：创建 Sentry 身份验证令牌** 转到 [sentry.io/settings/auth-tokens/]() 并创建一个具有 `project:releases` 和 `org:read` 范围的令牌。 **步骤 2：将 MSBuild 属性添加到`.csproj`或`Directory.Build.props`：** ___ORG_SLUG___ ___PROJECT_SLUG___ true true true true **第3步：在CI中设置`SENTRY_AUTH_TOKEN`：** # GitHub 操作 - 名称：构建和上传符号运行： dotnet build -c Release 环境： SENTRY_AUTH_TOKEN：${{secrets.SENTRY_AUTH_TOKEN }} ** ** ### 对于每个商定的功能加载相应的参考文件并按照其步骤操作：特色 |参考文件|加载时... ---|---|--- 错误监控 | `references/error-monitoring.md` |始终 — `CaptureException`、范围、丰富、过滤追踪 | `引用/tracing.md` |服务器应用程序、分布式跟踪、EF Core 跨度、自定义检测简介 | `references/profiling.md` | .NET 6+ 上的性能关键型应用程序记录 | `references/logging.md` | `ILogger`、Serilog、NLog、log4net 集成克朗斯 | `references/crons.md` | Hangfire、Quartz.NET 或预定功能监控对于每个功能：阅读参考文件，严格遵循其步骤，并在继续之前进行验证。 ** ** ## 验证向导或手动设置后，添加测试投掷并在验证后将其删除： // ASP.NET Core：添加临时端点 app.MapGet("/哨兵测试", () => { throw new Exception("Sentry 测试错误 — 删除我"); }); // 或者在任何地方显式捕获 SentrySdk.CaptureException(new Exception("Sentry 测试错误 — 删除我")); 然后检查您的 [Sentry 问题仪表板]() — 错误应该会在大约 30 秒内出现。 **验证清单：** 检查 |如何 ---|--- 捕获的异常 |抛出测试异常，在Sentry Issues中验证堆栈跟踪可读 |检查文件名和行号是否出现追踪活动 |检查事务的“性能”选项卡有线记录|通过“ILogger”记录错误，检查它是否显示为 Sentry 面包屑符号上传工作 |堆栈跟踪显示“Controllers/HomeController.cs:42”而不是“” ** ** ## 配置参考 ### 核心 `SentryOptions` 选项 |类型 |默认 |环境变量 |注释 ---|---|---|---|--- `Dsn` | `字符串` | — | `SENTRY_DSN` |必需的。如果未设置，则 SDK 被禁用。 `调试` | `布尔` | `假` | — | SDK 诊断输出。在生产中禁用。 `诊断级别` | `哨兵级` | `调试` | — | “调试”、“信息”、“警告”、“错误”、“致命” `发布` | `字符串` |汽车 | `SENTRY_RELEASE` |从程序集版本自动检测 + git SHA `环境` | `字符串` | `“生产”` | `SENTRY_ENVIRONMENT` |连接调试器时的“调试” `距离` | `字符串` | — | — |构建变体。最多 64 个字符。 `采样率` | `浮动` | `1.0` | — |错误事件采样率 0.0–1.0 `TraceSampleRate` | `双` | `0.0` | — |交易抽样。必须为“> 0”才能启用。 `TraceSampler` | `Func` | — | — |每笔交易动态采样器；覆盖`TracesSampleRate` `ProfilesSampleRate` | `双` | `0.0` | — |追踪到的交易的比例。需要`Sentry.Profiling`。 `发送默认Pii` | `布尔` | `假` | — |包括用户IP、姓名、电子邮件 `附加堆栈跟踪` | `布尔` | `真实` | — |将堆栈跟踪附加到所有消息 `最大面包屑导航` | `int` | `100` | — |每个事件存储的最大面包屑数量 `IsGlobalModeEnabled` | `布尔` | `假`* | — | *对于 MAUI、Blazor WASM，自动为“true”。对于 WPF、WinForms、控制台，**必须**为“true”。 `自动会话跟踪` | `布尔` | `假`* | — | *MAUI 自动-“true”。启用发布运行状况。 `CaptureFailedRequests` | `布尔` | `真实` | — |自动捕获 HTTP 客户端错误 `CacheDirectoryPath` | `字符串` | — | — |离线事件缓存目录 `关闭超时` | `时间跨度` | — | — |关闭时最大等待事件刷新 `HttpProxy` | `字符串` | — | — | Sentry 请求的代理 URL `启用背压处理` | `布尔` | `真实` | — |交付失败时自动降低采样率 ### ASP.NET Core 扩展选项 (`SentryAspNetCoreOptions`) 选项 |类型 |默认 |注释 ---|---|---|--- `MaxRequestBodySize` | `请求大小` | `无` | “无”、“小”（~4 KB）、“中”（~10 KB）、“始终” `最小面包屑级别` | `日志级别` | `信息` |面包屑的最低日志级别 `最低事件级别` | `日志级别` | `错误` |作为哨兵事件发送的最小日志级别 `CaptureBlockingCalls` | `布尔` | `假` |检测 `.Wait()` / `.Result` 线程池饥饿 `FlushOnCompletedRequest` | `布尔` | `假` | **Lambda/无服务器所需** `包含活动数据` | `布尔` | `假` |捕获“System.Diagnostics.Activity”值 ### MAUI 扩展选项 (`SentryMauiOptions`) 选项 |类型 |默认 |注释 ---|---|---|--- `在面包屑中包含文本` | `布尔` | `假` |来自“Button”、“Label”、“Entry”元素的文本。 ⚠️ PII 风险。 `在面包屑中包含标题` | `布尔` | `假` |来自“Window”、“Page”元素的标题。 ⚠️ PII 风险。 `在面包屑中包含背景状态` | `布尔` | `假` | `Window.Backgrounding` 事件状态。 ⚠️ PII 风险。 ### 环境变量变量|目的 ---|--- `SENTRY_DSN` |项目DSN `SENTRY_RELEASE` |应用程序版本（例如“my-app@1.2.3”） `SENTRY_ENVIRONMENT` |部署环境名称 `SENTRY_AUTH_TOKEN` | MSBuild / `sentry-cli` 符号上传身份验证令牌 **ASP.NET Core:** 使用双下划线 `__` 作为层次结构分隔符：导出 Sentry__Dsn="https://..." 导出 Sentry__TracesSampleRate="0.1" ### MSBuild 符号上传属性物业 |类型 |默认 |描述 ---|---|---|--- `SentryOrg` | `字符串` | — |哨兵组织蛞蝓 `哨兵计划` | `字符串` | — | Sentry 项目 slug `SentryUploadSymbols` | `布尔` | `假` |上传 PDB 文件以获取堆栈跟踪中的行号 `SentryUploadSources` | `布尔` | `假` |上传源上下文的源文件 `SentryCreateRelease` | `布尔` | `假` |在构建期间自动创建 Sentry 版本 `SentrySetCommits` | `布尔` | `假` |将 git 提交与发布关联起来 `SentryUrl` | `字符串` | — |自托管哨兵 URL ** ** ## 第 4 阶段：交叉链接完成 .NET 设置后，检查配套前端项目： # 检查相邻目录中的前端 ls ../frontend ../client ../web ../app 2>/dev/null # 检查 JavaScript 框架指标猫 ../package.json 2>/dev/null | grep -E '“下一个”|“react”|“vue”|“nuxt”' |头-3 如果找到前端，建议匹配的SDK技能：检测到前端 |建议技能 ---|--- Next.js (`package.json` 中的`"next"`) | `sentry-nextjs-sdk` React SPA (`"react"` 没有 `"next"`) | `@sentry/react` — 参见 [docs.sentry.io/platforms/javascript/guides/react/]() Vue.js | `@sentry/vue` — 请参阅 [docs.sentry.io/platforms/javascript/guides/vue/]() 努克斯特 | `@sentry/nuxt` — 参见 [docs.sentry.io/platforms/javascript/guides/nuxt/]() 使用同一个 Sentry 项目连接前端和后端可实现**分布式跟踪** — 跨浏览器、.NET 服务器和任何下游 API 的单个跟踪视图。 ** ** ## 故障排除问题 |原因 |解决方案 ---|---|--- 事件未出现 | DSN 配置错误 |设置“Debug = true”并检查控制台输出中的 SDK 诊断消息堆栈跟踪显示没有文件/行 | PDB 文件未上传 |将`SentryUploadSymbols=true`添加到`.csproj`；在 CI 中设置 `SENTRY_AUTH_TOKEN` WPF/WinForms 异常缺失 |未设置“IsGlobalModeEnabled” |在`SentrySdk.Init()`中设置`options.IsGlobalModeEnabled = true` Lambda/无服务器事件丢失 |容器在冲洗前结冰|设置 `options.FlushOnCompletedRequest = true` WPF UI 线程异常缺失 | `DispatcherUnhandledException` 未连接 |在构造函数中注册“App.DispatcherUnhandledException”（而不是“OnStartup”） Azure Functions 中的重复 HTTP 范围 | Sentry 和 OTel 仪器 HTTP |设置 `options.DisableSentryHttpMessageHandler = true` `TracesSampleRate` 没有效果 |速率为“0.0”（默认）|设置 `TracesSampleRate > 0` 以启用跟踪忽略 `appsettings.json` 值 |配置密钥格式错误 |使用平键 `"Sentry:Dsn"` 或环境变量 `Sentry__Dsn` （双下划线） `BeforeSend` 删除所有事件 | Hook 无条件返回 `null` |验证您的过滤逻辑；仅对要删除的事件返回“null” MAUI 原生崩溃未捕获 |错误的包裹 |确认已安装“Sentry.Maui”（不仅仅是“Sentry”）

Sentry Dotnet SDK

包含技能