Use InvalidPluginExecutionException in plug-ins and workflow activities
Category: Supportability, Usability
Impact potential: Medium
Symptoms
If a synchronous plug-in returns an exception other than InvalidPluginExecutionException back to the platform, in a Power Apps client an error is displayed to the user with the message of the exception Message and the stack trace. This provides an unfriendly user experience in what is likely already a frustrating situation.
If you are using InvalidPluginExecutionException to intentionally cancel the operation because of data validation logic issue, you should provide guidance applicable to the application user so that they can correct the issue and continue.
If the error is unexpected, it is still recommended to catch the exception, convert it into a InvalidPluginExecutionException, and then throw the new exception so that applications can show a friendly error message with guidance to help a user or technical staff quickly identify the issue.
Guidance
Plug-ins should only return an InvalidPluginExecutionException for the following reasons:
- Show a useful message to the user
- Avoiding event log/trace file bloat
A thrown InvalidPluginExecutionException returns to the caller with a friendly message and an IsvAborted error code. Failure to catch and convert an exception into a InvalidPluginExecutionException will result in an IsvUnExpected error code with no friendly message displayed to the user from a Power Apps client.
Handle errors from functions called in plug-ins
Within your plug-in you will commonly call other functions to re-use code. How you handle errors in these functions is very important because an unhandled error may cause the worker process to crash. This will not only terminate your plug-in, but may also terminate any concurrent plug-ins running for your organization. More information: Error: Sandbox Worker process crashed
Problematic patterns
Warning
These patterns should be avoided.
Do not use HTML within error message text.
Web applications which access Dataverse data should HTML encode any error message text before they display it to a user. This will prevent any HTML in your message from rendered as you intend. It will just show the HTML code.