Error Handling

The Docutain SDK for .NET MAUI distinguishes between two kinds of problems.

A failure that can be expected during normal operation, e.g. a file that cannot be read or a PDF that cannot be written, is reported through the return value. An error on your side, e.g. using the SDK before it has been initialized or passing an invalid configuration, is reported through an exception.

Return values

The following methods report failure by returning null, false or an empty string. In that case, DocutainSDK.LastError contains the reason.

Method	Value on failure
DocutainSDK.InitSDK	false
DocutainSDK.DeleteTempFiles	false
Document.LoadFile	false
Document.WritePDF	null
Document.WriteImage	null
Document.GetImageBytes	null
DocumentDataReader.LoadFile	false
DocumentDataReader.SetAnalyzeConfiguration	false
DocumentDataReader.GetText	empty string
DocumentDataReader.Analyze	empty string

info

DocumentDataReader.GetText and DocumentDataReader.Analyze also return an empty string if the document simply contains no text or no extractable data. Check DocutainSDK.LastError to find out whether an error occurred.

using Docutain.SDK.MAUI;

var pdfFile = Document.WritePDF(destinationPath);
if (pdfFile == null)
{
    //an error occurred, get the reason
    var error = DocutainSDK.LastError;
}

UI.ScanDocument and UI.StartPhotoPayment do not report errors this way. Their result tells you whether the user finished or canceled the process, see Document Scan and Photo Payment.

Exceptions

Exception	Thrown when
DocutainSdkNotInitializedException	DocutainSDK.InitSDK has not been called, or did not return true.
DocutainSdkConfigurationException	A value of the passed configuration could not be applied. The Member property names the value that was rejected, InnerException states why.
DocutainSdkFileAccessException	A file could not be loaded, most commonly because it is an encrypted PDF and the password was missing or wrong. On Android this also covers a file your app is not allowed to read, so check the message before telling the user their password was wrong.
DocutainSdkNoHostException	Your app currently has no screen the SDK could present its UI on. Start the scanner while your app is in the foreground.

In addition, the usual .NET argument exceptions are thrown for invalid arguments, e.g. an ArgumentNullException for a configuration that is null or an ArgumentOutOfRangeException for a page number below 1.

DocutainSdkNotInitializedException derives from InvalidOperationException, DocutainSdkNoHostException from InvalidOperationException, DocutainSdkConfigurationException from ArgumentException and DocutainSdkFileAccessException from IOException.

Sample

using Docutain.SDK.MAUI;

try
{
    var scanConfig = new DocumentScannerConfiguration();
    var result = await UI.ScanDocument(scanConfig);
    //...
}
catch (DocutainSdkNotInitializedException)
{
    //the SDK has not been initialized successfully, see SDK Initialization
}
catch (DocutainSdkConfigurationException ex)
{
    //ex.Member names the configuration value that was rejected
}
catch (DocutainSdkNoHostException)
{
    //the app is currently not in the foreground
}

Encrypted PDF files

DocumentDataReader.LoadFile throws a DocutainSdkFileAccessException if the file is an encrypted PDF and the password was missing or wrong. See File Import for a complete sample.

try
{
    if (DocumentDataReader.LoadFile(filePath, password))
    {
        //...
    }
}
catch (DocutainSdkFileAccessException ex)
{
    //the password was missing or wrong, or the file could not be accessed
    var message = ex.Message;
}

Logging

If you cannot make sense of an error, the trace file usually can. See Logging on how to obtain it and send it to us.