ملحق المحول

تحويل المستندات إلى 45 صيغة مستهدفة

يقوم ملحق Converter بتحويل Doconut إلى خدمة تحويل المستندات. إنه يقدّم المحرك وراء الواجهة العامة DocumentConverter — وبالاختيار — عنصر واجهة يُقدَّم عبر DocImage.axd، بحيث يمكنك تحويل المستندات من C#، أو من الواجهة، أو من الواجهة الأمامية التي تكتبها بنفسك.

السطحمتى تستخدمه
DocumentConverter (C#)تقوم بالتحويل على الخادم، دون مشاركة المتصفح
واجهة منسدلة (doconutConverter.js)تريد شاشة جاهزة للرفع والتحويل والتنزيل في صفحتك
نقاط النهاية HTTP على DocImage.axd (?convert=open|run|download)تبني واجهة تحويل خاصة بك ضد عقد خادم موثّق

تثبيت الحزمة

powershell
Install-Package Doconut.NETFramework.Converter

لتثبيت الملحق على الإصدار الذي تصفه هذه الوثائق:

powershell
Install-Package Doconut.NETFramework.Converter -Version 26.10.0

احتفظ بحزمة Converter بنفس الإصدار كما هو في Doconut.NETFramework.

ملف ترخيص الملحق، Doconut.Viewer.Converter.lic، يوضع في نفس المجلد مع Doconut.Viewer.lic؛ يتم قراءته مع ترخيص المشاهد.

تسجيل الملحق

كل ملحق يُسجَّل بنفس الطريقة: AddPlugin<TPlugin>() في DoconutHost.Initialize، يُستدعى من Application_Start.

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

هذا كل ما تحتاجه الواجهة C#. الواجهة (widget) ونقاط النهاية HTTP الخاصة بها هي اختيارية منفصلة، AddConverterWidget() (انظر واجهة منسدلة).

يحتاج الملحق إلى ترخيص يمنح القدرة على Converter. بدون ذلك، يطلق DoconutHost.Initialize استثناءً من Application_Start:

text
The Converter plugin is registered via AddPlugin but no active license grants Converter. Remove the AddPlugin<...>() call or install a license (or trial/demo) that includes Converter.

في System.Web يعني ذلك أن كل طلب يرد بـ 500 فارغ، والسبب موجود فقط في سجل أحداث Windows (المصدر ASP.NET). يطلق الاستثناء عندما لا يوجد ترخيص، أو ملف TRIAL قديم، أو ترخيص بدون Converter، أو ترخيص مدفوع يُستخدم خارج نافذة إصداره. تُقبل تراخيص Demo/NFR المؤقتة. انظر إعداد الترخيص.

الترخيص والعلامة المائية

حالة الترخيصبدء التشغيلنتيجة التحويل
ترخيص عارض مدفوع يمنح Converter، ضمن نافذة إصدارهيبدأنظيف — watermarked: false
ترخيص مؤقت نشط (Demo/NFR)يبدأيحول، مع العلامة المائية للتقييم — watermarked: true
ترخيص مؤقت منتهي (Demo/NFR)يبدأيحول، مع العلامة المائية للتقييم — watermarked: true
بدون ترخيص، ملف TRIAL قديم، ترخيص بدون Converter، أو ترخيص مدفوع خارج نافذة إصدارهيُطلق Application_Start؛ كل طلب يرد بـ 500 فارغ—

تطبق الواجهة DocumentConverter ومعالج ?convert=run للواجهة القاعدة نفسها. يمكن بناء واختبار تكامل من البداية إلى النهاية باستخدام ترخيص تجريبي قبل الشراء — فقط بايتات النتيجة تتغيّر.

مصدر DICOM (.dcm, .ima) يحتاج أيضًا إلى القدرة على Dicom. بدونها، يطلق ConvertAsync استثناءً من نوع LicenseException (Converting '.dcm' requires the Dicom capability license.) وتجيب open الخاصة بالواجهة بـ 403.

الاستخدام من C#

كل تحويل يُعيد MemoryStream قابل للبحث موضعه 0. DocumentConverter لا يحمل حالة: احصل عليه من DoconutHost.Services أينما احتجت واستخدمه بحرية.

csharp
// استدعِ DocumentConverter من DoconutHost.Services؛ مُنشئه داخلي، لذا لا تقم أبداً `new` له.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension يتضمن النقطة الأولية. password هو null ما لم يكن المستند محمياً.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: Stream يحمل الـ HTML لإعادته إلى مستند Word، مثل نتيجة WordToHtmlAsync.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

تفصيلان سهلان الخطأ فيهما: يجب أن يحتوي sourceExtension على التحميل الزائد للمجرى على النقطة الأولية (".xlsx"، وليس "xlsx")، وإلا لن يتم حلّه. وعلى الرغم من اسمه، يُعيد WordToHtmlAsync Task<Stream>، وليس Task<string> — يصل مستند HTML (الصور مدمجة كـ Base64) كمجرى، مثل كل نتيجة أخرى.

المستدعي يمتلك MemoryStream التي يُعيدها التحويل ويجب أن يُفرغها بعد النسخ أو الإرجاع (MVC's File(stream, …) يفرغها لك). لا تقم بإنشاء أو إفراغ DocumentConverter بنفسك — مُنشئه داخلي.

في وحدة تحكم MVC 5

اجعل الإجراء غير متزامن وawait التحويل:

csharp
[HttpPost]
public async Task<ActionResult> ToPdf(HttpPostedFileBase file)
{
    var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();
    Stream pdf = await converter.ConvertAsync(
        file.InputStream, Path.GetExtension(file.FileName), ConversionTarget.Pdf,
        password: null, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", Path.GetFileNameWithoutExtension(file.FileName) + ".pdf");
}

في Web Forms: لا تحظر أبدًا أثناء التحويل

تعمل صفحة Web Forms في سياق طلب أحادي الخيط. ConvertAsync تستأنف على ذلك السياق عندما تكتمل، لذا فإن الصفحة التي تنتظرها بشكل متزامن — .Result، .Wait()، .GetAwaiter().GetResult() — تحتجز الخيط نفسه الذي يحتاجه التحويل للانتهاء. الطلب لا يعود أبدًا. المتصفح يظل يدور، سجلات IIS لا تسجل شيئًا، وبقية الموقع تستمر في العمل، لذا يبدو الأمر كتحويل بطيء بدلاً من حالة توقف.

ضع علامة على الصفحة Async="true" وشغّل التحويل كمهمة غير متزامنة للصفحة:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// Web Forms: توجيه @Page يحتاج Async=\"true\"، وتعمل عملية التحويل كمهمة صفحة غير متزامنة.
// الحجز عليه بدلاً من ذلك (.Result, .Wait(), .GetAwaiter().GetResult()) يسبب تجمد الطلب:
// لن يعود أبداً، ولا يتم تسجيل أي شيء.
protected void Page_Load(object sender, EventArgs e)
{
    if (!IsPostBack) return;

    RegisterAsyncTask(new PageAsyncTask(async ct =>
    {
        var converter = Doconut.DoconutHost.Services.GetRequiredService<DocumentConverter>();

        using (var pdf = await converter.ConvertAsync(
                   Server.MapPath("~/App_Data/contract.docx"), ConversionTarget.Pdf, ct: ct))
        using (var ms = new MemoryStream())
        {
            if (pdf.CanSeek) pdf.Position = 0;
            await pdf.CopyToAsync(ms);

            Response.ContentType = "application/pdf";
            Response.AddHeader("Content-Disposition", "attachment; filename=contract.pdf");
            Response.BinaryWrite(ms.ToArray());
            // Context، وليس HttpContext.Current: بعد await قد يكون الأخير فارغاً (null).
            Context.ApplicationInstance.CompleteRequest();
        }
    }));
}

بدون Async="true" في توجيه @Page، يتم تجاهل RegisterAsyncTask بصمت. بعد await، استخدم Context الخاص بالصفحة؛ يمكن أن يكون HttpContext.Current null هناك.

تنسيقات الهدف

ConversionTarget (المساحة الاسمية Doconut.Configs.Conversion) تحتوي على 45 عضوًا:

text
Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp, Msg, Eml, Emlx, Mhtml,
Xlsm, Xlsb, Ppt, Docm, Dot, Dotx, Dotm, Vsdx, Vssx, Vstx, Vsdm, Vssm, Vstm,
Vdx, Vsx, Vtx, Ico

ليس كل مصدر يتحول إلى كل هدف: كل عائلة تنسيق مصدر (Word، Excel، PowerPoint، PDF، CAD، Image، Email، Diagram، Project، PSD، مستند ويب، DICOM) لها مجموعة خاصة من الأهداف المسموح بها. تحويل مصدر DICOM (.dcm، .ima) يتطلب أيضًا ترخيصًا يمنح القدرة على Dicom؛ أهدافه هي Pdf، Png، Jpeg، Bmp، Tiff وGif. لا تقم بترميز هذا التعداد صلبًا كقائمة أهداف لواجهة المستخدم الخاصة بك: ?convert=open تُعيد allowedTargets للملف المرفوع، وهذا ما يجب أن يحدد أداة الاختيار.

الأداة القابلة للإدماج

تمكين نقاط النهاية

نقاط النهاية ?convert=open|run|download الخاصة بالأداة تُقدم بواسطة DocImage.axd وهي معطلة افتراضيًا. فعّلها بجوار تسجيل الإضافة:

csharp
Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddConverterWidget(widget =>
    {
        widget.MaxUploadMb = 25;
    });
});
// System.Web يقرأ كامل الرفع قبل أن يراه Doconut: احتفظ بـ maxRequestLength (KB) و
// maxAllowedContentLength (bytes) في Web.config أعلى من MaxUploadMb للودجت.

AddConverterWidget() بدون أي معطى يُمكّن الأداة بالإعدادات الافتراضية (MaxUploadMb = 25). لا يمنح حقوق التحويل بحد ذاته: يحتاج إلى AddPlugin<ConverterPlugin>()، أو سيُحدث DoconutHost.Initialize استثناءً:

text
AddConverterWidget() was called but the Converter plugin is not registered. Add options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() (the widget needs it), or remove the AddConverterWidget() call.

شيئان يجب التحقق منهما عندما تتصرف الأداة بشكل غير صحيح:

  • basePath: '/DocImage.axd'. الإعداد الافتراضي للأداة، /doconut، هو نقطة النهاية ASP.NET Core. في هذه الحزمة، نقاط النهاية هي معالج DocImage.axd من Web.config.
  • السكريبت ونقاط النهاية مستقلان. وحدة الموارد تُقدم doconutConverter.js سواء كانت الأداة مفعلة أم لا. بدون AddConverterWidget()، تُحمَّل الأداة، تُرسم منطقة الإسقاط الخاصة بها، وتظهر صحيحة تمامًا — وإجراءها الأول يجيب على 404.

حدود التحميل

ASP.NET يقرأ كامل جسم الطلب قبل أن يعمل DocImage.axd. تحميل يزيد عن MaxUploadMb لكنه أقل من حدود المضيف يحصل على JSON الخاص بالودجت 413 (File is too large.). تحميل يزيد عن حدود المضيف يرفضه IIS أولاً، مع صفحة خطأ لا يستطيع الودجت قراءتها. احتفظ بكل من حدود المضيف في Web.config أعلى حد الودجت:

xml
<system.web>
  <httpRuntime maxRequestLength="30720" />           <!-- KILOBYTES: 30 MB -->
</system.web>
<system.webServer>
  <security>
    <requestFiltering>
      <requestLimits maxAllowedContentLength="31457280" />  <!-- BYTES: 30 MB -->
    </requestFiltering>
  </security>
</system.webServer>

تضمينه

html
<div id="doconut-convert"></div>
<script src="/doconut-res/js/doconutConverter.js"></script>
<script>
  Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd', maxUploadMb: 25 });
</script>

Doconut.convert(selectorOrElement, options) يأخذ محدد CSS أو عنصرًا، يرمي استثناءً إذا لم يُعثر على التركيب، ويعيد مقبضًا. الودجت يرفع ملفًا، يعرض معاينة للصفحة 1، يسمح للمستخدم باختيار أحد allowedTargets، يحول، يعرض معاينة للنتيجة عندما يستطيع، ويقدم التحميل.

الخيارات

الخيارالنوعالافتراضيملاحظات
basePathstring/doconutعنوان URL لنقطة النهاية. اضبط '/DocImage.axd' على هذه الحزمة
resPathstring/doconut-resمقبول للاتساق مع ودجات Doconut الأخرى؛ ودجت المحول لا يبني أي URL منه
maxUploadMbnumber25تحقق مسبق من جانب العميل فقط؛ الخادم يفرض حدّه الخاص
licenseUrlstring | nullnullيحول إشعار العلامة المائية على شاشة النتيجة إلى رابط
labelsobject{}يتجاوز أي مجموعة فرعية من سلاسل الودجت الإنجليزية

ردود النداء

رد النداءيُطلق عندماالحمولة
onReady()الودجت قد عرض شاشة الإسقاط الخاصة به—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })نجاح ?convert=openرمز المصدر، عدد الصفحات، امتداد المصدر (بدون نقطة أولية)، الأهداف المسموح بها
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })نجاح ?convert=runاستجابة التشغيل بالإضافة إلى target المطلوب
onDownload({ downloadName, downloadToken })النقر على تحميل من قبل المستخدميُطلق جنبًا إلى جنب مع تحميل المتصفح نفسه
onError({ phase, message })فشل طلب فتح أو تشغيلphase هو 'open' أو 'run'؛ message هو خطأ الخادم المنقح

