تبدیل اسناد Word به تصاویر با کیفیت بالا یک نیاز متداول برای تولید پیش‌نمایش، ایجاد تصویر بندانگشتی و داشبوردهای گزارش‌گیری است. Aspose.OMR Cloud SDK for .NET کتابخانه‌ای قدرتمند مبتنی بر ابر فراهم می‌کند که تبدیل فایل‌های DOCX به تصاویر PNG را از کد C# آسان می‌سازد. در این آموزش شما یاد خواهید گرفت چگونه DOCX را به PNG در C# تبدیل کنید با تنظیم SDK، نوشتن یک مثال کامل ناهمزمان، و استفاده از تماس‌های cURL معادل برای یکپارچه‌سازی REST. در پایان می‌توانید PNGهای شفاف را از هر DOCX تنها با چند خط کد تولید کنید.

گردش کار DOCX به PNG - پیش‌نیازها و تنظیمات

قبل از شروع، مطمئن شوید که موارد زیر را دارید:

  • .NET 6.0 یا بالاتر نصب شده باشد.
  • یک حساب Aspose Cloud با اعتبارهای API (Client ID و Client Secret).
  • دسترسی به اینترنت برای فراخوانی سرویس Aspose OMR Cloud.

SDK را از طریق NuGet نصب کنید:

dotnet add package Aspose.OMR-Cloud

آخرین بسته را دانلود کنید و یادداشت‌های انتشار را اینجا مشاهده کنید: Aspose.OMR Cloud SDK for .NET Download. برای استفاده دقیق از API، به مستندات رسمی مراجعه کنید.

برای استفاده از SDK باید آن را با اعتبارنامه‌های خود پیکربندی کنید:

var config = new Configuration
{
    BasePath = "https://api.aspose.cloud",
    ApiKey = Environment.GetEnvironmentVariable("ASPOSE_OMR_API_KEY")
};

با داشتن پیکربندی، آماده‌اید تا جریان کار تبدیل را شروع کنید.

راهنمای گام‌به‌گام برای تبدیل DOCX به PNG در C#

مرحله 1: بارگذاری سند منبع

فایل DOCX را به‌عنوان یک جریان باز کنید تا از بارگذاری کل فایل در حافظه جلوگیری شود.

using var inputStream = new FileStream(inputDocxPath, FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize: 81920, useAsync: true);

مرحله ۲: ساخت درخواست تبدیل

یک ConvertDocumentRequest ایجاد کنید و فرمت خروجی را به PNG مشخص کنید. ConvertOptions به شما امکان می‌دهد پس‌زمینه شفاف و DPI را تنظیم کنید.

var conversionRequest = new ConvertDocumentRequest
{
    InputFile = await ReadStreamFullyAsync(inputStream),
    OutputFormat = "png",
    Options = new ConvertOptions
    {
        TransparentBackground = true,
        Dpi = 150
    }
};

مرحله 3: فراخوانی API تبدیل

متد ناهمزمان را برای انجام تبدیل فراخوانی کنید.

byte[] pngResult = await omrApi.ConvertDocumentAsync(conversionRequest);

مرحله 4: ذخیره نتیجه PNG

آرایه بایت بازگشتی را در یک فایل روی دیسک بنویسید.

await File.WriteAllBytesAsync(outputPngPath, pngResult);
Console.WriteLine($"DOCX successfully converted to PNG: {outputPngPath}");

مرحله 5: مدیریت استثناها

برای مقاوم‌سازی فرآیند، خطاهای API و I/O را بگیرید.

catch (ApiException apiEx)
{
    Console.Error.WriteLine($"Aspose OMR API error (Code {apiEx.ErrorCode}): {apiEx.Message}");
}
catch (IOException ioEx)
{
    Console.Error.WriteLine($"File I/O error: {ioEx.Message}");
}
catch (Exception ex)
{
    Console.Error.WriteLine($"Unexpected error: {ex.Message}");
}

تبدیل فایل‌های DOCX به PNG در C# - مثال کامل کد

مثال زیر فرآیند تبدیل کامل انتها به انتها را نشان می‌دهد.

using System;
using System.IO;
using System.Threading.Tasks;
using Aspose.OMR.Cloud.Sdk.Api;
using Aspose.OMR.Cloud.Sdk.Client;
using Aspose.OMR.Cloud.Sdk.Model;

