DocumentConverterConvert(FileProvider, FileProvider, OutputOptions, NullableDocumentEngine) Method

Converts a given document file to another format with the specified output path and options.

Definition

Namespace: GleamTech.DocumentUltimate
Assembly: GleamTech.DocumentUltimate (in GleamTech.DocumentUltimate.dll) Version: 7.1.5
C#
public static DocumentConverterResult Convert(
	FileProvider inputFile,
	FileProvider outputFile,
	OutputOptions outputOptions = null,
	DocumentEngine? engine = null
)

Parameters

inputFile  FileProvider
The document file to convert.

This parameter can be set to:

  • A plain string which contains a physical/virtual path
    (e.g. "c:\SomeFolder\SomeFile.ext", "/SomeFolder/SomeFile.ext", "~/SomeFolder/SomeFile.ext").

    This is parsed as a FileSystemFileProvider instance with a PhysicalLocation instance. Note that virtual paths can only be resolved in a web application.
    and on Linux paths starting with "/" are physical paths and not virtual paths.

  • A plain string which contains a URL or a Data URL.
    (e.g. "http://example.com/SomeFolder/SomeFile.ext", "data:image/gif;base64,...").

    Strings starting with http:// or https:// are parsed as a UrlFileProvider instance.
    Strings starting with data: are parsed as a DataUrlFileProvider instance.

  • A FileProvider instance created with one of the builtin file providers
    (e.g. FileSystemFileProvider, UrlFileProvider, DataUrlFileProvider, StreamFileProvider, MemoryFileProvider, DatabaseFileProvider, AssemblyResourceFileProvider, TemporaryFileProvider).

    You can also override FileProvider base class to implement your custom file provider.

  • A provider string which defines a specific file provider
    (e.g. "Type=FileSystem; File=SomeFile.ext; Location='Type=Physical; Path=c:\SomeFolder'").

The parameter only needs a readable file provider as it only calls GetInfo and OpenRead.

outputFile  FileProvider
The document file to convert to.

This parameter can be set to:

  • A plain string which contains a physical/virtual path
    (e.g. "c:\SomeFolder\SomeFile.ext", "/SomeFolder/SomeFile.ext", "~/SomeFolder/SomeFile.ext").

    This is parsed as a FileSystemFileProvider instance with a PhysicalLocation instance. Note that virtual paths can only be resolved in a web application.
    and on Linux paths starting with "/" are physical paths and not virtual paths.

  • A plain string which contains a URL or a Data URL.
    (e.g. "http://example.com/SomeFolder/SomeFile.ext", "data:image/gif;base64,...").

    Strings starting with http:// or https:// are parsed as a UrlFileProvider instance.
    Strings starting with data: are parsed as a DataUrlFileProvider instance.

  • A FileProvider instance created with one of the builtin file providers
    (e.g. FileSystemFileProvider, UrlFileProvider, DataUrlFileProvider, StreamFileProvider, MemoryFileProvider, DatabaseFileProvider, AssemblyResourceFileProvider, TemporaryFileProvider).

    You can also override FileProvider base class to implement your custom file provider.

  • A provider string which defines a specific file provider
    (e.g. "Type=FileSystem; File=SomeFile.ext; Location='Type=Physical; Path=c:\SomeFolder'").

The parameter only needs a writable file provider as it only calls OpenWrite.

outputOptions  OutputOptions  (Optional)
The output options which contains format and other options for the converted file. If not specified, the format will be automatically determined from the file extension in outputFile.
engine  NullableDocumentEngine  (Optional)
The document engine to force. If not specified, the best document engine will be chosen automatically according to the input and output formats.

Return Value

DocumentConverterResult
A DocumentConverterResult object that contains the result of the document conversion such as output file paths.

Example

Use static Convert method to easily convert an input document to another format:

C#
// Convert "c:\SomeFolder\InputFile.docx" to "c:\SomeFolder\InputFile.pdf"
DocumentConverter.Convert(@"c:\SomeFolder\InputFile.docx", DocumentFormat.Pdf);

// Convert "c:\SomeFolder\InputFile.docx" to "c:\SomeFolder\OutputFile.pdf"
DocumentConverter.Convert(@"c:\SomeFolder\InputFile.docx", @"c:\SomeFolder\OutputFile.pdf");

//---------------------------------------

//Convert with a virtual path string:
//See below for other path string examples.
DocumentConverter.Convert("~/SomeFolder/InputFile.docx", DocumentFormat.Pdf);

//Convert with a URL string:
//See below for other path string examples.
DocumentConverter.Convert(
    "http://example.com/SomeFolder/InputFile.docx",
    @"c:\SomeFolder\OutputFile.pdf"
);