يتم التقاط أي رد نداء يرمي استثناءً وتسجيله؛ لا يكسر تدفق الودجت أبدًا.

مقبض إجرائي

Doconut.convert() يعيد نسخة الودجت:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // ملف من جهازك الخاص <input type="file" id="picker">
conv.reset();         // العودة إلى شاشة الإسقاط؛ لا يعيد تشغيل onReady
conv.loadFile(file);  // يبدأ التدفق بملف File; no-op ما لم يكن الودجت في شاشة الإسقاط
conv.destroy();       // يزيل المستمعين، يفرغ الـ mount؛ الكائن غير قابل للاستخدام بعد ذلك

التسميات

كل سلسلة لها افتراضية إنجليزية؛ labels يتجاوز أي مجموعة فرعية والبقية تبقى إنجليزية. القطع التي تتغير أثناء التشغيل تستخدم {placeholders}، مثل uploading: 'Uploading {name}…' و pages: '{n} pages'.

المفتاحالافتراضي الإنجليزي
dropPromptDrag & drop a document here
dropHintPDF, Word, Excel, PowerPoint, images and more
chooseFileChoose file
uploadingUploading {name}…
page / pages1 page / {n} pages
noTargetsNo conversion targets are available for this file.
convertTo / convertConvert to / Convert
convertingConverting to {target}…
readyToDownloadReady to download
download / convertAnotherDownload / Convert another
watermarkNoticeOutput is watermarked — get a license to remove it.
retryRetry
genericErrorSomething went wrong. Please try again.
sizeLimitThat file is larger than the {mb} MB upload limit. Please choose a smaller file.
serverErrorThe server could not process this request. Please try again.
networkErrorCould not reach the server. Please check your connection and try again.

