🧩 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.