🧩 Como Exibir Erros com Detalhes Técnicos no Dataverse Usando Xrm.Navigation.openErrorDialog
Em projetos com Microsoft Dataverse e Power Apps model-driven, é comum criar botões personalizados na faixa de opções (ribbon) para executar ações via API Web. Mas o que acontece quando uma chamada de API falha? Como informar o erro ao usuário de forma clara e profissional — e ainda oferecer a opção de baixar os detalhes do erro para análise?
Neste post, mostro a abordagem recomendada utilizando a API Xrm.Navigation.openErrorDialog.
🎯 O cenário
Você criou um botão na ribbon que:
-
Realiza uma chamada à API Web personalizada
-
Pode retornar um erro (ex:
404,500,Unauthorized, etc.) -
Precisa:
-
Exibir uma mensagem amigável para o usuário
-
Exibir detalhes técnicos do erro
-
Permitir baixar um arquivo de log
-
✅ A solução: Xrm.Navigation.openErrorDialog
A função openErrorDialog da API do cliente (Client API) permite exibir uma caixa de diálogo de erro com dois campos principais:
Xrm.Navigation.openErrorDialog({
message: "Ocorreu um erro durante a requisição.",
details: error.message
});
🔍 Entendendo os parâmetros:
-
message: Mensagem amigável, que o usuário consegue entender. -
details: Mensagem técnica — geralmente capturada da exceção (error.message) — que será incluída no arquivo de log.
Quando o parâmetro details está presente, a caixa de diálogo oferece automaticamente o botão "Baixar Arquivo de Log" com as informações técnicas do erro. Isso é extremamente útil para suporte e diagnóstico.
❌ O que não usar
Outras opções como Xrm.Navigation.openAlertDialog apenas exibem mensagens simples — não incluem o botão de log, nem foram pensadas para tratamento de erros técnicos.
Exemplo que não exibe o botão de log:
Xrm.Navigation.openErrorDialog({
message: "Ocorreu um erro durante a requisição."
});
📌 Dica extra
Certifique-se de que o error.message esteja corretamente definido. Em chamadas fetch, axios, ou XMLHttpRequest, o conteúdo do erro pode estar em campos diferentes — adapte conforme necessário:
catch(error) {
const errorMessage = error?.message || "Erro desconhecido";
Xrm.Navigation.openErrorDialog({
message: "Não foi possível completar a ação.",
details: errorMessage
});
}
🧠 Conclusão
A função Xrm.Navigation.openErrorDialog é a maneira recomendada para lidar com erros em ações personalizadas em Power Apps Model-Driven. Ela melhora a experiência do usuário, oferece transparência e facilita o suporte técnico com a possibilidade de baixar logs.
