• /
  • EnglishEspañolFrançais日本語한국어Português
  • EntrarComeçar agora

Esta tradução de máquina é fornecida para sua comodidade.

Caso haja alguma divergência entre a versão em inglês e a traduzida, a versão em inglês prevalece. Acesse esta página para mais informações.

Criar um problema

Simbolizar erros C# do .NET MAUI

|View as Markdown (English)

As compilações de release de aplicativos .NET MAUI para Android e iOS não incluem informações de depuração, portanto, os stack trace em C# que o seu aplicativo relata mostram o nome do método, mas não o arquivo de origem ou o número da linha. O New Relic pode simbolizar esses stack trace no seu navegador quando você fornece os arquivos .pdb e .dll correspondentes dessa compilação. A simbolização no navegador aplica-se apenas a exceções tratadas.

Esta página explica:

  • Como stack trace C# simbolizados e não simbolizados se comparam
  • Como gerar os arquivos .pdb e .dll e onde encontrá-los
  • Como simbolizar um stack trace na interface do New Relic
  • Onde encontrar falhas nativas do iOS na interface do New Relic e como simbolizá-las
  • Como armazenar esses arquivos para que você possa simbolizar erros de qualquer versão lançada

Importante

A simbolização é executada inteiramente no seu navegador. O New Relic não faz upload, não armazena nem mantém seus arquivos .pdb ou .dll ou o stack trace simbolizado. O resultado também não é compartilhado entre os erros: você faz o upload dos arquivos separadamente para cada erro que abre e novamente sempre que recarrega a página ou volta a ela mais tarde. Como você precisará dos arquivos todas as vezes, mantenha-os para cada versão.

O que a simbolização adiciona

Antes da simbolização, cada frame mostra <unknown> onde o arquivo e o número da linha estariam:

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

Após a simbolização, o frame mostra o arquivo de origem e um número de linha:

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

A coluna Thread ao lado de cada frame mostra a classe à qual o frame pertence, por exemplo, NewRelicMaui.MainPage.

Cuidado

O número da linha é onde o método começa (sua primeira instrução), não a linha exata que lançou a exceção. O stack trace que o New Relic recebe dos aplicativos .NET MAUI não inclui o deslocamento IL que identificaria a linha dentro do método. Use o número da linha para encontrar o método no seu código-fonte e, em seguida, procure a causa nesse método.

Entenda os arquivos de símbolo do .NET MAUI

Um aplicativo .NET MAUI contém tanto código C# gerenciado quanto código nativo da plataforma, e cada um tem seu próprio tipo de arquivo de símbolo de depuração. Cada arquivo apenas simboliza os erros de seu próprio código:

ArquivoPlataformaO que ele simbolizaOnde é criadoComo usá-lo no New Relic
.pdb + .dll (PDB portátil e seu assembly)Android, iOSErros de C# do seu aplicativo e das bibliotecas de classesbin/Release/<target framework>/, consulte Localizar os arquivos de saídaFaça o upload no navegador, conforme descrito nesta página
.dSYMiOSFalhas nativas do iOSbin/Release/net10.0-ios/ios-arm64/<YourApp>.app.dSYMCarregar arquivos dSYM

O New Relic usa apenas os arquivos .pdb e .dll para simbolizar erros em C#. Fazer o upload de um dSYM para um erro em C# não o simbolizará. No entanto, mantenha todos eles para cada versão, para que você possa simbolizar todos os tipos de erro que a versão relata.

Gere o .pdb e .dll

Habilitar PDBs portáteis para builds de release

No .csproj do seu aplicativo, certifique-se de que as compilações de Release produzam símbolos de depuração portáteis:

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

A compilação gera PDBs portáteis junto ao assembly. Eles não são empacotados no seu APK, AAB ou IPA, portanto, não aumentam o tamanho do seu aplicativo.

Adicione as mesmas configurações a quaisquer projetos de biblioteca de classes cujo código você deseja simbolizar.

Compile sua versão

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

Use o framework de destino do seu projeto (por exemplo, net9.0-android).

Encontre os arquivos de saída

