DataSource API: Error Handling

you are here (click to zoom) - discover the stack

Custom DataSources sometimes need to throw an error, for example if a SQL isn't found, a remote WebAPI fails or the configuration is faulty.

Since 2sxc 11.13 we changed the behavior so that DataSource Errors will not break code execution but just make the stream contain just one Error entity. This helps a lot in debugging.

You Don't Have to Do Anything

If your code just raises a .net Exception, the execution engine will catch this and wrap it in an error. The Exception will also be logged to Insights for the admin/developer to see.

...but You can do Better

Instead of raising the normal exception, your DataSource can also return an ErrorStream which contains more specific information about the problem. This greatly helps the developer (and that could be you 😉) figure out what to fix. There are three tools at your disposal:

The Error property (DataSourceErrorHelper) to create error streams
The TryGetIn() helper to get an In stream which must be available - or null so you can return an error

Read the API docs above or check out examples in the 2sxc EAV code base for more guidance.

Example using TryGetIn

TryGetIn ensures that we get a stream we really need, or null if something went wrong.

private IEnumerable<IEntity> GetEntities()
{
  // This will resolve the tokens before starting
  Configuration.Parse();

  var source = TryGetIn();
  if (source is null) return Error.TryGetInFailed(this);

  var results = ...;

  return results;
}

Create Custom Error Messages

If you need an error which is not a predefined type, you can create your own using Error.Create:

Demo App and further links

todo

History

Introduced in EAV / 2sxc 11.13
Error API completely rewritten in 2sxc 15 (breaking change)

Table of Contents