Улучшите обработку изображений с помощью Modern API

Введение

Исторически Aspose Slides зависит от System.Drawing и в публичном API содержит следующие классы из него:

Начиная с версии 24.4, этот публичный API объявлен устаревшим.

Поскольку поддержка System.Drawing в версиях .NET 6 и выше удалена для не‑Windows‑платформ (нарушающее совместимость изменение), Slides реализовал двухпакетный подход:

Aspose.Slides.NET – поддержка .NET 6+ для Windows, .NETStandard для Windows/Linux/macOS, .NETFramework 2+ (Windows).
- имеет зависимость от System.Drawing.Common.
Aspose.Slides.NET6.CrossPlatform – версия для Windows/Linux/macOS без внешних зависимостей.

Недостаток Aspose.Slides.NET6.CrossPlatform состоит в том, что он реализует свою собственную версию System.Drawing в том же пространстве имён (для обеспечения обратной совместимости с публичным API). Поэтому при одновременном использовании Aspose.Slides.NET6.CrossPlatform и System.Drawing из .NET Framework или пакета System.Drawing.Common возникает конфликт имён, если не использовать алиасы.

Чтобы избавиться от зависимостей от System.Drawing в основном пакете Aspose.Slides.NET, мы добавили так называемый «Modern API» – т.е. API, который следует использовать вместо устаревшего, подписи которого содержат зависимости от следующих типов System.Drawing: Image и Bitmap. PrinterSettings и Graphics объявлены устаревшими, и их поддержка удалена из публичного API Slides.

В текущих версиях публичный API, зависящий от System.Drawing, рассматривается как устаревший/наследованный. Для нового кода и при миграции существующих рабочих процессов обработки изображений используйте Modern API.

Modern API

В публичный API добавлены следующие классы и перечисления:

Aspose.Slides.IImage – представляет растровое или векторное изображение.
Aspose.Slides.ImageFormat – представляет файловый формат изображения.
Aspose.Slides.Images – методы для создания экземпляров и работы с интерфейсом IImage.

Обратите внимание, что IImage реализует интерфейс IDisposable и должен использоваться в конструкции using или быть освобождён другим удобным способом.

Используйте GetImage для рендеринга одного слайда или фигуры. Используйте GetImages для рендеринга нескольких слайдов презентации. Методы из Images позволяют загружать изображения, AddImage с IImage – добавлять их в презентацию, и ReplaceImage с IImage – обновлять существующее изображение в презентации.

Типичный сценарий использования нового API может выглядеть следующим образом:

using (Presentation pres = new Presentation())
{
    IPPImage ppImage;
    // создать освобождаемый экземпляр IImage из файла на диске.  
    using (IImage image = Images.FromFile("image.png"))
    {
        // создать изображение PowerPoint, добавив экземпляр IImage в коллекцию изображений презентации.
        ppImage = pres.Images.AddImage(image);
    }

    // добавить форму изображения на слайд №1
    pres.Slides[0].Shapes.AddPictureFrame(ShapeType.Rectangle, 10, 10, 100, 100, ppImage);

    // получить экземпляр IImage, представляющий слайд №1.
    using (var slideImage = pres.Slides[0].GetImage(new Size(1920, 1080)))
    {
        // сохранить изображение на диске.
        slideImage.Save("slide1.jpeg", ImageFormat.Jpeg);
    }
}

Замена старого кода на Modern API

Для упрощения перехода интерфейс нового IImage повторяет отдельные подписи классов Image и Bitmap. Как правило, достаточно заменить вызов старого метода, использующего System.Drawing, на новый.

Получение миниатюры слайда

Устаревший/наследованный API:

using (Presentation pres = new Presentation("pres.pptx"))
{
    pres.Slides[0].GetThumbnail().Save("slide1.png");
}

Modern API:

using (Presentation pres = new Presentation("pres.pptx"))
{
    pres.Slides[0].GetImage().Save("slide1.png");
}

Получение миниатюры фигуры

Устаревший/наследованный API:

using (Presentation pres = new Presentation("pres.pptx"))
{
    pres.Slides[0].Shapes[0].GetThumbnail().Save("shape.png");
}

Modern API:

using (Presentation pres = new Presentation("pres.pptx"))
{
    pres.Slides[0].Shapes[0].GetImage().Save("shape.png");
}

Получение миниатюры презентации

Устаревший/наследованный API:

using (Presentation pres = new Presentation("pres.pptx"))
{
    var bitmaps = pres.GetThumbnails(new RenderingOptions(), new Size(1980, 1028));
    try
    {
        for (var index = 0; index < bitmaps.Length; index++)
        {
            Bitmap thumbnail = bitmaps[index];
            thumbnail.Save($"slide{index}.png", ImageFormat.Png);
        }
    }
    finally
    {
        foreach (Bitmap bitmap in bitmaps)
        {
            bitmap.Dispose();
        }
    }
}

Modern API:

using (Presentation pres = new Presentation("pres.pptx"))
{
    var images = pres.GetImages(new RenderingOptions(), new Size(1980, 1028));
    try
    {
        for (var index = 0; index < images.Length; index++)
        {
            IImage thumbnail = images[index];
            thumbnail.Save($"slide{index}.png", ImageFormat.Png);
        }
    }
    finally
    {
        foreach (IImage image in images)
        {
            image.Dispose();
        }
    }
}

Добавление изображения в презентацию

Устаревший/наследованный API:

using (Presentation pres = new Presentation())
{
    IPPImage ppImage;
    using (Image image = Image.FromFile("image.png"))
    {
        ppImage = pres.Images.AddImage(image);
    }

    pres.Slides[0].Shapes.AddPictureFrame(ShapeType.Rectangle, 10, 10, 100, 100, ppImage);
}

Modern API:

