sentry-dotnet-sdk

Sentry .NET SDK

.NET プロジェクトをスキャンし、エラー監視、分散トレーシング、プロファイリング、構造化ログ、主要なすべての .NET フレームワークでのクロン監視を含む、Sentry の完全なセットアップを案内する、意見を反映したウィザードです。

このスキルを呼び出すタイミング

• ユーザーが「.NET に Sentry を追加して」「C# で Sentry をセットアップして」「ASP.NET Core に Sentry をインストールして」と依頼した場合
• ユーザーが .NET アプリのエラー監視、トレーシング、プロファイリング、ログ記録、クロンを希望する場合
• ユーザーが 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/ で確認してください。

---

フェーズ 1：検出

推奨事項を提示する前に、以下のコマンドを実行してプロジェクトの状況を把握してください。

# Detect framework type — find all .csproj files
find . -name "*.csproj" | head -20

# Detect framework targets
grep -r "TargetFramework\|Project Sdk" --include="*.csproj" .

# Check for existing Sentry packages
grep -r "Sentry" --include="*.csproj" . | grep "PackageReference"

# Check startup files
ls Program.cs src/Program.cs App.xaml.cs MauiProgram.cs 2>/dev/null

# Check for appsettings
ls appsettings.json src/appsettings.json 2>/dev/null

# Check for logging libraries
grep -r "Serilog\|NLog\|log4net" --include="*.csproj" .

# Check for companion frontend
ls ../frontend ../client ../web 2>/dev/null
cat ../package.json 2>/dev/null | grep -E '"next"|"react"|"vue"' | head -3

確認する項目：

質問	影響
フレームワークの種類は？	適切なパッケージと初期化パターンが決まります
.NET のバージョンは？	.NET 8 以降を推奨します。 .NET Framework 4.6.2 以降もサポートされています
Sentry はすでにインストールされていますか？	インストールをスキップし、機能の設定に進みます
ロギングライブラリ（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）	Sentry.AspNetCore
Application を基底クラスとする App.xaml.cs	Sentry（WPF）
Program.cs 内の [STAThread]	Sentry（WinForms）
MauiProgram.cs	Sentry.Maui
WebAssemblyHostBuilder	Sentry.AspNetCore.Blazor.WebAssembly
FunctionsStartup	Sentry.Extensions.Logging + Sentry.OpenTelemetry
HttpApplication / Global.asax	Sentry.AspNet
汎用ホスト / Worker Service	Sentry.Extensions.Logging

---

フェーズ 2：推奨

確認した内容に基づいて、具体的な推奨事項を提示してください。まず提案を示し、自由回答形式の質問はしないでください。

推奨（基本的なカバレッジ）：

• ✅ エラー監視 — 常に推奨します。未処理の例外、構造化キャプチャ、スコープのエンリッチメントを取得します
• ✅ トレーシング — ASP.NET Core およびホスト型アプリでは常に推奨します。HTTP リクエストと EF Core クエリを自動計測します
• ✅ ログ記録 — すべてのアプリに推奨します。ILogger / Serilog / NLog のログをパンくずリストとイベントとして Sentry に送ります

オプション（オブザーバビリティの強化）：

• ⚡ プロファイリング — CPU プロファイリングです。.NET 6 以降で動作する、パフォーマンスが重要なサービスに推奨します
• ⚡ クロン — 実行されなかった、または失敗したスケジュール済みジョブを検出します。Hangfire、Quartz.NET、またはスケジュール済みエンドポイントが検出された場合に推奨します

推奨ロジック：

機能	推奨する条件
エラー監視	常に — 譲れない基本要件です
トレーシング	ASP.NET Core では常に — リクエストトレース、EF Core スパン、HttpClient スパンは非常に有用です
ログ記録	アプリが ILogger<T>、Serilog、NLog、または log4net を使用している
プロファイリング	.NET 6 以降を使用する、パフォーマンスが重要なサービス
クロン	アプリが Hangfire、Quartz.NET、またはスケジュール済み Azure Functions を使用している

提案例：「エラー監視 + トレーシング + ログ記録のセットアップをおすすめします。プロファイリングやクロンも追加しますか？」

---

フェーズ 3：手順案内

オプション 1：ウィザード（推奨）

npx @sentry/wizard@latest -i dotnet