المفاتيح الإضافية تغطي aria-label لمنطقة الإسقاط (dropAriaLabel)، نصوص معاينة alt (previewAlt، resultAlt)، الشكل المرتبط لإشعار العلامة المائية المستخدم مع licenseUrl (watermarkNoticePrefix، watermarkNoticeLink، watermarkNoticeSuffix)، استجابة غير قابلة للقراءة (badResponse) وإعلانات aria-live (annReady، annUploading، annLoaded، annLoadedNoTargets، annConverting، annDone، annError).

يُعرض خطأ JSON من الخادم كما كتبه الخادم؛ يُستخدم serverError فقط عندما لا يحمل استجابة فاشلة خطأ JSON، مثل 404 لودجت معطل.

التنميط

تضيف الأداة الفئة dcw إلى عنصر التركيب الخاص بها وتقرأ ألوانها ونصف القطر والخط من خصائص CSS المخصصة، بحيث يمكنك تنسيقها دون تعديل مكوناتها الداخلية:

css
#doconut-convert.dcw {
  --dcw-accent: #6b46c1;
  --dcw-radius: 12px;
  --dcw-font: "Inter", system-ui, sans-serif;
}

القيم الافتراضية: --dcw-accent: #2b6cb0، --dcw-bg: #ffffff، --dcw-fg: #1a202c، --dcw-muted: #718096، --dcw-border: #cbd5e0، --dcw-radius: 8px، وخط واجهة المستخدم النظامي لـ --dcw-font.