using (Presentation pres = new Presentation())
{
    IPPImage ppImage;
    using (IImage image = Aspose.Slides.Images.FromFile("image.png"))
    {
        ppImage = pres.Images.AddImage(image);
    }

    pres.Slides[0].Shapes.AddPictureFrame(ShapeType.Rectangle, 10, 10, 100, 100, ppImage);
}

Устаревшие методы/свойства и их замены в Modern API

Presentation

Подпись метода	Подпись заменяющего метода
public Bitmap[] GetThumbnails(IRenderingOptions options)	GetImages(IRenderingOptions options)
public Bitmap[] GetThumbnails(IRenderingOptions options, int[] slides)	GetImages(IRenderingOptions options, int[] slides)
public Bitmap[] GetThumbnails(IRenderingOptions options, float scaleX, float scaleY)	GetImages(IRenderingOptions options, float scaleX, float scaleY)
public Bitmap[] GetThumbnails(IRenderingOptions options, int[] slides, float scaleX, float scaleY)	GetImages(IRenderingOptions options, int[] slides, float scaleX, float scaleY)
public Bitmap[] GetThumbnails(IRenderingOptions options, Size imageSize)	GetImages(IRenderingOptions options, Size imageSize)
public Bitmap[] GetThumbnails(IRenderingOptions options, int[] slides, Size imageSize)	GetImages(IRenderingOptions options, int[] slides, Size imageSize)
public void Save(string fname, SaveFormat format, HttpResponse response, bool showInline)	No Modern API replacement
public void Save(string fname, SaveFormat format, ISaveOptions options, HttpResponse response, bool showInline)	No Modern API replacement
public void Print()	No Modern API replacement
public void Print(PrinterSettings printerSettings)	No Modern API replacement
public void Print(string printerName)	No Modern API replacement
public void Print(PrinterSettings printerSettings, string presName)	No Modern API replacement

Shape

Подпись метода	Подпись заменяющего метода
public Bitmap GetThumbnail()	GetImage
public Bitmap GetThumbnail(ShapeThumbnailBounds bounds, float scaleX, float scaleY)	GetImage(ShapeThumbnailBounds bounds, float scaleX, float scaleY)

Slide

Подпись метода	Подпись заменяющего метода
public Bitmap GetThumbnail(float scaleX, float scaleY)	GetImage(float scaleX, float scaleY)
public Bitmap GetThumbnail()	GetImage
public Bitmap GetThumbnail(IRenderingOptions options)	GetImage(IRenderingOptions options)
public Bitmap GetThumbnail(Size imageSize)	GetImage(Size imageSize)
public Bitmap GetThumbnail(ITiffOptions options)	GetImage(ITiffOptions options)
public Bitmap GetThumbnail(IRenderingOptions options, float scaleX, float scaleY)	GetImage(IRenderingOptions options, float scaleX, float scaleY)
public Bitmap GetThumbnail(IRenderingOptions options, Size imageSize)	GetImage(IRenderingOptions options, Size imageSize)
public void RenderToGraphics(IRenderingOptions options, Graphics graphics)	No Modern API replacement
public void RenderToGraphics(IRenderingOptions options, Graphics graphics, float scaleX, float scaleY)	No Modern API replacement
public void RenderToGraphics(IRenderingOptions options, Graphics graphics, Size renderingSize)	No Modern API replacement

Output

Подпись метода	Подпись заменяющего метода
public IOutputFile Add(string path, Image image)	Add(string path, IImage image)

ImageCollection

Подпись метода	Подпись заменяющего метода
IPPImage AddImage(Image image)	AddImage(IImage image)

ImageWrapperFactory

Подпись метода	Подпись заменяющего метода
IImageWrapper CreateImageWrapper(Image image)	CreateImageWrapper(IImage image)

PPImage

Подпись метода/свойства	Подпись заменяющего метода
void ReplaceImage(Image newImage)	ReplaceImage(IImage newImage)
Image SystemImage { get; }	IImage Image { get; }

PatternFormat

Подпись метода	Подпись заменяющего метода
Bitmap GetTileImage(Color background, Color foreground)	GetTile(Color background, Color foreground)
Bitmap GetTileImage(Color styleColor)	GetTile(Color styleColor)

IPatternFormatEffectiveData

Подпись метода	Подпись заменяющего метода
Bitmap GetTileImage(Color background, Color foreground)	GetTileIImage(SlidesImage image)

Поддержка Graphics и PrinterSettings в API

Класс Graphics не поддерживается в кросс‑платформенных версиях .NET 6 и выше. В Aspose Slides используйте методы рендеринга изображений Modern API вместо API, который рендерит в Graphics: ISlide

Также API, связанный с печатью через PrinterSettings, не имеет прямой замены в Modern API:

IPresentation:

FAQ

Почему убрали Graphics?

Поддержка Graphics объявлена устаревшей в публичном API для унификации работы с рендерингом и изображениями, устранения привязки к платформо‑специфичным зависимостям и перехода к кросс‑платформенному подходу с использованием IImage. Вместо рендеринга в Graphics используйте GetImage или GetImages.

В чём практическая выгода IImage по сравнению с Image/Bitmap?

IImage объединяет работу как с растровыми, так и с векторными изображениями, упрощает сохранение в различные форматы через ImageFormat, снижает зависимость от System.Drawing и делает код более переносимым между средами.

Повлияет ли Modern API на производительность генерации миниатюр?

Переход от GetThumbnail к GetImage не ухудшает сценарии: новые методы предоставляют те же возможности по созданию изображений с различными параметрами и размерами, сохраняя поддержку параметров рендеринга. Конкретный прирост или падение производительности зависит от сценария, но функционально замены эквивалентны.

Поддержка .NET 6 Обновления поддерживаемых целевых платформ