ウィザードで Sentry にログインし、組織とプロジェクトを選択して DSN を設定し、MSBuild によるシンボルのアップロードをセットアップします。これにより、本番環境で読みやすいスタックトレースを確認できます。

ウィザードの実行後は、確認に進んでください。

---

オプション 2：手動セットアップ

適切なパッケージをインストールする

# ASP.NET Core
dotnet add package Sentry.AspNetCore -v 6.1.0

# WPF or WinForms or Console
dotnet add package Sentry -v 6.1.0

# .NET MAUI
dotnet add package Sentry.Maui -v 6.1.0

# Blazor WebAssembly
dotnet add package Sentry.AspNetCore.Blazor.WebAssembly -v 6.1.0

# Azure Functions (Isolated Worker)
dotnet add package Sentry.Extensions.Logging -v 6.1.0
dotnet add package Sentry.OpenTelemetry -v 6.1.0

# Classic ASP.NET (System.Web / .NET Framework)
dotnet add package Sentry.AspNet -v 6.1.0

---

ASP.NET Core — Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.WebHost.UseSentry(options =>
{
    options.Dsn = Environment.GetEnvironmentVariable("SENTRY_DSN")
                  ?? "___YOUR_DSN___";
    options.Debug = true;                         // disable in production
    options.SendDefaultPii = true;                // captures user IP, name, email
    options.MaxRequestBodySize = RequestSize.Always;
    options.MinimumBreadcrumbLevel = LogLevel.Debug;
    options.MinimumEventLevel = LogLevel.Warning;
    options.TracesSampleRate = 1.0;               // tune to 0.1–0.2 in production
    options.SetBeforeSend((@event, hint) =>
    {
        @event.ServerName = null;                 // scrub hostname from events
        return @event;
    });
});

var app = builder.Build();
app.Run();

appsettings.json（代替設定）：

{
  "Sentry": {
    "Dsn": "___YOUR_DSN___",
    "SendDefaultPii": true,
    "MaxRequestBodySize": "Always",
    "MinimumBreadcrumbLevel": "Debug",
    "MinimumEventLevel": "Warning",
    "AttachStacktrace": true,
    "Debug": true,
    "TracesSampleRate": 1.0,
    "Environment": "production",
    "Release": "[email protected]"
  }
}

環境変数（区切り文字には二重アンダースコアを使用）：

export Sentry__Dsn="https://[email protected]/0"
export Sentry__TracesSampleRate="0.1"
export Sentry__Environment="staging"

---

WPF — App.xaml.cs

⚠️ 重要： OnStartup() ではなく、コンストラクターで初期化してください。コンストラクターはより早く実行されるため、より多くの障害パターンを捕捉できます。

using System.Windows;
using Sentry;

public partial class App : Application
{
    public App()
    {
        SentrySdk.Init(options =>
        {
            options.Dsn = "___YOUR_DSN___";
            options.Debug = true;
            options.SendDefaultPii = true;
            options.TracesSampleRate = 1.0;
            options.IsGlobalModeEnabled = true;   // required for all desktop apps
        });

        // Capture WPF UI-thread exceptions before WPF's crash dialog appears
        DispatcherUnhandledException += App_DispatcherUnhandledException;
    }

    private void App_DispatcherUnhandledException(
        object sender,
        System.Windows.Threading.DispatcherUnhandledExceptionEventArgs e)
    {
        SentrySdk.CaptureException(e.Exception);
        // Set e.Handled = true to prevent crash dialog and keep app running
    }
}

---

WinForms — Program.cs

using System;
using System.Windows.Forms;
using Sentry;

static class Program
{
    [STAThread]
    static void Main()
    {
        Application.EnableVisualStyles();
        Application.SetCompatibleTextRenderingDefault(false);

        // Required: allows Sentry to see unhandled WinForms exceptions
        Application.SetUnhandledExceptionMode(UnhandledExceptionMode.ThrowException);

        using (SentrySdk.Init(new SentryOptions
        {
            Dsn = "___YOUR_DSN___",
            Debug = true,
            TracesSampleRate = 1.0,
            IsGlobalModeEnabled = true,           // required for desktop apps
        }))
        {
            Application.Run(new MainForm());
        } // Disposing flushes all pending events
    }
}

---

