Error Handling API

This section details the APIs and mechanisms for handling errors and exceptions within the MSDN framework. Effective error management is crucial for building robust and reliable applications.

Overview

The MSDN error handling system provides a standardized way to report, log, and recover from errors that occur during application execution. It leverages a combination of synchronous and asynchronous error reporting, allowing developers to implement strategies for both immediate feedback and long-term analysis.

Core Components

The error handling system comprises several key components:

• Error Objects: Standardized structures that encapsulate error details.
• Error Reporting Channels: Mechanisms for sending error information.
• Error Listeners/Handlers: Callbacks or functions that process reported errors.

ErrorObject Structure

Every error reported through the system is wrapped in an ErrorObject. This object provides a consistent interface for accessing error information.

Properties:

Reporting Errors

You can report errors using the global Msdn.Error.report() function. This function can be used for both expected and unexpected errors.

Synchronous Reporting

For immediate error handling, use synchronous reporting:

try {
    // Some operation that might fail
    if (someConditionFails) {
        throw new Error("Operation failed due to specific reason.");
    }
} catch (error) {
    Msdn.Error.report({
        code: "ERR_OPERATION_FAILED",
        message: "The operation could not be completed.",
        details: { originalError: error.message },
        stackTrace: error.stack
    });
    // Further local handling or user notification
}

Asynchronous Reporting

For non-critical errors or background tasks, consider asynchronous reporting to avoid blocking the main thread:

Msdn.Error.reportAsync({
    code: "WARN_UNRESPONSIVE_SERVICE",
    message: "A non-critical service is temporarily unavailable.",
    details: { serviceName: "Analytics" }
});

Registering Error Handlers

You can register functions to be called whenever an error is reported. This allows you to implement custom error logging, user notifications, or automatic recovery mechanisms.

Global Error Handler

Set a global handler to catch all reported errors:

Msdn.Error.addGlobalHandler(function(errorObject) {
    console.error("Global Error Caught:", errorObject);
    // Example: Send error to a remote logging service
    // logToServer(errorObject);

    // Example: Display a user-friendly message if it's a critical error
    if (errorObject.code.startsWith("ERR_")) {
        Msdn.UI.showNotification("An unexpected error occurred. Please try again later.", "error");
    }
});

Specific Error Handlers

Register handlers for specific error codes:

Msdn.Error.addHandler("ERR_NETWORK_TIMEOUT", function(errorObject) {
    console.warn("Network timeout occurred:", errorObject.message);
    Msdn.UI.showNotification("Network connection lost. Please check your internet connection.", "warning");
});

Built-in Error Codes

The MSDN framework defines several common error codes for frequently encountered issues:

• "ERR_UNKNOWN": A general, unclassified error.
• "ERR_NETWORK_REQUEST_FAILED": Indicates a failure in a network request.
• "ERR_INVALID_ARGUMENT": An argument passed to a function is invalid.
• "ERR_RESOURCE_NOT_FOUND": A requested resource could not be located.
• "ERR_AUTHENTICATION_FAILED": User authentication failed.

Best Practices

• Be Specific: Use distinct error codes and descriptive messages.
• Provide Context: Include relevant data in the details property.
• Don't Over-Report: Handle expected, recoverable issues gracefully without triggering error reporting.
• User Experience: Translate technical errors into user-friendly messages.
• Logging: Ensure errors are logged effectively for debugging and monitoring.