GroupDocs.Conversion for .NET 20.1 Release Notes

Major Features

There are 10+ features, improvements and bug-fixes in this release, most notable are:

  • Legacy API is removed from the product
  • Introduced EML to MSG conversions
  • API to retrieve prepared default ConvertOptions for desired target conversion
  • Introduced GetAllPossibleConversions method which return all supported conversions
  • GetPossibleConversions method for a document extension without instantiating a Converter
  • GetPossibleConversions for currently provided source document
  • Improved document info classes
  • Image to image conversions now produces proportional image if only width or only height is provided 

Full List of Issues Covering all Changes in this Release

KeyCategorySummary
CONVERSIONNET-3290FeatureEML to MSG conversion
CONVERSIONNET-3512FeatureAPI to retrieve prepared default ConvertOptions for desired target conversion
CONVERSIONNET-3536FeatureConvert attachments from a mail document
CONVERSIONNET-3586FeatureGetAllPossibleConversions method which returns all supported conversions
CONVERSIONNET-3587FeatureGetPossibleConversions for a document extension without instantiating a Converter
CONVERSIONNET-3597ImprovementImprove document info classes 
CONVERSIONNET-3626ImprovementMake proportional image If only Width or Height is provided when converting to image
CONVERSIONNET-3576BugEmail to Excel conversion issue
CONVERSIONNET-3581BugEmail to Word or PDF License Not working
CONVERSIONNET-3625BugPageNumber and PagesCount not respected when converting to image
CONVERSIONNET-3634Bug‘Index was out of range.’ exception when converting particular .mpx file to .html

Public API and Backward Incompatible Changes

  1. GroupDocs.Conversion.Contracts.PossibleConversions
    Introduced new class PossibleConversions

    /// <summary>
    /// Represents a mapping what conversion pairs
    /// are supported for specific source file format
    /// </summary>
    public sealed class PossibleConversions
    {
        /// <summary>
        /// Source file formats
        /// </summary>
        public FileType Source { get; private set; }
         
         
        /// <summary>
        /// All target file types and primary/secondary flag
        /// </summary>
        public IEnumerable<TargetConversion> All { get; }
         
        /// <summary>
        /// Returns target conversion for specified target file type
        /// </summary>
        /// <param name="target"></param>
        /// <returns><see cref="TargetConversion"/> or null</returns>
        public TargetConversion this[FileType target] { get; }
         
         
        /// <summary>
        /// Returns target conversion for specified target file type extension
        /// </summary>
        /// <param name="extension"></param>
        /// <returns><see cref="TargetConversion"/> or null</returns>
        public TargetConversion this[string extension] { get; }
         
        /// <summary>
        /// Primary target file types
        /// </summary>
        public IEnumerable<FileType> Primary { get; }
         
         
        /// <summary>
        /// Secondary target file types
        /// </summary>
        public IEnumerable<FileType> Secondary { get; }
    }
    

    Usage:

    using (var converter = new Converter("source.docx"))
    {
        var possibleConversions = converter.GetPossibleConversions();
        ...
    }
    
  2. GroupDocs.Conversion.Contracts.TargetConversion
    Introduced new class TargetConversion

    /// <summary>
    /// Represents possible target conversion and a flag is it a primary or secondary 
    /// </summary>
    public sealed class TargetConversion
    {
        /// <summary>
        /// Target document format
        /// </summary>
        public FileType Format { get; }
         
        /// <summary>
        /// Is the conversion primary
        /// </summary>
        public bool IsPrimary { get;  }
         
         
        /// <summary>
        /// Predefined convert options which could be used to convert to current type
        /// </summary>
        public ConvertOptions ConvertOptions { get; }
    } 
    

    Usage:

    using (var converter = new Converter("source.docx"))
    {
        var possibleConversions = converter.GetPossibleConversions();
        var targetConversion = possibleConversions["pdf"];
        var convertOptions = targetConversion?.ConvertOptions;
        ...
    }
    
  3. GroupDocs.Conversion.Converter.GetAllPossibleConversions
    Introduced new static method GetAllPossibleConversions in Converter class

    /// <summary>
    /// Gets all supported conversions
    /// </summary>
    /// <returns></returns>
    public static IEnumerable<PossibleConversions> GetAllPossibleConversions()
    

    Usage:

    var allPossibleConversions = Converter.GetAllPossibleConversions();
    foreach (var possibleConversions in allPossibleConversions)
    {
        Console.WriteLine($"Source format: {possibleConversions.Source.Description}");
        foreach (var primary in possibleConversions.Primary)
        {
            Console.WriteLine($"\t-->{primary.Description}");
        }
        foreach (var secondary in possibleConversions.Secondary)
        {
            Console.WriteLine($"\t-->{secondary.Description}");
        }
    }
    
  4. GroupDocs.Conversion.Converter.GetPossibleConversions
    Introduced new method GetPossibleConversions in Converter class

    /// <summary>
    /// Gets possible conversions for the source document.
    /// </summary>
    /// <returns></returns>
    public PossibleConversions GetPossibleConversions()
    

    Usage:

    using (var converter = new Converter("source.docx"))
    {
        var possibleConversions = converter.GetPossibleConversions();
        ...
    }
    

    Introduced new static method GetPossibleConversions in Converter class

    /// <summary>
    /// Gets supported conversions for provided document extension
    /// </summary>
    /// <param name="extension">Document extension</param>
    /// <example>Converter.GetPossibleConversions(".docx")</example>
    /// <example>Converter.GetPossibleConversions("docx")</example>
    /// <returns></returns>
    public static PossibleConversions GetPossibleConversions(string extension)
    

    Usage:

    var possibleConversions = Converter.GetPossibleConversions("docx");
    var targetConversion = possibleConversions["pdf"]; // docx -> pdf
    var convertOptions = targetConversion?.ConvertOptions;
    
  5. GroupDocs.Conversion.Options.Convert.EmailConvertOptions
    Introduced new class EmailConvertOptions

    /// <summary>
    /// Options for conversion to Email file type.
    /// </summary>
    public class EmailConvertOptions : ConvertOptions<EmailFileType>
    {
    }
    

    Usage:

    using(var converter = new Converter("source.eml")) {
        var convertOptions = new EmailConvertOptions
        {
            Format = EmailFileType.Msg
        };
        converter.Convert("converted.msg",  convertOptions);
    }
    
  6. GroupDocs.Conversion.Options.Load.EmailLoadOptions
    Introduced new property ConvertAttachments in EmailLoadOptions

    /// <summary>
    /// Option to convert attachments in source email or not. Default: false.
    /// </summary>
    public bool ConvertAttachments { get; set; }
    

    Usage:

    var source = "sample-with-attachment.eml";
    var loadOptions = new EmailLoadOptions {ConvertAttachments = true};
    using (var converter = new Converter(source, () => loadOptions))
    {
        var index = 1;
        var options = new PdfConvertOptions();
        converter.Convert(() => new FileStream($"converted-{index++}.pdf", FileMode.Create) , options);
    }
    
  7. GroupDocs.Conversion.Legacy
    Removed all public types form GroupDocs.Conversion.Legacy namespace.