Documentation Center

Best Practices

Following advised best practices when creating new background task handler will allow you to get the best out of your customization.

  • Throw the BackgroundTaskException with the specific error number to inform the background task service when the handler cannot finish execution successfully. An exception thrown by a handler informs the background task service that handler could not fulfil it's task. The service will use, if configured, the error number to re-try the execution. Once the task cannot be re-tried any more, the service will move it to the "Failed" status. Any exception that does not have an error number thrown by the handler will be treated as if it had error number "-1".
  • When handler cannot finish successfully, use IBackgroundTaskHandlerContext.WillRetryOnError method to know if you can end the event. Normally, has the handler finished successfully or not, you should end the event. However, you should remember that in case the handler failed to execute, the background task service can re-try it. In this case you should postpone ending the event until you know the service will not re-try the execution anymore.
  • When passing the stream, encode it with Unicode (UTF-16) with the byte order mark. The byte order mark indicates the encoding of the stream. Without it, you might not be able to decode it properly.
  • Avoid opening transactions explicitly. Accessing the application uising standard endpoints will open the transaction for you.