//Convert with a Data URL string:
//See below for other path string examples.
DocumentConverter.Convert(
    "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7",
    @"c:\SomeFolder\OutputFile.pdf"
);

//Convert with a file provider instance:
//See below for other file provider examples (UNC Path, AmazonS3, AzureBlob, Database etc.).
var fileProvider = new FileSystemFileProvider
{
    File = "InputFile.docx",
    Location = new PhysicalLocation
    {
        Path = @"c:\SomeFolder"
    }
};
DocumentConverter.Convert(fileProvider, DocumentFormat.Pdf);

//Convert with a provider string:
//See below for other provider string examples (UNC Path, AmazonS3, AzureBlob, Database etc.).
DocumentConverter.Convert(
    @"Type=FileSystem; File=InputFile.docx; Location='Type=Physical; Path=c:\SomeFolder'",
    DocumentFormat.Pdf
);

Convert and ConvertTo methods also returns an instance of DocumentConverterResult class which has some useful properties:

C#
var result = DocumentConverter.Convert(@"c:\SomeFolder\InputFile.docx", DocumentFormat.Jpg);

// result.ElapsedTime: Total elapsed time for the document conversion 
Console.WriteLine("Conversion took {0} milliseconds.", result.ElapsedTime.TotalMilliseconds);

// result.OutputFiles: A string array for the paths of the converted (output) document files. 
// When there is only one output file, the value will be a single item array.
// If the output is a directory (e.g. for DocumentFormat.Web format), 
// the string will have a trailing backslash (\).
Console.WriteLine("Conversion generated {0} output files:", result.OutputFiles.Length);
for (var i = 0; i < result.OutputFiles.Length; i++)
{
    Console.WriteLine("OutputFiles[{0}] -> {1}", i, result.OutputFiles[i]);
}

/*
    Conversion generated 3 output files:
    OutputFiles[0] -> InputFile-1.jpg
    OutputFiles[1] -> InputFile-2.jpg
    OutputFiles[2] -> InputFile-3.jpg
**/

  Notes to Callers

Below are the examples for setting a FileProvider parameter/property.

Setting a plain string:

C#
FileProvider fileProvider;

//Setting a physical/virtual path string:
//These strings are parsed as a FileSystemFileProvider instance with a PhysicalLocation instance.
fileProvider = @"c:\SomeFolder\SomeFile.ext";
//Note that virtual paths can only be resolved in a web application
//and on Linux paths starting with "/" are physical paths and not virtual paths.
fileProvider = "/SomeFolder/SomeFile.ext";
fileProvider = "~/SomeFolder/SomeFile.ext"; //"~" means relative to web application root.

//Setting a URL or a Data URL string:
//Strings starting with "http://" or "https://" are parsed as a UrlFileProvider instance.
//Strings starting with "data:" are parsed as a DataUrlFileProvider instance.
fileProvider = "http://example.com/SomeFolder/SomeFile.ext";
fileProvider = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";

Setting a MemoryFileProvider instance, to connect to a file in a byte array (byte) or a MemoryStream:

C#
FileProvider fileProvider;

//Setting a MemoryFileProvider instance,
//to connect to a file in a byte array (byte[]) or a MemoryStream:
//Optional parameter dateModified: used for detailed file info, e.g. for generating better cache keys.
fileProvider = new MemoryFileProvider(
    "SomeFile.ext", //file can also be set as a relative path "SomeFolder/SomeFile.ext".
    yourByteArray,
    yourFileDateModified //Provide dateModified to prevent cache key conflicts.
);
fileProvider = new MemoryFileProvider(
    "SomeFile.ext", //file can also be set as a relative path "SomeFolder/SomeFile.ext".
    yourMemoryStream,
    yourFileDateModified //Provide dateModified to prevent cache key conflicts.
);

//Create with empty MemoryStream
//Note that this instance should be written (filled with data via OpenWrite method) before being read
fileProvider = new MemoryFileProvider("SomeFolder/SomeFile.ext");

Setting a StreamFileProvider instance, to connect to a file in a Stream:

C#
FileProvider fileProvider;

//Setting a StreamFileProvider instance,
//to connect to a file in a Stream:
//Optional parameters dateModified and size: used for detailed file info, e.g. for generating better cache keys.
fileProvider = new StreamFileProvider(
    "SomeFile.ext", //file can also be set as a relative path "SomeFolder/SomeFile.ext".
    yourStream,
    yourFileDateModified, //Provide dateModified to prevent cache key conflicts.
    yourFileSize //Provide size only if your stream is not seekable to prevent cache key conflicts.
);

