جریان‌ها و پیوست‌های فایل

جریان‌ها و پیوست‌های فایل

فراتر از بارگذاری‌های پایه‌ای Document.Open/Document.Save، Aspose.PDF FOSS برای .NET کنترل دقیق‌تری بر نحوهٔ انتقال بایت‌ها به داخل و خارج یک سند به شما می‌دهد — بافرهای حافظه‌ای قابل رشد برای فایل‌های بسیار بزرگ، و یک API اختصاصی برای درج، بررسی و استخراج پیوست‌های فایل از طریق FileSpecification و EmbeddedFileCollection.

گسترش بافرهای در-حافظه‌ای فراتر از ۲GB

MemoryStream داده‌های خود را در یک آرایهٔ پیوستهٔ واحد ذخیره می‌کند که حدود ۲GB محدود می‌شود. OptimizedMemoryStream به‌جای آن داده‌ها را در تکه‌های با اندازهٔ ثابت ذخیره می‌کند، بنابراین می‌تواند اسناد بسیار بزرگ‌تری را هنگامی که یک PDF را به‌صورت کامل در حافظه ذخیره یا می‌سازید، نگه دارد.

using Aspose.Pdf;

using var doc = Document.Open("large-input.pdf");
using var buffer = new OptimizedMemoryStream();

doc.Save(buffer);

buffer.Seek(0, SeekOrigin.Begin);
byte[] allBytes = buffer.ToArray();
Console.WriteLine($"Buffer length: {buffer.Length}");

همچنین می‌توانید به‌صورت مستقیم به آن بنویسید، همان‌طور که با هر Stream انجام می‌دهید:

using var buffer = new OptimizedMemoryStream();
byte[] chunk = System.Text.Encoding.UTF8.GetBytes("raw content chunk");

buffer.Write(chunk, 0, chunk.Length);
buffer.WriteByte(0x0A);
buffer.SetLength(buffer.Length);

درج یک فایل به‌صورت مستقیم از یک جریان

FileSpecification می‌تواند به‌جای این که مجبور شوید پیوست را ابتدا در یک byte[] بافر کنید، یک Stream را بپوشاند. این زمانی مفید است که منبع پیوست خود یک جریان باشد، مانند یک دستهٔ فایل باز.

using Aspose.Pdf;

using var doc = Document.Open("input.pdf");
using var attachmentStream = File.OpenRead("report.csv");
using var spec = new FileSpecification(attachmentStream, "report.csv", "Quarterly report data");

spec.MimeType = "text/csv";
spec.AFRelationship = AFRelationship.Data;
spec.Encoding = FileEncoding.Zip;

doc.EmbeddedFiles.Add(spec);
doc.Save("with-attachment.pdf");

جاسازی یک فایل از بایت‌های خام

Document.AddEmbeddedFile یک روش راحت برای جاسازی یک فایل مستقیماً از یک آرایه بایت است، بدون اینکه به‌طور مستقیم یک FileSpecification بسازید.

using Aspose.Pdf;

using var doc = Document.Open("input.pdf");
byte[] fileData = File.ReadAllBytes("appendix.docx");

doc.AddEmbeddedFile(
    "appendix.docx",
    fileData,
    "Supporting appendix",
    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    true,
    DateTime.Now,
    DateTime.Now);

doc.Save("with-appendix.pdf");

فهرست‌گذاری و استخراج فایل‌های جاسازی‌شده

Document.EmbeddedFiles یک EmbeddedFileCollection است که می‌توانید فهرست کنید. هر ورودی یک FileSpecification است و GetData() بایت‌های خام پیوست را برمی‌گرداند.

using Aspose.Pdf;

using var doc = Document.Open("with-attachment.pdf");

if (doc.HasEmbeddedFiles)
{
    foreach (FileSpecification file in doc.EmbeddedFiles)
    {
        Console.WriteLine($"{file.Name} ({file.Size} bytes, {file.MimeType})");
        byte[] contents = file.GetData();
        File.WriteAllBytes(file.Name, contents);
    }
}

یافتن، بررسی و حذف پیوست‌ها

