.NET MAUI C# エラーをシンボル化する

AndroidおよびiOS向けの.NET MAUIアプリのリリースビルドにはデバッグ情報が含まれていないため、アプリが報告するC#のスタックトレースにはメソッド名は表示されますが、ソースファイルや行番号は表示されません。そのビルドの対応する.pdbおよび.dllファイルを提供すると、New Relicはブラウザ上でこれらのスタックトレースをシンボル化できます。ブラウザ内でのシンボル化は、処理された例外にのみ適用されます。

このページでは、以下について説明します：

• シンボル化されたC#のスタックトレースとシンボル化されていないC#のスタックトレースの比較
• .pdbファイルと.dllファイルを生成する方法と見つける場所
• New Relic UIでスタックトレースをシンボル化する方法
• New Relic UIでネイティブiOSのクラッシュを見つける場所と、それらをシンボリケートする方法
• 出荷したすべてのリリースのエラーをシンボル化できるように、これらのファイルを保存する方法

シンボル化によって追加されるもの

シンボリケーションを行う前は、各フレームのファイルと行番号が表示される場所に<unknown>が表示されます：

<unknown> in NewRelicMaui.MainPage.OnHandledExceptionClicked(Object sender, EventArgs e)()

シンボリケーションを行った後は、フレームにソースファイルと行番号が表示されます：

MainPage.xaml.cs line 41 in NewRelicMaui.MainPage.OnHandledExceptionClicked()

各フレームの横にあるThread列には、そのフレームが属するクラス（たとえばNewRelicMaui.MainPageなど）が表示されます。

.NET MAUIシンボルファイルについて

.NET MAUIアプリにはマネージドC#コードとネイティブプラットフォームコードの両方が含まれており、それぞれに独自のデバッグシンボルファイルがあります。各ファイルは、独自のコードからのエラーのみをシンボル化します：

New Relicは、C#エラーをシンボル化するために.pdbおよび.dllファイルのみを使用します。C#エラーにdSYMをアップロードしても、シンボル化されません。ただし、リリースが報告するあらゆる種類のエラーをシンボリケートできるように、リリースごとにそれらをすべて保持してください。

.pdbを生成し、 .dll

<PropertyGroup Condition="'$(Configuration)' == 'Release'">
  <DebugType>portable</DebugType>
  <DebugSymbols>true</DebugSymbols>
</PropertyGroup>

$
# Android
$
dotnet publish -f net10.0-android -c Release
$

$
# iOS
$
dotnet publish -f net10.0-ios -c Release

New Relicでスタックトレースをシンボリケートする

エラーを開く

どちらかの場所からC#のエラーを開きます：

• one.newrelic.com > Errors Inbox、次にエラーを選択します。
• one.newrelic.com > Mobile > (select your app) > Handled exceptions、次にエラーを選択します。

Stack traceセクションまでスクロールします。

エラーのappVersionとappBuildを確認してください。これらにより、どのリリースのファイルが必要かがわかります。

.pdb をアップロードし、 .dll

スタックトレースの上にあるNot seeing what you expected?バナーでは、オンデマンドのシンボル化を利用できます。Upload .pdb and .dll filesをクリックし、スタックトレース内のアセンブリの.pdbと.dllの両方を選択します。スタックトレースに複数のアセンブリ（アプリやクラスライブラリなど）のフレームが含まれている場合は、それぞれの.pdbと.dllを選択します。両方のファイルが必要です：.dllはアセンブリとそのメソッドを識別し、.pdbは各メソッドをソースファイルと行にマッピングします。

選択したファイルがボタンの横に表示されます。両方がリストされていることを確認し（間違っているものは×で削除します）、Symbolicateをクリックします。

結果を確認またはエクスポートする

シンボリケーションが完了すると、バナーがSymbolicated your traceに変わり、解決されたフレーム数（例：Symbolicated 1 of 1 unresolved frame）が報告されます。また、フレームは例外をスローした正確な行ではなく、メソッドの先頭に解決されることも通知されます。