Setting a FileSystemFileProvider instance with a PhysicalLocation instance, to connect to physical file system:

C#
FileProvider fileProvider;

//Setting a physical file provider via a FileSystemFileProvider instance:
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        //Path can also be virtual path string like "~/SomeFolder" in a web application.
        Path = @"c:\SomeFolder"
    }
};

//Setting a physical file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=Physical; Path=c:\SomeFolder'";

//---------------------------------------

//Setting a FileSystemFileProvider instance with a PhysicalLocation instance,
//to connect as a specific Windows user to a UNC path or a protected local path:
//UserName can be specified as "Domain\User", "User@Domain" (UPN format), "Machine\User", "User" (local user).
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        Path = @"\\server\share", //Path can be a UNC path or a local path
        UserName = "USERNAME",
        Password = "PASSWORD"
    }
};

//Setting a physical file provider via a provider string, to connect as a specific user (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Path=\\server\share; User Name=USERNAME; Password=PASSWORD'";

//---------------------------------------

//Setting a physical file provider via a FileSystemFileProvider instance, to connect as the authenticated user:
//If Windows Authentication is used in IIS for this site, location can be specified like this
//to connect as the already authenticated user: 
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new PhysicalLocation
    {
        Path = @"\\server\share", //Path can be a UNC path or a local path
        AuthenticatedUser = AuthenticatedUser.Windows
    }
};

//Setting a physical file provider via a provider string, to connect as the authenticated user:
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Path=\\server\share; Authenticated User=Windows'";

Setting a FileSystemFileProvider instance with an AzureBlobLocation instance, to connect to Azure Blob cloud file system:

C#
FileProvider fileProvider;

//Setting a FileSystemFileProvider instance with an AzureBlobLocation instance,
//to connect to Azure Blob cloud file system.
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new AzureBlobLocation
    {
        //Leave Path empty to connect to the root of the container. 
        //For connecting to subfolders, Path should be specified as a relative path (eg. "some/folder")
        //Path = "some/folder",

        //Get these values from your Azure Portal (Storage Account -> Access Keys -> Connection String)
        Container = "CONTAINER",
        AccountName = "XXX",
        AccountKey = "XXX"
    }
};

//Setting a an Azure Blob file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=AzureBlob; Container=CONTAINER; Account Name=XXX; Account Key=XXX'";

Setting a FileSystemFileProvider instance with an AmazonS3Location instance, to connect to Amazon S3 cloud file system:

C#
FileProvider fileProvider;

//Setting a FileSystemFileProvider instance with an AmazonS3Location instance,
//to connect to Amazon S3 cloud file system.
fileProvider = new FileSystemFileProvider
{
    File = "SomeFile.ext",
    Location = new AmazonS3Location
    {
        //Leave Path empty to connect to the root of the bucket. 
        //For connecting to subfolders, Path should be specified as a relative path (eg. "some/folder")
        //Path = "some/folder",

        BucketName = "BUCKET",
        Region = "eu-central-1",
        AccessKeyId = "XXX",
        SecretAccessKey = "XXX",
    }
};

//Setting an Amazon S3 file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = @"Type=FileSystem; File=SomeFile.ext; Location='Type=AmazonS3; Bucket Name=BUCKET; Region=eu-central-1; Access Key Id=XXX; Secret Access Key=XXX'";

Setting a UrlFileProvider instance, to connect to a file located at a URL:

C#
FileProvider fileProvider;

//Setting a URL file provider via a UrlFileProvider instance:
//File should start with "http://" or "https://".
fileProvider = new UrlFileProvider
{
    File = "http://example.com/SomeFolder/SomeFile.ext"
};

//Setting a URL file provider via a provider string (same as above):
fileProvider = "Type=Url; File=http://example.com/SomeFolder/SomeFile.ext";

Setting a DataUrlFileProvider instance, to connect to a file encoded in a Data URL:

C#
FileProvider fileProvider;

//Setting a Data URL file provider via a UrlFileProvider instance:
//File should start with "data:".
fileProvider = new DataUrlFileProvider
{
    File = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7"
};

//Setting a Data URL file provider via a provider string (same as above):
fileProvider = "Type=DataUrl; File='data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7'";

Setting a DatabaseFileProvider instance, to connect to a database file system:

C#
FileProvider fileProvider;