.NET MAUI — MauiProgram.cs

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseSentry(options =>
            {
                options.Dsn = "___YOUR_DSN___";
                options.Debug = true;
                options.SendDefaultPii = true;
                options.TracesSampleRate = 1.0;
                // MAUI-specific: opt-in breadcrumbs (off by default — PII risk)
                options.IncludeTextInBreadcrumbs = false;
                options.IncludeTitleInBreadcrumbs = false;
                options.IncludeBackgroundingStateInBreadcrumbs = false;
            });

        return builder.Build();
    }
}

---

Blazor WebAssembly — Program.cs

var builder = WebAssemblyHostBuilder.CreateDefault(args);

builder.UseSentry(options =>
{
    options.Dsn = "___YOUR_DSN___";
    options.Debug = true;
    options.SendDefaultPii = true;
    options.TracesSampleRate = 0.1;
});

// Hook logging pipeline without re-initializing the SDK
builder.Logging.AddSentry(o => o.InitializeSdk = false);

await builder.Build().RunAsync();

---

Azure Functions（分離ワーカー）— Program.cs

using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using OpenTelemetry.Trace;
using Sentry.OpenTelemetry;

var host = new HostBuilder()
    .ConfigureFunctionsWorkerDefaults()
    .ConfigureServices(services =>
    {
        services.AddOpenTelemetry().WithTracing(builder =>
        {
            builder
                .AddSentry()                        // route OTel spans to Sentry
                .AddHttpClientInstrumentation();    // capture outgoing HTTP
        });
    })
    .ConfigureLogging(logging =>
    {
        logging.AddSentry(options =>
        {
            options.Dsn = "___YOUR_DSN___";
            options.Debug = true;
            options.TracesSampleRate = 1.0;
            options.UseOpenTelemetry();                     // let OTel drive tracing
            options.DisableSentryHttpMessageHandler = true; // prevent duplicate HTTP spans
        });
    })
    .Build();

await host.RunAsync();

---

AWS Lambda — LambdaEntryPoint.cs

public class LambdaEntryPoint : APIGatewayProxyFunction
{
    protected override void Init(IWebHostBuilder builder)
    {
        builder
            .UseSentry(options =>
            {
                options.Dsn = "___YOUR_DSN___";
                options.TracesSampleRate = 1.0;
                options.FlushOnCompletedRequest = true; // REQUIRED for Lambda
            })
            .UseStartup<Startup>();
    }
}

---

従来の ASP.NET — Global.asax.cs

public class MvcApplication : HttpApplication
{
    private IDisposable _sentry;

