الإعداد في .NET 6 أو أعلى

استخدام رخصتكفعّل وطبق رخصة Doconut الخاصة بك.

ملف Startup.cs

داخل ملف Startup.cs لمشروع .NET Core، تُعرّف هذه الأسطر من الشيفرة تكوين خط أنابيب الوسيط باستخدام طريقة MapWhen. الشرط المقدم يتحقق مما إذا كان مسار الطلب الوارد ينتهي بـ DocImage.axd. داخل هذا الجزء، تُستدعى طريقة UseDoconut مع كائن DoconutOptions كمعامل.

Startup.cs
app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

إضافة مساحات أسماء Doconut

في مشروعك، أضف عبارات using التالية:

إضافة مساحات أسماء Doconut
using Doconut;
using Doconut.Configs;
using Doconut.Clouds;

إنشاء كائن Viewer

هذه السطر ينشئ نسخة جديدة من فئة Viewer، مما يتيح لك إنشاء كائن عارض داخل الشيفرة الخاصة بك.

إنشاء كائن Viewer
// License is configured via AddDoconut; obtain the viewer from DI.
var docViewer = app.Services.GetRequiredService<Viewer>();

إعداد كائن DocOptions

مثال على تهيئة كائن DocOptions بإعدادات محددة:

DocOptions
```csharp
// Document opening options – password and session timeout
var docOptions = new DocOptions
{
    Password = string.Empty,
    TimeOut = 30
};

// Per‑format rendering options – set image resolution via the format‑specific config
var pdfConfig = new PdfConfig
{
    ImageResolution = 200
};
```

إعداد كائن config

تهيئة كائن PdfConfig جديد بإعدادات محددة لمعالجة مستندات PDF:

PdfConfig
var config = new PdfConfig { DefaultRender = true, ExtractHyperlinks = true };

فتح المستند الخاص بك

هذا السطر يستدعي طريقة OpenDocument لكائن العارض، مع تمرير مسار ملف المستند الموجود على الخادم وكائنات PdfConfig و DocOptions التي تم تكوينها مسبقًا كمعاملات.

OpenDocument
var token = await viewer.OpenDocumentAsync(path, new PdfConfig
{
    AllowSearch = true,
    AllowCopy   = true,
    ImageResolution = 150
});

إضافة العارض في HTML الخاص بك

HTML
<div id="div_ctlDoc"></div>

إضافة ملفات CSS و JavaScript

أضف ملفات CSS و JavaScript التالية في الصفحة. هذه السكربتات مضمّنة في ملف ZIP مع عينات الشيفرة.

إضافة ملفات CSS و JavaScript
<!-- Main Viewer Related Scripts -->
<script src="scripts/splitter.js"></script>
<script src="scripts/docViewer.js"></script>
<script src="scripts/documentLinks.js"></script>

<!-- Viewer functions -->
<script src="scripts/docViewer.UI.js?v=1"></script>

إضافة تراخيص إلى مشروعك

اكتشاف الترخيص تلقائيًا

لتهيئة docViewer مع اكتشاف الترخيص تلقائيًا، استخدم السطر التالي:

C#
app.MapPost("/api/open", async (Viewer viewer) =>
{
    // The token is opaque — hand it to the widget, never log or persist it.
    string token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

إضافة ترخيص افتراضي يدوي

يمكنك تحديد مسار ملف ترخيص افتراضي واحد يدويًا عند تهيئة العارض.

C#
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

إضافة ترخيص عبر تدفق

تستخدم هذه الطريقة التحميل الزائد Viewer.DoconutLicense(Stream licenseStream) لإضافة ترخيص باستخدام تدفق.

C#
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

إضافة ترخيص عبر مستند XML

تستخدم هذه الطريقة التحميل الزائد Viewer.DoconutLicense(XMLDocument licence) لإضافة ترخيص باستخدام مستند XML.

C#
// License XML from a database, environment variable, or secret manager —
// no file on disk. Beaten only by LicenseStream.
builder.Services.AddDoconut(options =>
{
    options.LicenseContent = Environment.GetEnvironmentVariable("DOCONUT_LICENSE") ?? "";
});

ترخيصات إضافية متعددة يدويًا

إذا كنت بحاجة لتحديد تراخيص متعددة، يمكنك تقديم قائمة بمسارات الملفات إلى تهيئة العارض.

C#
builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state needs a cache (MVC/Razor Pages already add one)
builder.Services.AddSession(); // Doconut document security rides on ASP.NET session state

app.UseSession();          // call UseSession() before UseDoconut()
app.UseDoconutResources(); // must be registered before UseDoconut()
app.UseDoconut();

إضافة ترخيص مكوّن إضافي عبر تدفق

تستخدم هذه الطريقة التحميل الزائد Viewer.SetLicensePlugin(Stream pluginLicence) لإضافة ترخيص مكوّن إضافي باستخدام تدفق.

C#
using var pluginLicenseStream = new FileStream("path/to/your/plugin-license.lic", FileMode.Open);

builder.Services.AddDoconut(options =>
{
    // The stream takes precedence over LicenseContent, LicensePath, and auto‑search.
    options.LicenseStream = pluginLicenseStream;
});

إضافة ترخيص مكوّن إضافي عبر مستند XML

تستخدم هذه الطريقة التحميل الزائد Viewer.SetLicensePlugin(XMLDocument xmlPluginLicence) لإضافة ترخيص مكوّن إضافي باستخدام مستند XML.

C#
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
});

حزم NuGet المطلوبة

لضمان توافق مشروعك بالكامل مع .NET Core Standard، يجب تضمين حزم NuGet التالية، مرتبة أبجديًا.

  • MessagePack - Version 2.5.140
  • Microsoft.Bcl.AsyncInterfaces - Version 8.0.0
  • Microsoft.Extensions.Caching.Abstractions - Version 8.0.0
  • Microsoft.Extensions.Configuration - Version 8.0.0
  • Microsoft.Extensions.Configuration.Abstractions - Version 8.0.0
  • Microsoft.Extensions.Configuration.FileExtensions - Version 8.0.0
  • Microsoft.Extensions.Configuration.Json - Version 8.0.0
  • Microsoft.Extensions.FileProviders.Abstractions - Version 8.0.0
  • Microsoft.Extensions.FileProviders.Physical - Version 8.0.0
  • Microsoft.Extensions.FileSystemGlobbing - Version 8.0.0
  • Microsoft.Extensions.Primitives - Version 8.0.0
  • System.Buffers - Version 4.5.1
  • System.Formats.Asn1 - Version 8.0.0
  • System.Numerics.Vectors - Version 4.5.0
  • System.Security.Cryptography.Cng - Version 5.0.0
  • System.Security.Cryptography.Pkcs - Version 8.0.0
  • System.Text.Encoding.CodePages - Version 8.0.0
  • System.Text.Encodings.Web - Version 8.0.0
  • System.Text.Json - Version 8.0.3
  • System.Threading.Tasks.Extensions - Version 4.5.4

خيارات تكوين العرض

يمكنك تكوين سلوك العرض باستخدام الخيارات التالية:

  • CadConfig: يُستخدم لملفات DWG و DXF و DGN.
  • EmailConfig: يُستخدم لملفات EML و EMLX و MSG.
  • EpubConfig: يُستخدم لملفات EPUB.
  • ExcelConfig: يُستخدم لملفات Excel و CSV.
  • MhtConfig: يُستخدم لملفات MHT.
  • PptConfig: يُستخدم لملفات PowerPoint.
  • ProjectConfig: يُستخدم لملفات MPP.
  • PsdConfig: يُستخدم لملفات PSD.
  • TxtConfig: يُستخدم لملفات TXT.
  • TiffConfig: يُستخدم لملفات TIFF.

تكوين خيارات العرض

يتم تكوين خيارات العرض باستخدام الخاصية DefaultRender:

  • DefaultRender = true : يقدّم هذا الخيار عرضًا بجودة أعلى لكنه يستخدم المزيد من ذاكرة الخادم ووقت المعالجة.
  • DefaultRender = false : يوفّر هذا الخيار عرضًا أسرع على حساب جودة أقل قليلاً.