//Setting a DatabaseFileProvider instance,
//to connect to a database file system.
fileProvider = new DatabaseFileProvider
{
    File = "SomeFile.ext", //File can also be set as a relative path "SomeFolder/SomeFile.ext".
    ConnectionString = "Data Source=(local); Initial Catalog=SomeDb; Integrated Security=SSPI",
    //ProviderName = "System.Data.SqlClient" //ProviderName default value is "System.Data.SqlClient"

    Table = "SomeTable", //Table default value is "File".

    //Mandatory fields:
    KeyField = "Path", //KeyField default value is "Id".
    ContentField = "Content", //ContentField default value is "Content".

    //Optional fields DateModifiedField and SizeField: used for detailed file info, e.g. for generating better cache keys.
    //NameField = "Name", //NameField used for overriding file name specified in File.
    DateModifiedField = "DateModified", //Provide DateModifiedField to prevent cache key conflicts.
    SizeField = "Size" //Provide SizeField to prevent cache key conflicts.
};

//Setting a database file provider via a provider string (same as above):
//In a provider string, if a value contains semi-colon character, that value should be enclosed
//in single quotes (eg. Password='PASS;WORD') or double quotes (eg. Password="PASS;WORD").
fileProvider = "Type=Database; File=SomeFolder/SomeFile.ext; Connection String='Data Source=(local); Initial Catalog=SomeDb; Integrated Security=SSPI'; Table=SomeTable; Key Field=Path; Content Field=Content";

//---------------------------------------

/*

Sample SQL script to create a table in the database:

CREATE TABLE [File] (
    [Id] [int] IDENTITY(1, 1) PRIMARY KEY,
    [Path] [nvarchar](500) NOT NULL UNIQUE,
    [Name] [nvarchar](100),
    [DateModified] [smalldatetime],
    [Size] [bigint],
    [Content] [varbinary](max)
);

*
*/

Setting a AssemblyResourceFileProvider instance, to connect to a file embedded in an assembly:

C#
FileProvider fileProvider;

//Setting an assembly resource file provider via a AssemblyResourceFileProvider instance:
fileProvider = new AssemblyResourceFileProvider
{
    File = @"SomeFolder\SomeFile.ext",
    Assembly = typeof(SomeType).Assembly,
    BaseNamespace = typeof(SomeType).Namespace
};

//Setting an assembly file provider via a provider string (same as above):
fileProvider = @"Type=AssemblyResource; File=SomeFolder\SomeFile.ext; Assembly=SomeAssembly; Base Namespace=Some.Namespace";

Setting a TemporaryFileProvider instance, to connect to a temporary file:

C#
FileProvider fileProvider;

//Setting a temporary file provider via a TemporaryFileProvider instance:
//Note that this instance should be written (filled with data via OpenWrite method) before being read
fileProvider = new TemporaryFileProvider("SomeFolder/SomeFile.ext");

Setting and implementing a custom file provider:

C#
FileProvider fileProvider;

//Setting a custom file provider:
fileProvider = new CustomFileProvider
{
    File = @"SomeFolder\SomeFile.ext",
    Parameters = new Dictionary<string, string>
    {
        {"parameter1", "value1"}
    }
};
C#
public class CustomFileProvider : FileProvider
{
    public override string File { get; set; }

    //Return true if DoGetInfo method is implemented, and false if not.
    public override bool CanGetInfo => true;

    //Return true if DoOpenRead method is implemented, and false if not.
    public override bool CanOpenRead => true;

    //Return true if DoOpenWrite method is implemented, and false if not.
    public override bool CanOpenWrite => false;

    //Return true only if File identifier is usable across processes/machines.
    public override bool CanSerialize => false;

    protected override FileProviderInfo DoGetInfo()
    {
        //Return info here which corresponds to the identifier in File property.

        //When this file provider is used in DocumentViewer:
        //This method will be called every time DocumentViewer requests a document.
        //The cache key and document format will be determined according to the info you return here.

        string fileName = File;
        DateTime dateModified = DateTime.Now;
        long size = 81920;

        return new FileProviderInfo(fileName, dateModified, size);

        //throw new NotImplementedException();
    }

    protected override Stream DoOpenRead()
    {
        //Open and return a readable stream here which corresponds to the identifier in File property.

        //You can make use of Parameters dictionary which was passed when this provider was initialized.
        //var someParameter = Parameters["parameter1"];

        //When this file provider is used in DocumentViewer:
        //This method will be called only when original input document is required, 
        //For example if DocumentViewer already did the required conversions and cached the results, 
        //it will not be called.

        return readableStream;

        //throw new NotImplementedException();
    }

    protected override Stream DoOpenWrite()
    {
        //Open and return a writable stream here which corresponds to the identifier in File property.

        throw new NotImplementedException();
    }
}

See Also