    protected void Application_Start()
    {
        _sentry = SentrySdk.Init(options =>
        {
            options.Dsn = "___YOUR_DSN___";
            options.TracesSampleRate = 1.0;
            options.AddEntityFramework(); // EF6 query breadcrumbs
            options.AddAspNet();          // Classic ASP.NET integration
        });
    }

    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：.csproj または Directory.Build.props に MSBuild プロパティを追加する：

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <SentryOrg>___ORG_SLUG___</SentryOrg>
  <SentryProject>___PROJECT_SLUG___</SentryProject>
  <SentryUploadSymbols>true</SentryUploadSymbols>
  <SentryUploadSources>true</SentryUploadSources>
  <SentryCreateRelease>true</SentryCreateRelease>
  <SentrySetCommits>true</SentrySetCommits>
</PropertyGroup>

手順 3：CI で SENTRY_AUTH_TOKEN を設定する：

# GitHub Actions
- name: Build & upload symbols
  run: dotnet build -c Release
  env:
    SENTRY_AUTH_TOKEN: ${{ secrets.SENTRY_AUTH_TOKEN }}

---

合意した各機能について

対応するリファレンスファイルを読み込み、手順に従ってください。

機能	リファレンスファイル	読み込むタイミング...
エラー監視	references/error-monitoring.md	常に — CaptureException、スコープ、情報の付加、フィルタリング
トレーシング	references/tracing.md	サーバーアプリ、分散トレーシング、EF Core スパン、カスタム計測
プロファイリング	references/profiling.md	.NET 6 以降を使用するパフォーマンスが重要なアプリ
ロギング	references/logging.md	ILogger<T>、Serilog、NLog、log4net との統合
Cron	references/crons.md	Hangfire、Quartz.NET、またはスケジュールされた関数の監視

機能ごとに、リファレンスファイルを読み、記載された手順に正確に従い、次に進む前に検証してください。

---

検証

ウィザードまたは手動でのセットアップ後、テスト用の例外を発生させ、検証後に削除してください。

// ASP.NET Core: add a temporary endpoint
app.MapGet("/sentry-test", () =>
{
    throw new Exception("Sentry test error — delete me");
});

// Or capture explicitly anywhere
SentrySdk.CaptureException(new Exception("Sentry test error — delete me"));

次に、Sentry Issues ダッシュボードを確認します。エラーは約 30 秒以内に表示されます。

検証チェックリスト：

確認項目	方法
例外が捕捉される	テスト用の例外を発生させ、Sentry Issues で確認する
スタックトレースが読みやすい	ファイル名と行番号が表示されていることを確認する
トレーシングが有効	Performance タブでトランザクションを確認する
ロギングが接続されている	ILogger でエラーをログに記録し、Sentry のブレッドクラムとして表示されることを確認する
シンボルが正常にアップロードされる	スタックトレースに <unknown> ではなく Controllers/HomeController.cs:42 と表示される

---

設定リファレンス

SentryOptions の基本設定

オプション	型	デフォルト	環境変数	備考
Dsn	string	—	SENTRY_DSN	必須です。設定されていない場合、SDK は無効になります。
Debug	bool	false	—	SDK の診断出力です。本番環境では無効にしてください。
DiagnosticLevel	SentryLevel	Debug	—	Debug、Info、Warning、Error、Fatal
Release	string	自動	SENTRY_RELEASE	アセンブリのバージョンと git SHA から自動検出されます
Environment	string	"production"	SENTRY_ENVIRONMENT	デバッガーが接続されている場合は "debug" です
Dist	string	—	—	ビルドのバリアントです。最大 64 文字です。
SampleRate	float	1.0	—	エラーイベントのサンプリング率（0.0～1.0）
TracesSampleRate	double	0.0	—	トランザクションのサンプリングです。有効にするには > 0 にする必要があります。
TracesSampler	Func<SamplingContext, double>	—	—	トランザクションごとの動的サンプラーです。TracesSampleRate より優先されます
ProfilesSampleRate	double	0.0	—	プロファイリングするトレース済みトランザクションの割合です。Sentry.Profiling が必要です。
SendDefaultPii	bool	false	—	ユーザーの IP、名前、メールアドレスを含めます
AttachStacktrace	bool	true	—	すべてのメッセージにスタックトレースを添付します
MaxBreadcrumbs	int	100	—	イベントごとに保存するパンくずの最大数です
IsGlobalModeEnabled	bool	false*	—	*MAUI、Blazor WASM では自動的に true になります。WPF、WinForms、Console では 必ず true にしてください。
AutoSessionTracking	bool	false*	—	*MAUI では自動的に true になります。リリースヘルスを有効にするには設定してください。
CaptureFailedRequests	bool	true	—	HTTP クライアントのエラーを自動キャプチャします
CacheDirectoryPath	string	—	—	オフラインイベントのキャッシュディレクトリです
ShutdownTimeout	TimeSpan	—	—	シャットダウン時にイベントのフラッシュを待機する最大時間です
HttpProxy	string	—	—	Sentry リクエスト用のプロキシ URL です
EnableBackpressureHandling	bool	true	—	配信に失敗した場合、サンプリング率を自動的に下げます

ASP.NET Core の拡張オプション（SentryAspNetCoreOptions）

オプション	型	デフォルト	備考
MaxRequestBodySize	RequestSize	None	None、Small（約 4 KB）、Medium（約 10 KB）、Always
MinimumBreadcrumbLevel	LogLevel	Information	パンくずとして記録する最小ログレベルです
MinimumEventLevel	LogLevel	Error	Sentry イベントとして送信する最小ログレベルです
CaptureBlockingCalls	bool	false	.Wait() / .Result によるスレッドプールの枯渇を検出します
FlushOnCompletedRequest	bool	false	Lambda／サーバーレスでは必須です
IncludeActivityData	bool	false	System.Diagnostics.Activity の値をキャプチャします

MAUI の拡張オプション（SentryMauiOptions）

オプション	型	デフォルト	備考
IncludeTextInBreadcrumbs	bool	false	Button、Label、Entry 要素のテキストです。⚠️ PII のリスクがあります。
IncludeTitleInBreadcrumbs	bool	false	Window、Page 要素のタイトルです。⚠️ PII のリスクがあります。
IncludeBackgroundingStateInBreadcrumbs	bool	false	Window.Backgrounding イベントの状態です。⚠️ PII のリスクがあります。

環境変数

変数	用途
SENTRY_DSN	プロジェクトの DSN
SENTRY_RELEASE	アプリのバージョン（例：[email protected]）
SENTRY_ENVIRONMENT	デプロイ環境の名前
SENTRY_AUTH_TOKEN	MSBuild / sentry-cli のシンボルアップロード用認証トークン

**ASP.NET Core：**階層の区切り文字として二重アンダースコア __ を使用します。

export Sentry__Dsn="https://..."
export Sentry__TracesSampleRate="0.1"

MSBuild シンボルアップロードのプロパティ

プロパティ	型	デフォルト	説明
SentryOrg	string	—	Sentry 組織のスラッグ
SentryProject	string	—	Sentry プロジェクトのスラッグ
SentryUploadSymbols	bool	false	スタックトレースに行番号を表示するため、PDB ファイルをアップロードします
SentryUploadSources	bool	false	ソースコンテキスト用にソースファイルをアップロードします
SentryCreateRelease	bool	false	ビルド時に Sentry リリースを自動作成します
SentrySetCommits	bool	false	Git コミットをリリースに関連付けます
SentryUrl	string	—	セルフホスト版 Sentry の URL

---

フェーズ 4：相互リンク

.NET のセットアップが完了したら、関連するフロントエンドプロジェクトを確認します。

# Check for frontend in adjacent directories
ls ../frontend ../client ../web ../app 2>/dev/null

# Check for JavaScript framework indicators
cat ../package.json 2>/dev/null | grep -E '"next"|"react"|"vue"|"nuxt"' | head -3

フロントエンドが見つかった場合は、対応する SDK スキルを提案します。

検出されたフロントエンド	提案するスキル
Next.js（package.json に "next" がある）	sentry-nextjs-sdk
React SPA（"next" を含まず、"react" がある）	@sentry/react — docs.sentry.io/platforms/javascript/guides/react/ を参照
Vue.js	@sentry/vue — docs.sentry.io/platforms/javascript/guides/vue/ を参照
Nuxt	@sentry/nuxt — docs.sentry.io/platforms/javascript/guides/nuxt/ を参照

フロントエンドとバックエンドを同じ Sentry プロジェクトに接続すると、分散トレーシングが利用できます。ブラウザー、.NET サーバー、および下流の API をまたぐ単一のトレースビューを確認できます。

---

トラブルシューティング

問題	原因	解決策
イベントが表示されない	DSN の設定ミス	Debug = true を設定し、コンソール出力で SDK の診断メッセージを確認します
スタックトレースにファイル名や行番号が表示されない	PDB ファイルがアップロードされていない	.csproj に SentryUploadSymbols=true を追加し、CI で SENTRY_AUTH_TOKEN を設定します
WPF／WinForms の例外が記録されない	IsGlobalModeEnabled が設定されていない	SentrySdk.Init() で options.IsGlobalModeEnabled = true を設定します
Lambda／サーバーレスのイベントが失われる	フラッシュ前にコンテナーがフリーズする	options.FlushOnCompletedRequest = true を設定します
WPF の UI スレッド例外が記録されない	DispatcherUnhandledException が登録されていない	コンストラクター（OnStartup ではなく）で App.DispatcherUnhandledException を登録します
Azure Functions で HTTP スパンが重複する	Sentry と OTel の両方が HTTP を計測している	options.DisableSentryHttpMessageHandler = true を設定します
TracesSampleRate が反映されない	レートが 0.0（デフォルト）になっている	トレーシングを有効にするには TracesSampleRate > 0 を設定します
appsettings.json の値が無視される	設定キーの形式が誤っている	フラット形式のキー "Sentry:Dsn" または環境変数 Sentry__Dsn（アンダースコア 2 つ）を使用します
BeforeSend がすべてのイベントを破棄する	フックが無条件に null を返している	フィルターロジックを確認し、破棄するイベントに対してのみ null を返します
MAUI のネイティブクラッシュが記録されない	パッケージが誤っている	Sentry だけでなく、Sentry.Maui がインストールされていることを確認します