كيفية إضافة توضيح صورة

في C#

1. افتح المستند واحصل على أبعاد الصفحة الأولى. 2. ابدأ AnnotationManager بأبعاد الصفحة. 3. أنشئ ImageAnnotation، مع تحديد مسار الصورة في imgUrl، وحدد الموقع والحجم داخل Rectangle. 4. أضف التوضيح إلى المدير وحمّله في عارض المستند لعرضه.

C#
var token = await viewer.OpenDocumentAsync(pathToFile, config, documentOptions);

// The annotation manager is automatically bound to the opened document's page dimensions.
using var annMgr = viewer.GetAnnotationManager(token);

var imgAnn = new ImageAnnotation(
    1,
    new Rectangle(600, 700, 750, 300),
    "img/sample.png"
);

annMgr.Add(imgAnn);
viewer.LoadAnnotationData(token, annMgr);

في JavaScript

1. تأكد من توفر YourController. 2. أنشئ ImageAnnotation جديد، مع تحديد مسار الصورة باستخدام SetNote. 3. أضف ورسم التوضيح لعرضه على المستند.

JavaScript
function ImageStamp() {
    if (null != objctlDoc.YourController()) {
        var objStampImage = new ImageAnnotation({ left: 200, top: 200, width: 260, height: 55 });
        objctlDoc.YourController().AddAnnotation(null, objStampImage, null);

        objStampImage.SetNote('/images/Approved_Stamp.png');
        objStampImage.Paint();
    }
}

خطوط مخصصة في مستندات Word

خاصية FontFolders في فئة WordConfig تحدد دلائل مخصصة حيث سيبحث التطبيق عن الخطوط. هذا مفيد بشكل خاص لمعالجة مستندات Word التي تعتمد على خطوط غير مثبتة في دلائل الخطوط الافتراضية للنظام.

خطوط مخصصة في مستندات Word
var config = new WordConfig
{
    FontFolders = new string[] { "C:\\CustomFonts", "D:\\SharedFonts" }
};

تحديث مهم لـ Doconut 25.2.0

من الضروري تحديث حزمة System.Text.Json إلى الإصدار 8.0.5 في جميع مشاريعك. هذا التحديث حاسم لضمان التوافق مع الميزات الأخيرة ومعالجة تحسينات الأمان المهمة.

ترميز البريد الإلكتروني

خاصية EmailEncoding في فئة EmailConfig تحدد الترميز المفضّل لكل من موضوع البريد الإلكتروني ومحتواه.

ترميز البريد الإلكتروني
var emailConfig = new EmailConfig {
    EmailEncoding = Encoding.UTF8 // Set preferred email encoding
};

ترميز الموضوع والمحتوى

خاصيتي SubjectEncoding و BodyEncoding في فئة EmailConfig تحددان الترميز المستخدم للموضوع ومحتوى البريد الإلكتروني على التوالي.

ترميز الموضوع والمحتوى
var emailConfig = new EmailConfig {
    SubjectEncoding = Encoding.UTF8, // Set encoding for the subject
    BodyEncoding = Encoding.UTF8     // Set encoding for the body
};

دعم ثقافة عارض Word

تسمح لك خاصية DocumentCulture في فئة WordConfig بتحديد الثقافة بشكل صريح لملفات DOC و DOCX. يضمن ذلك أن المحتوى المحلي — مثل التواريخ والعملات والأرقام — يُعرض بالضبط كما هو في Microsoft Word. هذا مفيد بشكل خاص للغات التي لديها متطلبات تنسيق محددة.

دعم ثقافة عارض Word
var config = new WordConfig { DocumentCulture = "he-IL" }; // Hebrew (Israel)
var config = new WordConfig { DocumentCulture = "ar-SA" }; // Arabic (Saudi Arabia)
var config = new WordConfig { DocumentCulture = "th-TH" }; // Thai (Thailand)
var config = new WordConfig { DocumentCulture = "ja-JP" }; // Japanese (Japan)