結果はページが開いている間のみ保持されます。保持するには、Export handled exception detailsをクリックします。エクスポートにはシンボル化されたフレームが含まれるため、チケットに添付したり、チームと共有したりできます。

別のエラーをシンボリケートするには、そのエラーを開いてファイルを再度アップロードしてください。1つのエラーの結果は、他のエラーには引き継がれません。

ネイティブiOSクラッシュのシンボル化

Objective-C、Swift、またはiOSランタイムでのクラッシュなどのネイティブiOSのクラッシュはC#のエラーではないため、.pdbおよび.dllファイルは適用されません。これらのクラッシュでは、代わりにiOSの.dSYMファイルが使用されます。

New Relic UIでネイティブiOSクラッシュを見つけるには、one.newrelic.com > Mobile > (select your app) > Crashesに移動して、クラッシュを選択します。そのビルドのdSYMがNew Relicで利用できない場合、スタックトレースには読み取り可能なメソッド名ではなくマシンコード（メモリアドレス）が表示され、クラッシュレポートには警告が表示されます We were unable to locate your dsym.

修正するには：

1. 「.NET MAUIシンボルファイルを理解する」で説明されているように、クラッシュしたビルドの.dSYMを見つけます。それをクラッシュのappVersionとappBuildに一致させます。
2. dSYMファイルのアップロードの手順に従って、New Relicにアップロードしてください。

適切なファイルを見つける

.dll と .pdb のペアは、それを生成したビルドからのスタックトレースに対してのみ正しい結果を提供します：

1. リリース：エラーのappVersionとappBuildを、そのリリース用に保存したファイルと照合してください。
2. プラットフォーム：AndroidのエラーにはAndroidファイルを、iOSのエラーにはiOSファイルを使用してください。
3. アセンブリ：「出力ファイルを見つける」で説明されているように、スタックフレーム内のネームスペースとアセンブリ名を照合してください。
4. 同じビルド：.pdbを、.dllを生成したビルドと一致させてください。異なるビルドのファイルを混在させないでください。

ベストプラクティス：すべてのリリースでシンボルを保存する

New Relicは.pdbファイルと.dllファイルを保持しないため、ご自身で保存する必要があります。エラーが発生した後ではなく、各リリースをビルドする際に保存してください。

• 配布するすべてのビルドのファイルを保管してください。これには、AndroidとiOSの両方の内部ビルド、ベータ版、ストアビルドが含まれます。
• iOSのdSYMを含め、すべての種類のシンボルファイルを保持してください。「.NET MAUIシンボルファイルを理解する」を参照してください。
• メインアプリのアセンブリだけでなく、独自のクラスライブラリを含めてください。
• エラーの適切なファイルを見つけられるように、アプリが報告するappVersionおよびappBuild属性と一致させて、プラットフォーム、バージョン、ビルド番号でラベル付けしてください。
• そのバージョンが使用されている間は、それらを保持してください。ユーザーは何ヶ月も古いバージョンを使い続けることがよくあります。
• アクセスを制限します。PDBにより、ソースファイルのパスとコード構造が明らかになります。ソースコードと同じアクセス制御で保存してください。

どこに保存するかは任意です。たとえば、CIシステムのビルドアーティファクト、ストレージバケット、アーティファクトリポジトリなどです。CIビルドアーティファクトを使用する場合は、CIシステムがそれらを保持する期間を確認してください。多くのシステムでは、一定時間後に自動的に削除されるためです。

トラブルシューティング

制限

• フレームは、スローした正確な行ではなく、メソッドの先頭に解決されます。
• シンボリケーションはC#エラーに適用されます。ネイティブAndroid（Java/Kotlin）およびiOSのクラッシュでは、AndroidおよびiOSのシンボリケーションワークフローを使用します。
• 結果は保存されず、エラー間で共有されることもありません。エラーを表示するたびに、エラーごとにファイルをアップロードする必要があります。