ایجاد اسناد غوطه‌ور که به کاربران اجازه می‌دهد مدل‌های سه‌بعدی را چرخانده، بزرگ‌نمایی کنند و به‌صورت مستقیم داخل یک PDF بررسی کنند، روشی قدرتمند برای ارتقاء کاتالوگ‌های محصول، گزارش‌های مهندسی و دفترچه‌های آموزشی است. Aspose.Words Cloud SDK for .NET کتابخانه‌ای مبتنی بر ابر فراهم می‌کند که ادغام و حفظ محتوای 3D را هنگام تبدیل فایل‌های DOCX به PDF آسان می‌سازد. در این راهنما خواهید آموخت که چگونه PDF تعاملی 3D را در C# تولید کنید، یک نمونه کامل کد را ببینید، فراخوانی‌های REST معادل cURL را بررسی کنید و ملاحظات استقرار برای برنامه‌های دنیای واقعی را درک کنید.

نیازمندی‌های سناریوی تولید PDF سه‌بعدی

توسعه‌دهندگانی که پورتال‌های مهندسی یا بروشورهای تعاملی محصول را می‌سازند، اغلب نیاز دارند PDFهایی ارائه دهند که شامل مدل‌های سه‌بعدی جاسازی‌شده باشند. الزامات معمول عبارتند از:

  • سند منبع باید یک DOCX باشد که قبلاً شامل یک مدل 3D در فرمت U3D یا PRC باشد.
  • PDF حاصل باید داده‌های 3D را حفظ کند تا مرورگرهایی مانند Adobe Acrobat بتوانند آن را به‌صورت تعاملی رندر کنند.
  • فرآیند تبدیل باید خودکار باشد، روی سرور اجرا شود و بدون نیاز به مداخله دستی، با دسته‌های بزرگ کار کند.

ابزارهای دسکتاپ سنتی نمی‌توانند به‌صورت قابل اعتماد در محیط ابری اسکریپت شوند و اغلب جریان‌های 3D را در حین تبدیل حذف می‌کنند. بنابراین یک راه‌حل برنامه‌نویسی که مدل 3D را حفظ کند و در عین حال سازگاری PDF/A را ارائه دهد، ضروری است.

رویکرد: استفاده از Aspose.Words Cloud برای PDF سه‌بعدی

Aspose.Words Cloud SDK for .NET یک مجموعه از عملیات مبتنی بر REST را ارائه می‌دهد که بر روی سرورهای امن Aspose اجرا می‌شوند. قابلیت‌های کلیدی که این سناریو را پوشش می‌دهند عبارتند از:

  • بارگذاری مستقیم فایل‌های DOCX به ذخیره‌سازی Aspose Cloud.
  • PdfSaveOptionsData که به شما امکان کنترل سازگاری PDF، به‌روزرسانی فیلدها و به‌ویژه حفظ محتوای سه‌بعدی جاسازی‌شده را می‌دهد.
  • روش‌های تبدیل ناهمزمان که یک جریان (stream) برمی‌گردانند و به شما اجازه می‌دهند فایل خروجی را مستقیماً روی دیسک بنویسید.

این ویژگی‌ها با هم یک جریان کاری تمیز از 3D به PDF را فراهم می‌کنند که می‌تواند در خطوط لوله CI، سرویس‌های وب یا کارهای پس‌زمینه یکپارچه شود. اطلاعات دقیق API در مستندات رسمی و مرجع API موجود است.

تولید PDF تعاملی 3D در C#: پیاده‌سازی

در زیر یک راهنمای گام‌به‌گام از پیاده‌سازی آورده شده است. هر گام شامل یک قطعه کد کوتاه است که مستقیماً از مثال کامل گرفته شده است.

نصب Aspose.Words Cloud SDK for .NET

ابتدا بسته NuGet را به پروژهٔ خود اضافه کنید.

dotnet add package Aspose.Words-Cloud

شما همچنین می‌توانید باینری‌ها را از صفحهٔ دانلود دریافت کنید.

پیکربندی WordsApi Client

یک شیء Configuration با اعتبارهای مشتری خود ایجاد کنید و WordsApi را نمونه‌سازی کنید.

var config = new Configuration
{
    ClientId = "YOUR_CLIENT_ID",
    ClientSecret = "YOUR_CLIENT_SECRET"
};
var wordsApi = new WordsApi(config);

WordsApi کلاس در مرجع API مستند شده است.

بارگذاری یک DOCX که شامل یک مدل 3D جاسازی شده است

فایل DOCX محلی را باز کنید و آن را به ذخیره‌سازی Aspose Cloud بارگذاری کنید، به‌طوری که هر فایلی که با همان نام وجود دارد بازنویسی شود.

