Dealing with errors
This article provides an overview of the various error handling mechanisms available in Carmenta Engine. The different methods described here have evolved over time, some were meant to work together with others, and some were meant to replace existing methods.
Which of these you should use in your application depends, but hopefully this overview will help you implementing good, robust error handling in your application.
Errors on API calls
If you write your application without considering error handling at all, Carmenta Engine will throw an exception whenever you call a method or property, and that method or property encounters an error. If you don't catch these exceptions in your code, the application will be terminated, probably without any meaningful error message to the user.
There is no indication of how serious an exception is. In most cases the exception type will be EngineException, but for instance the .NET API can also throw system exceptions like System.ArgumentException. You typically have no choice but to consider all exceptions as fatal.
So you should add exception handlers around application code calling Carmenta Engine methods, catching all exceptions. Depending on where you catch the error, you might just display an error, keep running and let the user try something else. But if you can't handle the error in a good way, you should at least terminate gracefully with an error message to the user.
Error handling in map controls
Catching exceptions from API calls is one thing. But almost all Carmenta Engine applications include one or more map controls, hosting Carmenta Engine views. The problem is that the map control and related tool classes also make calls to the Carmenta Engine API, in response to GUI events such as paint events or mouse clicks. In this case it is not possible to add exception handlers, since no application code is being called.
The way this is handled is that all map control classes have exception handlers internally. Exceptions are handled by firing the MapControl.Error event. If you register a handler for this event you will be notified when an error occurs and you have a chance to deal with it. If you don't register a listener, the MapControl will re-throw the exception, again terminating the application without any meaningful error message to the user.
It's hard to do anything else but to treat map control errors as fatal, display an error message to the user and exit gracefully. You might consider setting the View.UpdateEnabled flag to False, removing all tools from the map control, and keep running, to give the user a chance to save his/her current work or similar, before terminating. This is by the way what Carmenta Explorer does.
Avoiding fatal errors
So far we mostly talked about catching generic exceptions, and terminating the application. It is hard to do anything better in the above situations. But some errors you might not want to treat as fatal. For instance, if a data set doesn't find its expected data files, or if a certain web service is down, you might still want to allow the application to run, with some limited functionality. There are several methods you can use to handle certain errors, without generating exceptions or map control errors.
Suppressing data set initialization errors
All data set classes have an option to suppress errors that occur during data set initialization, and go on as if everything is fine. The data set will still function without errors, it will just not return any data. There are several ways this type of error handling can be activated:
If you set the DataSet.SuppressInitializationErrors to True.
If you load a configuration file with the OnDemandSuppressErrors, all loaded data sets will act this way.
If you create a data set instance in application code, and let it be implicitly initialized on its first data access. If you don't want this behavior, you should explicitly call its DataSet.Initialize method to trigger initialization and catch any exceptions thrown.
It is possible to get a notification when a data set suppresses an error, through the Runtime.Error event. You might want to use this, and notify the user somehow that certain functionality is not available.
Automatically disabling layers
Suppressing data set initialization errors is useful, but there are also cases where a data set or layer can function properly to begin with, but cause errors at a later time. For this reason the Layer.DisableOnError flag was added in Carmenta 5.14.
With this flag set, a layer will catch any errors that might occur during an update, and automatically turn itself off by setting its Layer.Enabled flag to False. This can be used together with, or instead of, the data set initialization error suppression, depending on the preferred behavior of the application. Again, the application can be notified when an error occurs, by listening to the Layer.EnabledChanged event and checking the result of the Layer.GetLastError method.
In some cases it might be possible to re-enable the layer again, but this could also cause problems; please see the remarks section for Layer.DisableOnError.
ServiceChanged event
Some Carmenta Engine components are dependent on remote database or web services to function. Since such services may not always be as stable as you like, and since it requires some extra work to reestablish a lost connection, these components support yet another error handling mechanism. They support a way to monitor the service for changes, and send notifications through an event when a service goes up or down. See for instance HttpLayer.ThrowExceptions, HttpLayer.ServiceMonitorInterval and HttpLayer.ServiceChanged. Other components with this functionality are the database data sets, the MvtDataSet and the other layers and data sets in the OGC module.
If you want to be able to restore these components after an error, and not just turn the layer off, you will need to implement handling of this event, and reset and reinitialize the component.
Catalog mechanism considerations
Hopefully there aren't any. If you're using remote services, you probably should handle the CatalogMap.ServiceChanged (not available in C#) event. If private layers inside a local catalog map have the Layer.DisableOnError flag set, the corresponding virtual layer will be located and disabled when an error occurs.
Log/trace
Finally, you probably do want to enable the Carmenta Engine log, or at least give the user an option to enable it when needed. This could be very useful when trying to locate the cause of an error. See the Log class for more information.