將 Word 文件轉換為高品質圖像是預覽產生、縮圖建立與報告儀表板的常見需求。Aspose.OMR Cloud SDK for .NET 提供強大的雲端函式庫，使得從 C# 程式碼輕鬆將 DOCX 檔案轉換為 PNG 圖像。在本教學中，您將學習如何透過設定 SDK、編寫完整的非同步範例，以及使用等效的 cURL 呼叫進行 REST 整合，將 DOCX 轉換為 PNG。完成後，您只需幾行程式碼即可從任何 DOCX 產生透明 PNG。

DOCX 轉 PNG 工作流程 - 前置條件與設定

在開始之前，請確保您已具備以下項目：

  • 已安裝 .NET 6.0 或更高版本。
  • 具備 Aspose Cloud 帳戶及 API 憑證（Client ID 和 Client Secret）。
  • 具備連接網際網路以呼叫 Aspose OMR Cloud 服務的能力。

透過 NuGet 安裝 SDK：

dotnet add package Aspise.OMR-Cloud

下載最新套件並在此查看發行說明： Aspose.OMR Cloud SDK for .NET 下載。 如需詳細的 API 使用說明，請參閱 官方文件。

您需要使用您的憑證配置 SDK：

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

配置完成後，您已準備好開始轉換工作流程。

逐步指南：在 C# 中將 DOCX 轉換為 PNG

步驟 1：載入來源文件

以串流方式開啟 DOCX 檔案，以避免將整個檔案載入記憶體。

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

步驟 2：建立轉換請求

建立一個 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}");
}

在 C# 中將 DOCX 檔案轉換為 PNG - 完整程式碼範例

以下示例演示完整的端到端轉換過程。

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();
    }
}

注意： 此程式碼範例展示了核心功能。在您的專案中使用之前，請確保更新所有檔案路徑和設定值以符合實際環境，驗證所有必要的相依項目已正確安裝，並在開發環境中徹底測試。如遇到任何問題，請參閱官方文件或聯繫支援團隊尋求協助。

使用 cURL 透過 REST API 將 Word 文件轉換為 PNG

您可以透過直接的 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 搭配非同步讀取可保持低記憶體使用量。
  • 調整 DPI - 降低 DPI（例如，設定為 100）可減少處理時間和輸出大小。
  • 重複使用 OMRApi 客戶端 - 建立單一實例並在多次轉換中重複使用，以避免重複握手。
  • 非同步執行轉換 - 利用 await 讓執行緒保持回應，特別是在 Web 或 UI 應用程式中。

應用這些做法可幫助您在 C# 中高效地將 DOCX 轉換為 PNG，即使是頁數眾多或高解析度圖像的文件也能順利處理。

結論

在 C# 中將 DOCX 轉換為 PNG 非常簡單，只需使用 Aspose.OMR Cloud SDK for .NET。按照上述步驟，您可以生成透明 PNG，將此流程整合到伺服器端工作流程中，並針對大型檔案微調效能。此 SDK 採商業授權銷售；您可以在產品頁面查看價格，並在臨時授權頁面取得評估用的臨時授權。立即開始整合 DOCX 到 PNG 的轉換，提升應用程式的文件處理能力。

常見問題

  • 如何在 C# 中使用 Aspose.OMR 將 DOCX 轉換為 PNG？
    使用示例代碼中顯示的非同步 ConvertDocumentAsync 方法。SDK 會處理整個 DOCX 到 PNG 的工作流程，包括透明背景支援。

  • 是否可以在 .NET 中將 DOCX 轉換為 PNG 而不寫入臨時檔案？
    是的。透過使用 ReadStreamFullyAsync 將 DOCX 串流至位元組陣列，轉換過程保持在記憶體中，這對於雲端或 API 情境非常理想。

  • 我可以自訂 PNG 輸出嗎，例如將背景設為透明？
    當然可以。將 TransparentBackground = true 設定於 ConvertOptions 中。這樣即可在 .NET 中將 DOCX 轉換為具有透明背景的 PNG，非常適合疊加使用情境。

  • Aspose.OMR Cloud SDK for .NET 有哪些授權選項？
    此 SDK 採用商業授權。詳細價格資訊請參閱產品頁面，您也可以從臨時授權頁面申請臨時評估授權。

閱讀更多