using (var fileStream = File.OpenRead(localDocxPath))
{
    var uploadRequest = new UploadFileRequest(fileStream, remoteFileName);
    await wordsApi.UploadFileAsync(uploadRequest);
}

اطمینان حاصل کنید که فایل DOCX از قبل شامل یک مدل U3D یا PRC باشد؛ این قالب مدل 3D است که SDK حفظ می‌کند.

تنظیم گزینه‌های ذخیره‌سازی PDF برای حفظ محتوای 3D

PdfSaveOptionsData را پیکربندی کنید تا جریان‌های 3D را حفظ کرده و از سازگاری PDF/A‑1b استفاده کنید.

var pdfOptions = new PdfSaveOptionsData
{
    UpdateFields = false,
    Compliance = PdfCompliance.PdfA1b,
    SaveFormat = "pdf"
};

این گزینه‌ها بخشی از 3D to PDF Workflow هستند که اطمینان می‌دهند مدل تعاملی دست نخورده باقی بماند.

تبدیل و دانلود PDF تعاملی 3 بعدی

درخواست تبدیل را فراخوانی کنید و جریان حاصل را در یک فایل PDF محلی بنویسید.

var convertRequest = new ConvertDocumentRequest(
    remoteFileName,
    format: "pdf",
    saveOptions: pdfOptions
);

using (var pdfStream = await wordsApi.ConvertDocumentAsync(convertRequest))
using (var fileWriter = File.Create(outputPdfPath))
{
    await pdfStream.CopyToAsync(fileWriter);
}

پس از تبدیل می‌توانید به‌اختیار فایل موقت را از ذخیره‌سازی ابری حذف کنید.

مثال کامل کد: تولید PDF سه‌بعدی تعاملی در C#

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

using System;
using System.IO;
using System.Threading.Tasks;
using Aspose.Words.Cloud.Sdk;
using Aspose.Words.Cloud.Sdk.Model;
using Aspose.Words.Cloud.Sdk.Model.Requests;

namespace Generate3DPdfExample
{
    class Program
    {
        static async Task Main(string[] args)
        {
            // -----------------------------------------------------------------
            // 1. Configure Aspose.Words Cloud client (replace with your credentials)
            // -----------------------------------------------------------------
            var config = new Configuration
            {
                ClientId = "YOUR_CLIENT_ID",
                ClientSecret = "YOUR_CLIENT_SECRET"
            };
            var wordsApi = new WordsApi(config);

// -----------------------------------------------------------------
            // 2. Define file names and paths (generic placeholders)
            // -----------------------------------------------------------------
            const string localDocxPath = "input.docx";   // DOCX that already contains an embedded 3D model (U3D/PRC)
            const string remoteFileName = "input.docx"; // Name used in Aspose Cloud storage
            const string outputPdfPath = "output.pdf";

// -----------------------------------------------------------------
            // 3. Upload the DOCX to Aspose Cloud storage (overwrites if exists)
            // -----------------------------------------------------------------
            using (var fileStream = File.OpenRead(localDocxPath))
            {
                var uploadRequest = new UploadFileRequest(fileStream, remoteFileName);
                await wordsApi.UploadFileAsync(uploadRequest);
            }

// -----------------------------------------------------------------
            // 4. Prepare PDF save options – enable 3D content preservation
            // -----------------------------------------------------------------
            var pdfOptions = new PdfSaveOptionsData
            {
                // Preserve the embedded 3D model; the option name may vary depending on API version.
                // Setting 'UpdateFields' to false speeds up conversion when fields are not required.
                UpdateFields = false,
                // Use PDF/A-1b compliance to keep the document portable while still supporting 3D.
                Compliance = PdfCompliance.PdfA1b,
                // Ensure the output is a single PDF file.
                SaveFormat = "pdf"
            };

// -----------------------------------------------------------------
            // 5. Convert the uploaded DOCX to PDF with the defined options
            // -----------------------------------------------------------------
            var convertRequest = new ConvertDocumentRequest(
                remoteFileName,
                format: "pdf",
                saveOptions: pdfOptions
            );

using (var pdfStream = await wordsApi.ConvertDocumentAsync(convertRequest))
            using (var fileWriter = File.Create(outputPdfPath))
            {
                await pdfStream.CopyToAsync(fileWriter);
            }

// -----------------------------------------------------------------
            // 6. Clean up remote file (optional)
            // -----------------------------------------------------------------
            var deleteRequest = new DeleteFileRequest(remoteFileName);
            await wordsApi.DeleteFileAsync(deleteRequest);

Console.WriteLine($"3D PDF generated successfully at '{Path.GetFullPath(outputPdfPath)}'.");
        }
    }
}

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. پیش از استفاده از آن در پروژه خود، مطمئن شوید مسیرهای فایل (input.docx، output.pdf و غیره) را به مکان‌های واقعی خود به‌روز کنید، اطمینان حاصل کنید تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند، و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه نمایید.