از FindByName برای جستجوی یک پیوست واحد استفاده کنید، Params برای خواندن متادیتای آن، و Delete/DeleteByKey برای حذف آن.

using Aspose.Pdf;

using var doc = Document.Open("with-attachment.pdf");

FileSpecification? found = doc.EmbeddedFiles.FindByName("report.csv");
if (found?.Params is FileParams info)
{
    Console.WriteLine($"{found.Name}: {info.Size} bytes, checksum {info.CheckSum}, modified {info.ModDate}");
}

doc.EmbeddedFiles.Delete("report.csv");
Console.WriteLine($"Remaining attachments: {doc.EmbeddedFiles.Count}");
doc.Save("cleaned.pdf");

نکات و بهترین شیوه‌ها

• به جای MemoryStream، هر زمان که یک سند در حافظه ممکن است بیش از ۲ گیگابایت شود، OptimizedMemoryStream را ترجیح دهید – MemoryStream زمانی که آرایه پشتیبان تک‌تکه آن به این حد برسد، استثنا می‌اندازد.
• نمونه‌های FileSpecification را آزاد کنید (و هر جریانی که به‌صورت دستی برای آن‌ها باز کرده‌اید) – FileSpecification پیاده‌سازی IDisposable است.
• قبل از پیمایش EmbeddedFiles، Document.HasEmbeddedFiles را بررسی کنید تا شمارش غیرضروری در اسنادی که پیوست ندارند، صرفنظر شود.
• MimeType و AFRelationship را بر روی هر FileSpecification تنظیم کنید تا مصرف‌کنندگان PDF پایین‌دست بتوانند پیوست‌ها را به‌درستی طبقه‌بندی کنند.
• به‌جای نوشتن یک حلقه دستی، از EmbeddedFileCollection.FindByName برای یک جستجوی نام‌دار واحد استفاده کنید.

مسائل رایج

FAQ

تفاوت بین MemoryStream و OptimizedMemoryStream چیست؟

MemoryStream بایت‌های خود را در یک آرایهٔ پیوسته ذخیره می‌کند که حدود ۲ گیگابایت محدود شده است. OptimizedMemoryStream به‌جای آن داده‌ها را در قطعات با اندازه ثابت ذخیره می‌کند، بنابراین می‌تواند از آن محدودیت فراتر برود – که برای عملیات Document.Save که به‌صورت کامل در حافظه روی فایل‌های بسیار بزرگ انجام می‌شود، مفید است.

آیا می‌توانم فایلی را بدون اینکه ابتدا آن را به یک byte[] بارگذاری کنم، جاسازی کنم؟

بله. FileSpecification(stream, name, description) یک Stream را به‌صورت مستقیم می‌پذیرد، بنابراین می‌توانید از File.OpenRead(...) یا هر جریان دیگری بدون این که خودتان آن را در حافظه بافر کنید، جاسازی کنید.

چگونه می‌توانم یک فایل جاسازی‌شده را از سند بیرون بگیرم؟

بر doc.EmbeddedFiles تکرار کنید و برای هر FileSpecification GetData() را صدا بزنید تا بایت‌های خام را بازیابی کنید.

آیا EmbeddedFileCollection.Delete(name) تمام پیوست‌هایی که همان نام را دارند حذف می‌کند؟

نه – دقیقاً یک پیوست را با DeleteByKey هدف بگیرید و کلید خاصی را از Keys استفاده کنید اگر چندین پیوست همان نام را داشته باشند.

آیا استفاده مجدد از FileSpecification در چندین سند ایمن است؟

نه. FileSpecification IDisposable را پیاده‌سازی می‌کند و یک جریان فایل جاسازی‌شدهٔ تک‌تکه را می‌پیچاند؛ برای هر پیوست در هر سند یک نمونه جدید ایجاد کنید.

API Reference خلاصه

همچنین ببینید:

• مدیریت اسناد
• مدیریت اسناد اصلی
• Aspose.PDF for .NET Enterprise Product
• Aspose.PDF for .NET — Enterprise Documentation