الإعداد في .NET Standard / Core

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

ملف Startup.cs

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

Startup.cs
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    appBranch =>
    {
        appBranch.UseDoconut(new DoconutOptions { UnsafeMode = false, ShowDoconutInfo = false });
    }
);

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

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

Usings
using Doconut;
using Doconut.Configs;
using Doconut.Clouds;

// TODO: implement licence loading, viewer registration, document opening, conversion using current API

إنشاء كائن Viewer

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

Instantiation
// Viewer is injected; no explicit construction required in Doconut.NETStandard 26.9.0

إعداد كائن DocOptions

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

DocOptions
var documentOptions = new DocOptions
{
    Password = "",
    // ImageResolution is obsolete; omitted.
    TimeOut = 30
};

إعداد كائن config

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

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

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

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

OpenDocument
dynamic viewer = null;
var token = viewer.LoadDocument(path, null, null);

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

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

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

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

HTML Headers
<link rel="stylesheet" href="css/viewer.css" />

<!-- Main Viewer Related Scripts -->
<script src="scripts/jquery.min.js"></script>
<script src="scripts/docViewer.js"></script>
<script src="scripts/splitter.js"></script>
<script src="scripts/search.js"></script>
<script src="scripts/documentLinks.js"></script>

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

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

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

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

C#
```csharp
// Create a Viewer instance using the current API (no constructor arguments required).
var docViewer = new Viewer();
```

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

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

C#
using System.IO;
using Microsoft.Extensions.DependencyInjection;
using Doconut;

var licenseFilePath = Path.Combine(builder.Environment.WebRootPath, "path/to/your/license");
var docViewer = app.Services.GetRequiredService<Viewer>();

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

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

C#
using System.IO;
using Doconut.Infrastructure.Licensing;

using (var licenseStream = new FileStream("path/to/your/license", FileMode.Open, FileAccess.Read))
{
    var license = new DoconutLicense { DocBytes = new BinaryReader(licenseStream).ReadBytes((int)licenseStream.Length) };
}

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

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

C#
using System.Xml;
using Doconut.Infrastructure.Licensing;

var xmlDoc = new XmlDocument(); // load the license XML
xmlDoc.Load("path/to/your/license.xml");
var license = new DoconutLicense(); // instantiate license object (populate properties as needed)

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

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

C#
```csharp
// Prepare the paths to the viewer licence files (kept for reference; the current API loads them automatically)
var licenseFilePaths = new List<string>
{
    Path.Combine(_hostingEnvironment.WebRootPath, "Doconut.Viewer.lic"),
    Path.Combine(_hostingEnvironment.WebRootPath, "Doconut.Viewer.Annotation.lic"),
    Path.Combine(_hostingEnvironment.WebRootPath, "Doconut.Viewer.Search.lic")
};

// The Viewer class no longer requires the licences in its constructor.
// Create an instance with the default constructor.
var docViewer = new Viewer();

// Open a document (e.g., a PDF) and obtain a token that represents the opened file.
string token = await docViewer.OpenDocumentAsync(
    filePath: Path.Combine(_hostingEnvironment.WebRootPath, "sample.pdf"),
    options: new DocOptions(),
    ct: CancellationToken.None);
```

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

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

C#
using (var pluginLicenseStream = new FileStream("path/to/your/plugin-license.lic", FileMode.Open))
{
    // In Doconut.NETStandard 26.9.0 the license is supplied via the configuration
    // passed to OpenDocumentAsync (BaseConfig), so the explicit SetLicensePlugin call
    // is no longer required. Keep the license file accessible to the viewer or
    // include it in your BaseConfig as shown in other samples.
}

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

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

C#
// The license XML is discovered automatically by the viewer in Doconut.NETStandard 26.9.0.
// No explicit API call is required to register it.

string token = await Viewer.OpenDocumentAsync(
    "path/to/your/document.pdf",
    null, // DocOptions – use default settings
    CancellationToken.None);

حزم 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#
using Doconut.Annotations;
using System.Drawing;

// Placeholder: open the document and obtain page dimensions using the current Doconut.NETStandard API.
// Placeholder: create an annotation manager for the page size.

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

// Placeholder: add the annotation to the manager and load the annotation XML back into the viewer using the current API.

في 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 التي تعتمد على خطوط غير مثبتة في دلائل الخطوط الافتراضية للنظام.

Usage
var config = new WordConfig
{
    FontFolders = new string[] { "C:\\CustomFonts", "D:\\SharedFonts" }
};

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

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

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

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

Usage
var emailConfig = new EmailConfig {
    EmailEncoding = Encoding.UTF8 // Set preferred email encoding
};

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

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

Usage
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. وهذا مفيد بشكل خاص للغات التي لديها متطلبات تنسيق محددة.

Usage
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)