Para cada assembly que aparece em seu stack trace, você precisa do respectivo .dll e do .pdb correspondente. Eles estão na pasta de saída de build, nomeados de acordo com o seu projeto:

PlataformaLocalização
Androidbin/Release/net10.0-android/
iOSbin/Release/net10.0-ios/ios-arm64/ (ios-arm64 é a pasta para dispositivos físicos. Não use iossimulator-arm64.)

Por exemplo, se o projeto do seu aplicativo é NewRelicMaui, você precisa de NewRelicMaui.dll e NewRelicMaui.pdb. Para descobrir de qual assembly um frame vem, observe o namespace no frame: NewRelicMaui.MainPage.OnHandledExceptionClicked está em NewRelicMaui.dll. Se um frame vier da sua própria biblioteca de classes, como MyApp.Core, use MyApp.Core.dll e MyApp.Core.pdb.

dotnet publish coloca seu APK, AAB ou IPA em uma subpasta publish/. Os arquivos .dll e .pdb estão na pasta acima dela, nos locais indicados na tabela.

Você também pode encontrar cópias desses arquivos em obj/Release/. Sempre faça o upload de .dll e .pdb juntos da mesma pasta na tabela, para que correspondam um ao outro.

Cuidado

No iOS, o .dll não deve ser extraído de dentro do pacote do aplicativo (NewRelicMaui.app/) ou do IPA. As compilações de Release reduzem e removem essa cópia, de modo que ela não corresponda mais a nenhum .pdb, e o pacote não inclua um .pdb.

Simbolizar um stack trace no New Relic

Abra o erro

O erro de C# deve ser aberto a partir de qualquer um dos locais:

Role até a seção Stack trace.

Observe o appVersion e o appBuild do erro. Eles informam de quais arquivos da versão você precisa.

Faça o upload do .pdb e .dll

Acima do stack trace, o banner Not seeing what you expected? oferece simbolização sob demanda. Clique em Upload .pdb and .dll files e selecione tanto o .pdb quanto o .dll para o assembly no stack trace. Se o stack trace incluir frames de mais de um dos seus assemblies, por exemplo, seu aplicativo e uma biblioteca de classes, selecione o .pdb e o .dll para cada um deles. Ambos os arquivos são obrigatórios: o .dll identifica o assembly e seus métodos, e o .pdb mapeia cada método para seu arquivo de origem e linha.

Screenshot of an unsymbolicated .NET MAUI C# stack trace with the Upload .pdb and .dll files button

Antes da simbolicação, o frame mostra <unknown> onde o arquivo de origem e o número da linha estariam.

Os arquivos selecionados aparecem ao lado do botão. Verifique se ambos estão listados (remova um incorreto com ×), depois clique em Symbolicate.

Revise ou exporte o resultado

Quando a simbolização termina, o banner muda para Symbolicated your trace e relata quantos frames foram resolvidos, por exemplo, Symbolicated 1 of 1 unresolved frame. Ele também lembra você de que os frames são resolvidos para o início de seu método, não para a linha exata que lançou o erro.

Screenshot of a .NET MAUI C# stack trace after symbolication, showing MainPage.xaml.cs line 41

Após a simbolização, o frame mostra o arquivo de origem e a linha onde o método começa.

O resultado dura apenas enquanto a página está aberta. Para mantê-lo, clique em Export handled exception details. A exportação inclui os frames simbolizados, para que você possa anexá-la a um ticket ou compartilhá-la com a sua equipe.

Para simbolizar outro erro, abra-o e faça o upload dos arquivos novamente. O resultado de um erro não é transferido para os outros.

Simbolicar falhas nativas do iOS

As falhas nativas do iOS, como uma falha em Objective-C, Swift ou no tempo de execução do iOS, não são erros C#; portanto, os arquivos .pdb e .dll não se aplicam a elas. Em vez disso, essas falhas usam o arquivo .dSYM do iOS.

