ImageGear .NET v24.12 - Updated
Handling Warnings and Errors
User Guide > How to Work with... > Handling Warnings and Errors

This topic provides information about the following:

Errors

ImageGear .NET natively supports the exception handling model provided by .NET CLR and reports errors by throwing an exception containing specific information about the error. These exceptions can be handled in the same manner as other .NET exceptions are handled (see example below). The base class for exceptions thrown by ImageGear .NET is ImGearException.

It is important to note that the ImageGear API will throw ImageGear .NET exceptions in addition to System or currently executing application exceptions. To separate these ImageGear exceptions from others, you can check if an exception caught is of ImGearException type, as shown in the example below.

 

Example
Copy Code
try
{
        if (_imGearDocument != null)
        {
                _imGearDocument.Dispose();
                _imGearDocument = null;
        }
 
        // Load first page.
        _imGearDocument = ImGearFileFormats.LoadDocument(stream, 0, 3);
}
catch (ImGearException ex)
{
        // Perform error handling.
        string errorNotification = string.Format("Could not load file {0}", _inputFileName);
        toolStripStatusLabel.Text = string.IsNullOrEmpty(ex.Message) ? errorNotification : ex.Message;
        MessageBox.Show(errorNotification, "", MessageBoxButtons.OK, MessageBoxIcon.Error);
        return;
}              

Warnings

ImageGear .NET uses a separate way to report minor and non-critical mistakes (i.e., an inconsistency of the metadata or image attributes passed into the SavePage Method). These reports for non-critical mistakes are called warnings and are reported without using the generic .NET Exceptions mechanism. To get notifications of such minor errors, you should define and register a delegate ImGearAddWarning Delegate and then receive and handle warning information encapsulated into ImGearWarning objects in a callback method defined in the code.

Example
Copy Code
public MainForm()
{
        InitializeComponent();
        
        // Registers a delegate to handle ImageGear warnings
        ImGearWarning.AddWarning += new ImGearAddWarning(OnWarning);
}

…

// Store last warning.
public void OnWarning(ImGearWarning warning)
{
        lastWarning = warning.Description;
        ImGearWinForms.AddWarning(warning);
        toolStripStatusLabel.Text = "Warnings encountered in the operation";
}                                     

WinForms UI

ImageGear .NET provides API and WinForms UI dialogs to help display ImageGear exceptions and warnings. The API for this is listed below:

 

Example
Copy Code
      static void Main()
      {
          ...
          try
          {
              ...
              
              // Register warning handler
              ImGearWarning.AddWarning = new ImGearAddWarning(ImGearWinForms.AddWarning);
 
              // Registers exception handler for all threads
              ImGearWinForms.RegisterExceptionHandler();
 
              Application.Run(new MainForm());
          }                                    

Throwing an ImageGearException

Although the ImGearException Class does not have a public constructor, you сan use ThrowError to report a problem specific to ImageGear. To specify the error you want to report, you can use an appropriate identifier listed in ImGearErrorCodes Enumeration.

There is no API to report an ImageGear Warning, except for ImGearWinForms.AddWarning, which only affects the GUI.