بناء الواجهة الأمامية الخاصة بك

الأداة هي عميل لهذا العقد HTTP على DocImage.axd. تُجيب المسارات بـ 404 حتى يتم استدعاء AddConverterWidget(). تحمل الأخطاء جسم JSON، { "error": "..." }، ما عدا عندما تقول الجدول “فقط الحالة”. قيمة غير معروفة لـ ?convert= تُجيب بـ 400.

المسارالغرضاستجابة النجاح
POST /DocImage.axd?convert=open (متعدد الأجزاء، ملف واحد)رفع وفتح مستند مصدر200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>تحويل المصدر المرفوع إلى target200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>بث الملف المحول200 — الملف، Content-Disposition: attachment، Cache-Control: no-store

sourceExt في استجابة open ليس له نقطة بادئة ("docx") — وهو عكس معامل sourceExtension في ConvertAsync. allowedTargets يسرد أسماء الأهداف بأحرف صغيرة ("pdf"، "html"، …)؛ مرّر أحدها كـ target، الذي يُطابق دون حساسية لحالة الأحرف. open يستخدم الملف الأول في جسم متعدد الأجزاء.

resultToken هو null، وresultPages هو 0، عندما لا يمكن معاينة النتيجة. downloadName هو اسم ملف المصدر مع امتداد الهدف.

