1. GroupDocs.Conversion
  2. /
  3. GroupDocs.Conversion for .NET
  4. /
  5. GroupDocs.Conversion
  6. /
  7. Converter

Converter

On this page

Converter class

Represents main class that controls document conversion process.

public sealed class Converter : IDisposable

Constructors

Name Description
Converter(Func<Stream>) Initializes new instance of Converter class.
Converter(string) Initializes new instance of Converter class.
Converter(Func<Stream>, Func<ConverterSettings>) Initializes new instance of Converter class.
Converter(string, Func<ConverterSettings>) Initializes new instance of Converter class.
Converter(Func<Stream>, Func<ConverterSettings>, Func<ConversionEvents>) Initializes new instance of Converter class with explicit conversion events.
Converter(Func<Stream>, Func<LoadContext, LoadOptions>, Func<ConverterSettings>) Initializes new instance of Converter class.
Converter(string, Func<ConverterSettings>, Func<ConversionEvents>) Initializes new instance of Converter class with explicit conversion events.
Converter(string, Func<LoadContext, LoadOptions>, Func<ConverterSettings>) Initializes new instance of Converter class.
Converter(Func<Stream>, Func<LoadContext, LoadOptions>, Func<ConverterSettings>, Func<ConversionEvents>) Initializes new instance of Converter class with explicit conversion events.
Converter(string, Func<LoadContext, LoadOptions>, Func<ConverterSettings>, Func<ConversionEvents>) Initializes new instance of Converter class with explicit conversion events.

Methods

Name Description
Convert(ConvertOptions, Action<ConvertedContext>, CancellationToken) Converts source document. Saves the whole converted document.
Convert(ConvertOptions, Action<ConvertedPageContext>, CancellationToken) Converts source document. Saves the converted document page by page.
Convert(Func<ConvertContext, ConvertOptions>, Action<ConvertedContext>, CancellationToken) Converts source document. Saves the whole converted document.
Convert(Func<ConvertContext, ConvertOptions>, Action<ConvertedPageContext>, CancellationToken) Converts source document. Saves the converted document page by page.
Convert(Func<SaveContext, Stream>, ConvertOptions, CancellationToken) Converts source document. Saves the whole converted document.
Convert(Func<SaveContext, Stream>, Func<ConvertContext, ConvertOptions>, CancellationToken) Converts source document. Saves the whole converted document.
Convert(Func<SavePageContext, Stream>, ConvertOptions, CancellationToken) Converts source document. Saves the converted document page by page.
Convert(Func<SavePageContext, Stream>, Func<ConvertContext, ConvertOptions>, CancellationToken) Converts source document. Saves the converted document page by page.
Convert(string, ConvertOptions, CancellationToken) Converts source document. Saves the whole converted document.
Dispose() Releases resources.
GetDocumentInfo() Gets source document info - pages count and other document properties specific to the file type.
GetDocumentInfo<T>() Gets source document info - pages count and other document properties specific to the file type.
GetPossibleConversions() Gets possible conversions for the source document.
IsDocumentPasswordProtected() Checks is source document is password protected
static GetAllPossibleConversions() Gets all supported conversions
static GetPossibleConversions(string) Gets supported conversions for provided document extension

Examples

Basic conversion from file path:

// Convert DOCX to PDF
using (var converter = new Converter("sample.docx"))
{
    var options = new PdfConvertOptions();
    converter.Convert("output.pdf", options);
}

Conversion with custom options:

// Convert DOCX to PDF with watermark and specific page range
using (var converter = new Converter("sample.docx"))
{
    var options = new PdfConvertOptions
    {
        PageNumber = 1,
        PagesCount = 3,
        Watermark = new WatermarkTextOptions("CONFIDENTIAL")
        {
            Color = System.Drawing.Color.Red,
            Width = 300,
            Height = 100
        }
    };
    converter.Convert("output.pdf", options);
}

Conversion from stream:

// Convert document from stream to stream
using (var sourceStream = File.OpenRead("sample.docx"))
using (var converter = new Converter(() => sourceStream))
using (var outputStream = File.Create("output.pdf"))
{
    var options = new PdfConvertOptions();
    converter.Convert((SaveContext context) => outputStream, options);
}

Conversion with load options (password-protected document):

// Load password-protected document and convert to PDF
var loadOptions = new WordProcessingLoadOptions
{
    Password = "secret_password"
};
using (var converter = new Converter("protected.docx", (LoadContext context) => loadOptions))
{
    var convertOptions = new PdfConvertOptions();
    converter.Convert("output.pdf", convertOptions);
}

Page-by-page conversion:

// Convert document pages to separate image files
using (var converter = new Converter("sample.pdf"))
{
    var options = new ImageConvertOptions
    {
        Format = ImageFileType.Png
    };

    converter.Convert(
        (SavePageContext context) => File.Create($"page-{context.Page}.png"),
        options
    );
}

Registering conversion event handlers (recommended path):

// Aggregate all event handlers in a ConversionEvents bag and pass it to the Converter.
var events = new ConversionEvents
{
    OnDocumentConverted = ctx       => Console.WriteLine($"Done: {ctx.SourceFileName}"),
    OnDocumentFailed    = (ctx, ex) => Console.Error.WriteLine($"Conversion of {ctx.SourceFileName} failed: {ex.Message}"),
    OnPageFailed        = (ctx, ex) => Console.Error.WriteLine($"Page {ctx.Page} of {ctx.SourceFileName} failed: {ex.Message}"),
};
using (var converter = new Converter("sample.docx", () => new ConverterSettings(), () => events))
{
    converter.Convert("output.pdf", new PdfConvertOptions());
}

The flat OnConversionFailed, OnConversionByPageFailed, and OnCompressionCompleted properties on ConverterSettings still work but are obsolete; new code should pass a ConversionEvents instance via the events constructor parameter.

Get document information:

// Retrieve document metadata before conversion
using (var converter = new Converter("sample.docx"))
{
    var info = converter.GetDocumentInfo();
    Console.WriteLine($"Document has {info.PagesCount} pages");
    Console.WriteLine($"Format: {info.Format}");
    Console.WriteLine($"Size: {info.Size} bytes");
}

See Also

On this page