class Program
{
    static async Task Main(string[] args)
    {
        // -----------------------------------------------------------------
        // Configuration – replace with your actual credentials/environment
        // -----------------------------------------------------------------
        var config = new Configuration
        {
            // Base URL for Aspose OMR Cloud API
            BasePath = "https://api.aspose.cloud",
            // API key (or JWT) – read from environment for security
            ApiKey = Environment.GetEnvironmentVariable("ASPOSE_OMR_API_KEY")
        };

// Initialize the OMR API client
        var omrApi = new OMRApi(config);

// Input DOCX and output PNG paths (generic placeholders)
        const string inputDocxPath = "input.docx";
        const string outputPngPath = "output.png";

try
        {
            // -------------------------------------------------------------
            // Stream the DOCX file – avoids loading the whole file into RAM
            // -------------------------------------------------------------
            using var inputStream = new FileStream(inputDocxPath, FileMode.Open, FileAccess.Read, FileShare.Read, bufferSize: 81920, useAsync: true);

// -------------------------------------------------------------
            // Build conversion request with transparent PNG option
            // -------------------------------------------------------------
            var conversionRequest = new ConvertDocumentRequest
            {
                // The SDK expects the document as a byte array; copy via stream efficiently
                InputFile = await ReadStreamFullyAsync(inputStream),
                OutputFormat = "png",
                // Optional conversion settings
                Options = new ConvertOptions
                {
                    // Ensure PNG background is transparent
                    TransparentBackground = true,
                    // For large documents, limit DPI to balance quality/performance
                    Dpi = 150
                }
            };

// -------------------------------------------------------------
            // Perform the conversion (async)
            // -------------------------------------------------------------
            byte[] pngResult = await omrApi.ConvertDocumentAsync(conversionRequest);

// -------------------------------------------------------------
            // Write the resulting PNG to disk
            // -------------------------------------------------------------
            await File.WriteAllBytesAsync(outputPngPath, pngResult);
            Console.WriteLine($"DOCX successfully converted to PNG: {outputPngPath}");
        }
        catch (ApiException apiEx)
        {
            // Handles errors returned by the Aspose OMR service
            Console.Error.WriteLine($"Aspose OMR API error (Code {apiEx.ErrorCode}): {apiEx.Message}");
        }
        catch (IOException ioEx)
        {
            // Handles file‑system related errors
            Console.Error.WriteLine($"File I/O error: {ioEx.Message}");
        }
        catch (Exception ex)
        {
            // Catch‑all for any other unexpected issues
            Console.Error.WriteLine($"Unexpected error: {ex.Message}");
        }
    }

// -----------------------------------------------------------------
    // Helper: reads a stream fully into a byte array without blocking UI
    // -----------------------------------------------------------------
    private static async Task<byte[]> ReadStreamFullyAsync(Stream stream)
    {
        if (stream is MemoryStream ms && ms.TryGetBuffer(out var buffer))
            return buffer.Array;

using var memory = new MemoryStream();
        await stream.CopyToAsync(memory);
        return memory.ToArray();
    }
}

Note: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه‌تان، اطمینان حاصل کنید که مسیرهای فایل و مقادیر پیکربندی را به‌گونه‌ای به‌روزرسانی کنید که با محیط واقعی شما مطابقت داشته باشد، تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند، و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه کنید.

تبدیل اسناد Word به PNG از طریق REST API با استفاده از cURL

می‌توانید همان نتیجه را با تماس‌های مستقیم REST به دست آورید. در زیر یک جریان کاری معمولی cURL آورده شده است.

  1. دریافت توکن دسترسی (مقادیر جایگزین را با اعتبارهای خود جایگزین کنید).
curl -X POST "https://api.aspose.cloud/connect/token" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
  1. فایل DOCX را بارگذاری کنید به نقطه انتهایی ذخیره‌سازی.
curl -X PUT "https://api.aspose.cloud/v4.0/words/storage/file/input.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -T "input.docx"
  1. درخواست تبدیل به PNG (پس‌زمینه شفاف فعال است).
curl -X POST "https://api.aspose.cloud/v4.0/omr/convert?outputFormat=png&transparentBackground=true&dpi=150" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/octet-stream" \
     --data-binary "@input.docx" \
     -o output.png
  1. نتیجه PNG را دانلود کنید (اگر از نقطه انتهایی کار جداگانه استفاده کرده‌اید).
curl -X GET "https://api.aspose.cloud/v4.0/omr/result/output.png" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.png

برای جزئیات بیشتر در مورد پارامترهای درخواست، به مرجع API مراجعه کنید.