تستخدم صور المعاينة مسار صورة العارض القياسي، /DocImage.axd?token={token}&page=1&thumb=1&width={px}، مع الـ token من open أو الـ resultToken من run. تطلب الأداة width=240.

يُحتفظ بالمصادر المرفوعة لمدة 30 دقيقة بعد آخر قراءة لها؛ بعد ذلك، يجيب run بـ 404 ويجب فتح الملف مرة أخرى. يحصل downloadToken على نافذة 30 دقيقة خاصة به عند اكتمال التحويل. resultToken هو رمز عارض عادي لمعاينة النتيجة؛ عندما يمكن معاينة النتيجة، تكون قيمته نفسها كـ downloadToken.

المسارالحالةمتىالمحتوى
أي404الأداة غير مفعلة (لم يتم استدعاء AddConverterWidget() أبداً)فقط الحالة
أي405الفعل غير صحيح (open/run يتطلبان POST، download يتطلب GET)فقط الحالة
open400ليس تحميلًا متعدد الأجزاءExpected a multipart file upload.
open400لا ملف، أو ملف فارغNo file uploaded.
open400نوع لا يمكن تحويلهThis file type cannot be converted.
open403نوع الملف يحتاج إلى قدرة لا تمنحها الرخصة (ملف DICOM بدون Dicom)Converting this file type requires the Dicom capability license.
open413التحميل يتجاوز MaxUploadMb (ولكن ليس حدود IIS)File is too large.
run400رمز غير صالح (ليس GUID)Invalid token.
run400target لا يمكن تحليله إلى ConversionTargetUnknown target format.
run400هدف غير موجود في allowedTargetsThat target format is not available for this file.
run404انتهت صلاحية التحميل أو لم يتم فتحه أبداًUpload expired — please re-open the file.
open, run500فشل المعالجةرسالة مُنقاة
download400 / 404رمز تحميل غير صالح أو غير معروف أو منتهي الصلاحيةفقط الحالة

جولة كاملة مع fetch:

javascript
// الملف: الـFile المراد تحويله، على سبيل المثال من <input type="file">.
async function convertFile(file) {
  const base = '/DocImage.axd';

  // 1. open: رفع الملف
  const form = new FormData();
  form.append('file', file, file.name);
  const openResp = await fetch(base + '?convert=open', { method: 'POST', body: form });
  if (!openResp.ok) throw new Error((await openResp.json()).error);
  const opened = await openResp.json();

  // 2. run: تحويل إلى PDF عندما يكون مسموحًا، وإلا إلى أول هدف مسموح
  const target = opened.allowedTargets.includes('pdf') ? 'pdf' : opened.allowedTargets[0];
  const runResp = await fetch(base + '?token=' + encodeURIComponent(opened.token) +
    '&convert=run&target=' + target, { method: 'POST' });
  if (!runResp.ok) throw new Error((await runResp.json()).error);
  const converted = await runResp.json();

  // 3. download: طلب GET بسيط يمكن للمتصفح متابعته
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

النقاط النهائية هي نفس الأصل: هذا الإصدار لا يدعم CORS. قدّم واجهة المستخدم وسكربت الأداة من نفس الأصل الذي تستضيفه Doconut، أو استخدم reverse-proxy للمعالج ومسارات الموارد تحت أصل واجهة المستخدم الخاصة بك.

في الإنتاج

  1. تثبيت المكوّن الإضافي بجوار حزمة النواة، بنفس الإصدار: Install-Package Doconut.NETFramework.Converter.
  2. إضافة ملف الترخيص. ضع Doconut.Viewer.Converter.lic في نفس المجلد مع Doconut.Viewer.lic.
  3. تحديد حدود التحميل. MaxUploadMb في AddConverterWidget هو الحد الذي يفرضه Doconut؛ حافظ على maxRequestLength و maxAllowedContentLength في Web.config أعلى منه (انظر حدود التحميل)، واجعل maxUploadMb الخاص بالأداة مساويًا له.
  4. لا تقم أبدًا بحجب التحويل في نماذج الويب (انظر في نماذج الويب).
  5. تخلص من نتائج التحويل. الدفق الذي تُعيده ConvertAsync مُجَمَّع؛ التخلص منه يعيد المخازن المؤقتة إلى التجمع.

مزارع الويب

تحافظ الأداة على كل تحميل ونتيجته في الذاكرة على الخادم الذي خدم open. خلف موازن التحميل دون جلسات ثابتة، قد يصل طلب لاحق run أو download أو طلب معاينة إلى خادم آخر ولا يجد التحميل. سجِّل مخزن الأداة المشترك المشفر عبر الوسيط الثاني لـ DoconutHost.Initialize:

csharp
byte[] farmKey = Convert.FromBase64String(System.Configuration.ConfigurationManager.AppSettings["Doconut:FarmKey"]);

Doconut.DoconutHost.Initialize(
    options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
        options.AddConverterWidget();
    },
    services => services.AddDoconutDistributedWidgets(store =>
    {
        store.RootPath = @"\\fileshare\doconut";   // مجلد يمكن لكل خادم قراءته وكتابته
        store.FarmKey = farmKey;                   // على الأقل 32 بايت، متطابقة على كل خادم
        // store.Ttl = TimeSpan.FromMinutes(30);   // مدة بقاء التحميل (الإعداد الافتراضي)
    }));
  • لا يحتاج الخادم الفردي إلى شيء: بدون هذا الاستدعاء يُستخدم المخزن في الذاكرة.
  • يتم تشفير التحميلات والنتائج أثناء الراحة على المشاركة (AES-256، تشفير ثم MAC)، ويرتبط كل ملف برمز مميز خاص به، لذا لا يمكن لرمز مميز واحد قراءة ملف آخر.
  • على المشاركة، يُحتفظ بتحميل أو نتيجة لمدة Ttl بعد كتابتها؛ القراءة لا تمدد تلك الفترة.
  • يجب أن يكون FarmKey على الأقل 32 بايت ومتماثلًا على كل خادم. حمّله من مخزن سري؛ لا تقم أبدًا بكتابة ثابتة. التسجيل يُلقي ArgumentException عندما يكون RootPath مفقودًا أو يكون FarmKey أقصر من 32 بايت.
  • وجه RootPath إلى نفس الموقع المشترك الذي يستخدمه العارض الموزع.

مرجع API

الواجهة وخيارات الأداة موجودة في مساحة الاسم Doconut؛ ConversionTarget موجود في Doconut.Configs.Conversion. ConverterPlugin موجود في Doconut.Plugins.Converter.

DocumentConverter

csharp
public sealed class DocumentConverter
{
    public Task<Stream> ConvertAsync(
        string filePath, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> ConvertAsync(
        Stream source, string sourceExtension, ConversionTarget target,
        string? password = null, CancellationToken ct = default);

    public Task<Stream> WordToHtmlAsync(string filePath, CancellationToken ct = default);

    public Task<Stream> HtmlToWordAsync(
        Stream htmlSource, ConversionTarget outputFormat = ConversionTarget.Docx,
        CancellationToken ct = default);
}

يتم حلّها من DoconutHost.Services؛ المُنشئ داخلي. sourceExtension يتضمن النقطة الأولية. HtmlToWordAsync يكتب ملف .doc عندما يكون outputFormat هو ConversionTarget.Doc، وملف .docx لأي قيمة أخرى.

ConversionTarget

تنسيقات الإخراج الـ45 المذكورة في تنسيقات الهدف.

ConverterWidgetOptions

csharp
public sealed class ConverterWidgetOptions
{
    public int MaxUploadMb { get; set; } = 25;
}

يتم الضبط عبر DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null)، الذي يُعيد الـ DoconutOptions حتى يمكن ربط الاستدعاءات.

استكشاف الأخطاء وإصلاحها