انجام تبدیل PDF سه‌بعدی با cURL و REST API

همین عملیات می‌تواند از طریق تماس‌های cURL به نقطه‌های انتهایی REST سرویس Aspose.Words Cloud اجرا شود.

  1. دریافت یک توکن دسترسی (مقادیر جایگزین را با اعتبارهای خود جایگزین کنید).
curl -X POST "https://api.aspose.cloud/connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
  1. بارگذاری DOCX که شامل مدل 3D است.
curl -X PUT "https://api.aspose.cloud/v4.0/words/storage/file/input.docx" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @input.docx
  1. درخواست تبدیل PDF با حفظ سه‌بعدی
curl -X POST "https://api.aspose.cloud/v4.0/words/input.docx/saveAs/pdf" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "PdfSaveOptions": {
            "UpdateFields": false,
            "Compliance": "PdfA1b"
        }
      }' \
  -o output.pdf
  1. نتیجه PDF را دانلود کنید (دستور قبلی آن را به‌صورت محلی ذخیره کرده است، اما می‌توانید آن را مستقیماً نیز دریافت کنید).

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

ملاحظات استقرار برای تولید PDF سه‌بعدی

هنگام ادغام این راه‌حل در محیط تولید، نکات زیر را در نظر بگیرید:

  • محل سرور - تبدیل بر روی سرورهای ابری Aspose اجرا می‌شود، بنابراین اطمینان حاصل کنید که شبکه شما اجازه ترافیک خروجی HTTPS به api.aspose.cloud را دارد.
  • مجوزدهی - برای استفاده در محیط تولید، یک مجوز تجاری لازم است. می‌توانید با یک مجوز موقت از صفحه مجوز موقت شروع کنید.
  • قابلیت مقیاس‌پذیری - از آنجا که API بدون وضعیت است، می‌توانید بارگذاری‌ها و تبدیل‌ها را به صورت موازی بر روی چندین نمونه کارگر انجام دهید تا بتوانید دسته‌های با حجم بالا را مدیریت کنید و از اتوماتیک‌سازی 3D به PDF کامل پشتیبانی کنید.

نتیجه‌گیری

ایجاد PDF تعاملی 3D در C# با استفاده از Aspose.Words Cloud SDK for .NET به سادگی انجام می‌شود. با دنبال کردن مراحل بالا می‌توانید مدل‌های U3D یا PRC را جاسازی کنید، آنها را در طول تبدیل PDF حفظ کنید و جریان کار را با استفاده از کتابخانه .NET یا تماس‌های مستقیم REST خودکار کنید. به‌خاطر داشته باشید که برای تولید یک لایسنس مناسب تهیه کنید و PDFهای تولید شده را در یک نمایشگر که از 3D پشتیبانی می‌کند، مانند Adobe Acrobat، تست کنید. با این قابلیت می‌توانید اسناد غنی‌تر و جذاب‌تری برای مهندسی، بازاریابی و سناریوهای آموزشی ارائه دهید.

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

چگونه می‌توانم PDF تعاملی 3D را در C# با استفاده از Aspose.Words Cloud تولید کنم؟
از SDK برای بارگذاری یک فایل DOCX که از پیش شامل مدل U3D یا PRC است، استفاده کنید، PdfSaveOptionsData را پیکربندی کنید تا جریان‌های 3D حفظ شوند، و ConvertDocumentAsync را فراخوانی کنید. مثال کامل کد در این مقاله توالی دقیق را نشان می‌دهد.

کدام فرمت‌های مدل 3D را می‌توانم برای تبدیل PDF جاسازی کنم؟
Aspose.Words Cloud از فرمت‌های U3D و PRC پشتیبانی می‌کند، که فرمت‌های استاندارد برای محتوای تعاملی 3D در PDFها هستند.

آیا امکان اجرای تبدیل بدون نوشتن هیچ کد C# ای وجود دارد؟
بله، همان فرآیند می‌تواند با دستورات cURL در مقابل Aspose.Words Cloud REST API انجام شود، همان‌طور که در بخش cURL نشان داده شده است.

کجا می‌توانم اطلاعات قیمت‌گذاری و مجوزها را پیدا کنم؟
جزئیات مجوزهای تجاری در صفحه محصول موجود است و می‌توانید یک مجوز موقت برای ارزیابی از صفحه مجوز موقت دریافت کنید.

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