ImageGear .NET v25.2 - Updated
Developer Guide / How to Work with... / Handling Warnings and Errors
In This Topic
    Handling Warnings and Errors
    In This Topic

    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.