العَرَضالسببالإصلاح
كل طلب يُعيد 500 فارغ بعد إضافة الملحق؛ سجل أحداث Windows (المصدر ASP.NET) يُظهر The Converter plugin is registered via AddPlugin but no active license grants Converter.لا توجد رخصة، ملف TRIAL، رخصة بدون Converter، أو رخصة مدفوعة خارج نافذة الإصدار الخاصة بهاثبت رخصة تُعطي Converter، أو أزل AddPlugin<ConverterPlugin>()
كل طلب يُعيد 500 فارغ؛ سجل الأحداث يُظهر AddConverterWidget() was called but the Converter plugin is not registered.الودجت مُفعَّل بدون الملحق الخاص بهأضف options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>()
حل DocumentConverter يثير No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().ConverterPlugin غير مسجلأضف AddPlugin<ConverterPlugin>() في DoconutHost.Initialize
تحويل Web Forms لا يُعيد أبدًاالصفحة تُعطِّل على ConvertAsyncاستخدم Async="true" و RegisterAsyncTask
تحويل الدفق يُشير إلى أن الصيغة غير مدعومةsourceExtension لا يحتوي على نقطة في البدايةمرّر ".xlsx"، وليس "xlsx"
ConvertAsync يثير Converting '.dcm' requires the Dicom capability license.مصدر DICOM، والرخصة لا تُعطي Dicomاستخدم رخصة تُعطي Dicom
المخرجات مائية العلامةالرخصة مؤقتة (Demo/NFR)استخدم رخصة مدفوعة تُعطي Converter
الودجت يُحمَّل لكن طلباته تُعيد 404AddConverterWidget() لم يُستدعَ، أو basePath ليس '/DocImage.axd'استدعِ AddConverterWidget()؛ اضبط basePath: '/DocImage.axd'
رفع كبير يُظهر صفحة خطأ IIS بدلاً من رسالة الودجتmaxRequestLength / maxAllowedContentLength أقل من MaxUploadMbارفع حدود Web.config فوق MaxUploadMb
open يجيب 403 Converting this file type requires the Dicom capability license.رفع DICOM، والرخصة لا تُعطي Dicomاستخدم رخصة تُعطي Dicom
run يجيب 400 That target format is not available for this file.الهدف ليس أحد allowedTargets الخاص بالمصدراعرض فقط allowedTargets من convert=open
run أو download يجيب 404 (Upload expired — please re-open the file. من run)انقضت نافذة الـ30 دقيقة، أو خادم آخر في المزرعة لا يملك الرفعافتح الملف مرة أخرى؛ في المزرعة، سجِّل AddDoconutDistributedWidgets
الودجت يفشل عندما تكون واجهة المستخدم على أصل آخرنقاط النهاية لا تدعم CORSقدِّم واجهة المستخدم من نفس الأصل، أو استخدم reverse-proxy لمسارات Doconut
السمة لا تُطبقالمتغيّرات مضبوطة على سلف أو على عنصر داخل الـmount؛ قاعدة .dcw الخاصة بالودجت تضبطها على الـmountاستهدف الـmount نفسه: #doconut-convert.dcw أو #doconut-convert

ملاحظات الإطار

مقارنةً بحزم ASP.NET Core، تختلف هذه الحزمة فقط في الاستضافة؛ أما الـAPI، وعقد نقطة النهاية، وسكريبت الودجت، وقواعد الترخيص فهي نفسها.

  • التسجيل في Application_Start، عبر DoconutHost.Initialize، بدلاً من builder.Services.AddDoconut. الخدمات مثل AddDoconutDistributedWidgets تُوضع في معاملها الثاني.
  • نقاط النهاية تُخدم بواسطة DocImage.axd والسكريبت بواسطة DoconutResourceModule، كلاهما مسجل في Web.config، بدلاً من UseDoconut() وUseDoconutResources(). الودجت يحتاج إلى basePath: '/DocImage.axd'.
  • فشل بدء التشغيل يظهر كـ 500 فارغ في كل طلب، مع السبب في سجل أحداث Windows.
  • الرفع يُقرأ بالكامل بواسطة ASP.NET قبل أن يراه Doconut، لذا يجب أن تكون حدود IIS فوق MaxUploadMb.
  • صفحات Web Forms يجب ألا تُعطِّل عند التحويل؛ راجع في نماذج الويب.
  • Windows فقط، مثل بقية حزمة .NET Framework.

هل كانت هذه الصفحة مفيدة؟