تنظیمات خروجی PNG: گزینه‌ها و تنظیمات

شیء ConvertOptions به شما امکان تنظیم دقیق خروجی PNG را می‌دهد. دو تنظیم مهم در کد نشان داده شده‌اند:

  • TransparentBackground - وقتی به true تنظیم شود، PNG تولید شده هیچ رنگ پس‌زمینه‌ای ندارد که برای سناریوهای هم‌پوشانی مفید است.
  • Dpi - وضوح تصویر را کنترل می‌کند. DPI بالاتر تصاویر واضح‌تری تولید می‌کند اما مصرف حافظه را افزایش می‌دهد. برای بیشتر موارد استفاده وب، 150 DPI تعادل مناسبی بین کیفیت و عملکرد فراهم می‌کند.

اگر به کنترل بیشتری نیاز دارید، مانند تنظیم سطح فشرده‌سازی یا حالت رنگ، به فهرست کامل گزینه‌ها در مرجع API مراجعه کنید.

بهینه‌سازی عملکرد تبدیل اسناد بزرگ DOCX

هنگام تبدیل فایل‌های بزرگ DOCX، این نکات را در نظر بگیرید:

  • جریان ورودی - استفاده از FileStream با خواندن‌های async مصرف حافظه را کم نگه می‌دارد.
  • تنظیم DPI - کاهش DPI (مثلاً به 100) زمان پردازش و حجم خروجی را کاهش می‌دهد.
  • دوباره استفاده از کلاینت OMRApi - یک نمونه واحد ایجاد کنید و برای تبدیل‌های متعدد دوباره استفاده کنید تا از تکرار دست‌دادها جلوگیری شود.
  • اجرای تبدیل‌ها به صورت ناهمزمان - از await استفاده کنید تا نخ پاسخگو بماند، به‌ویژه در برنامه‌های وب یا UI.

به‌کارگیری این روش‌ها به شما کمک می‌کند تا به‌صورت کارآمد DOCX را به PNG در C# تبدیل کنید، حتی برای اسنادی که صفحات زیادی یا تصاویر با وضوح بالا دارند.

نتیجه‌گیری

تبدیل DOCX به PNG در C# به‌راحتی با Aspose.OMR Cloud SDK for .NET امکان‌پذیر است. با دنبال کردن مراحل بالا، می‌توانید PNGهای شفاف ایجاد کنید، فرآیند را در جریان‌های کاری server‑side ادغام کنید و عملکرد را برای فایل‌های بزرگ به‌دقت تنظیم کنید. این SDK تحت مجوز تجاری عرضه می‌شود؛ می‌توانید قیمت‌گذاری را در صفحه محصول مشاهده کنید و برای ارزیابی، یک مجوز موقت از صفحه مجوز موقت دریافت کنید. امروز شروع به ادغام تبدیل DOCX به PNG کنید و قابلیت‌های مدیریت اسناد برنامه خود را ارتقا دهید.

سوالات متداول

  • چگونه می‌توانم DOCX را به PNG در C# با استفاده از Aspose.OMR تبدیل کنم؟
    از متد async ConvertDocumentAsync که در کد نمونه نشان داده شده استفاده کنید. SDK کل فرآیند تبدیل DOCX به PNG را مدیریت می‌کند، از جمله پشتیبانی از پس‌زمینه شفاف.

  • آیا می‌توان DOCX را به PNG در .NET تبدیل کرد بدون نوشتن فایل موقت؟
    بله. با استریم کردن DOCX به یک آرایه بایت با استفاده از ReadStreamFullyAsync، تبدیل در حافظه باقی می‌ماند که برای سناریوهای ابری یا API ایده‌آل است.

  • آیا می‌توانم خروجی PNG را سفارشی کنم، برای مثال پس‌زمینه را شفاف کنم؟
    مطمئناً. مقدار TransparentBackground = true را در ConvertOptions تنظیم کنید. این امکان را می‌دهد که DOCX را به PNG در .NET با پس‌زمینه شفاف تبدیل کنید، که برای موارد استفاده به‌عنوان لایه‌گذاری ایده‌آل است.

  • کدام گزینه‌های مجوز برای Aspose.OMR Cloud SDK for .NET موجود است؟
    این SDK تحت یک مجوز تجاری در دسترس است. قیمت‌گذاری دقیق در صفحه محصول موجود است و می‌توانید یک مجوز ارزیابی موقت از صفحه مجوز موقت درخواست کنید.

بیشتر بخوانید