Para encontrar falhas nativas do iOS na interface do New Relic, acesse one.newrelic.com > Mobile > (select your app) > Crashes e, em seguida, selecione a falha. Se o dSYM dessa compilação não estiver disponível para o New Relic, o stack trace mostra código de máquina (endereços de memória) em vez de nomes de métodos legíveis, e o relatório de falhas mostra o aviso We were unable to locate your dsym.

Screenshot of the Stack trace section of a .NET MAUI native iOS crash on the Crashes page, showing memory addresses such as 0x108d84944 instead of method names

Sem o dSYM, os frames nativos do iOS mostram endereços de memória em vez de nomes de métodos.

Para corrigir isso:

  1. Encontre o .dSYM para a compilação que falhou, conforme descrito em Entenda os arquivos de símbolo do .NET MAUI. Corresponda-o ao appVersion e appBuild da falha.
  2. Faça o upload para o New Relic seguindo Fazer upload de arquivos dSYM.

Encontre os arquivos certos

Um par .dll e .pdb fornece resultados corretos apenas para stack traces da compilação que o produziu:

  1. Release: associe o appVersion e o appBuild do erro aos arquivos que você salvou para essa release.
  2. Plataforma: use os arquivos do Android para erros do Android e os arquivos do iOS para erros do iOS.
  3. Assembly: faça a correspondência do namespace no frame da stack com o nome do assembly, conforme descrito em Encontrar os arquivos de saída.
  4. Mesma compilação: corresponda o .pdb à compilação que produziu o .dll. Não misture arquivos de compilações diferentes.

Cuidado

Como o stack trace não inclui um ID de assembly, a New Relic nem sempre consegue identificar que os arquivos vêm de uma compilação diferente. Arquivos de outra versão do seu aplicativo ainda podem produzir um resultado, com números de linha que apontam para o lugar errado se o código tiver sido alterado. Até mesmo adicionar uma única linha de comentário acima de um método desloca o seu número de linha. Certifique-se de que os arquivos correspondam a appVersion e appBuild do erro antes de confiar no resultado.

Prática recomendada: armazene símbolos para cada versão

O New Relic não mantém seus arquivos .pdb e .dll, portanto, você precisa armazená-los por conta própria. Salve-os ao compilar cada versão, não depois que um erro aparecer.

  • Mantenha os arquivos de cada compilação que você distribui, incluindo compilações internas, beta e de loja, tanto para Android quanto para iOS.
  • Mantenha todos os tipos de arquivo de símbolos, incluindo os dSYMs do iOS. Consulte Entenda os arquivos de símbolos do .NET MAUI.
  • Inclua suas próprias bibliotecas de classes, não apenas o assembly principal do aplicativo.
  • Eles devem ser rotulados por plataforma, versão e número de build, correspondendo aos atributos appVersion e appBuild que o seu aplicativo reporta, para que você possa encontrar os arquivos corretos para um erro.
  • Mantenha-os enquanto essa versão estiver em uso. Os usuários frequentemente permanecem em versões antigas por meses.
  • Restrinja o acesso. Os PDBs revelam os caminhos dos seus arquivos de código-fonte e a estrutura do código. Armazene-os com os mesmos controles de acesso que o seu código-fonte.

Onde você os armazena depende de você, por exemplo, os artefatos de compilação do seu sistema de CI, um bucket de armazenamento ou um repositório de artefatos. Se você usar artefatos de compilação de CI, verifique por quanto tempo seu sistema de CI os mantém, pois muitos os excluem automaticamente após um tempo definido.

Cuidado

Uma recompilação produz arquivos idênticos apenas se o código-fonte, as dependências, a versão do SDK e as configurações de compilação forem todos exatamente iguais. Salve os arquivos da compilação que você realmente distribuiu. Não conte em recriá-los.

Resolução de problemas

Limitações

  • Os frames são resolvidos para o início de seu método, não para a linha exata que lançou a exceção.
  • A simbolização se aplica a erros C#. As falhas nativas do Android (Java/Kotlin) e do iOS usam os fluxos de trabalho de simbolização do Android e do iOS.
  • Os resultados não são salvos ou compartilhados entre erros. Você precisa fazer o upload dos arquivos para cada erro, toda vez que o visualizar.
Copyright © 2026 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.