Dönüştürücü Eklentisi

Belgeleri 45 hedef formata dönüştürün

Converter eklentisi Doconut'u bir belge-dönüştürme hizmetine dönüştürür. DocumentConverter genel arabasının arkasındaki motoru ve — isteğe bağlı — DocImage.axd tarafından sunulan bir drop-in widget'ı sağlar, böylece belgeleri C#'tan, widget'tan veya kendinizin yazdığı bir ön uçtan dönüştürebilirsiniz.

YüzeyNe zaman kullanılır
DocumentConverter (C#)Sunucuda, tarayıcı olmadan dönüştürürsünüz
Yerleştirilebilir widget (doconutConverter.js)Sayfanızda hazır bir yükleme, dönüştürme ve indirme ekranı istiyorsunuz
HTTP endpoints on DocImage.axd (?convert=open|run|download)Belgelendirilmiş bir sunucu sözleşmesine karşı kendi dönüşüm UI'nizi oluşturursunuz

Paketi kurun

powershell
Install-Package Doconut.NETFramework.Converter

Bu belgelerin açıkladığı sürüme eklentiyi sabitlemek için:

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

Doconut.NETFramework ile aynı sürümde Converter paketini tutun.

Eklentinin lisans dosyası Doconut.Viewer.Converter.lic, Doconut.Viewer.lic ile aynı klasöre konur; izleyici lisansı ile birlikte okunur.

Eklentiyi kaydedin

Her eklenti aynı şekilde kaydedilir: AddPlugin<TPlugin>(), DoconutHost.Initialize içinde, Application_Start'dan çağrılır.

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

Bu, C# arabiriminin ihtiyaç duyduğu her şeydir. Widget ve onun HTTP uç noktaları ayrı bir isteğe bağlı, AddConverterWidget() (bkz. Yerleştirilebilir widget).

Eklenti, Converter yeteneğini veren bir lisansa ihtiyaç duyar. Bir lisans olmadan, DoconutHost.Initialize, Application_Start'den bir istisna fırlatır:

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 içinde bu, her isteğin boş bir 500 ile yanıt verdiği anlamına gelir ve neden sadece Windows olay günlüğünde (kaynak ASP.NET) bulunur. Lisans yoksa, eski bir TRIAL dosyası, Converter içermeyen bir lisans ve sürüm penceresi dışındaki ücretli bir lisans için istisna fırlatır. Geçici Demo/NFR lisansları kabul edilir. Bkz. Lisans Kurulumu.

Lisanslama & filigran

Lisans durumuBaşlangıçDönüştürme çıktısı
Sürüm penceresi içinde Converter sağlayan ücretli görüntüleyici lisansıBaşlarTemiz — watermarked: false
Aktif Geçici (Demo/NFR) lisansBaşlarDönüştürür, değerlendirme filigranı ile — watermarked: true
Süresi dolmuş Geçici (Demo/NFR) lisansBaşlarDönüştürür, değerlendirme filigranı ile — watermarked: true
Lisans yok, eski bir TRIAL dosyası, Converter içermeyen bir lisans veya sürüm penceresi dışındaki ücretli bir lisansApplication_Start fırlatır; her istek boş bir 500 ile yanıt verir—

DocumentConverter arabirimi ve widget'ın ?convert=run işleyicisi aynı kuralı uygular. Bir entegrasyon, satın almadan önce değerlendirme lisansı üzerinde uçtan uca inşa edilebilir ve test edilebilir — sadece çıktı baytları değişir.

Bir DICOM kaynağı (.dcm, .ima) ayrıca Dicom yeteneğine ihtiyaç duyar. Olmadan, ConvertAsync bir LicenseException (Converting '.dcm' requires the Dicom capability license.) fırlatır ve widget'ın open'i 403 yanıt verir.

C#'dan Kullanım

Her dönüşüm, 0 konumunda konumlandırılmış bir seekable MemoryStream döndürür. DocumentConverter durum bilgisizdir: ihtiyacınız olduğu yerde DoconutHost.Services'den çözün ve serbestçe yeniden kullanın.

csharp
// DoconutHost.Services'tan DocumentConverter'ı çözün; yapıcı içsel olduğu için, asla `new` etmeyin.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);
csharp
// sourceExtension baştaki noktayı içerir. password, belge korunmuyorsa null olur.
Stream png = await converter.ConvertAsync(stream, ".xlsx", ConversionTarget.Png, password: null, ct: ct);
csharp
Stream html = await converter.WordToHtmlAsync("report.docx", ct);
csharp
// html: Word belgesine geri dönüştürülecek HTML'i tutan bir Stream, örneğin WordToHtmlAsync sonucunda elde edilen.
Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Yanlış yapılması kolay iki detay: akış aşırı yüklemesinde sourceExtension, baştaki nokta (".xlsx", "xlsx" değil) içermelidir, aksi takdirde çözülmez. Ve adı ne olursa olsun, WordToHtmlAsync Task<Stream> döndürür, Task<string> değil — HTML belge (Base64 olarak gömülü görüntüler) bir akış olarak gelir, diğer tüm sonuçlar gibi.

Çağıran, bir dönüşümün döndürdüğü MemoryStream'in sahibidir ve kopyaladıktan ya da döndürdükten sonra onu dispose etmelidir (MVC'nin File(stream, …) sizin için dispose eder). DocumentConverter'i kendiniz oluşturmayın veya dispose etmeyin — yapıcı içtedir.

MVC 5 denetleyicisinde

Eylemi asenkron yapın ve dönüşümü 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'ta: dönüşümde asla engelleme

Bir Web Forms sayfası tek iş parçacıklı bir istek bağlamında çalışır. ConvertAsync tamamlandığında o bağlamda devam eder, bu yüzden senkron olarak bekleyen bir sayfa — .Result, .Wait(), .GetAwaiter().GetResult() — dönüşümün bitmesi için gereken iş parçacığını tutar. İstek asla geri dönmez. Tarayıcı dönmeye devam eder, IIS hiçbir şey kaydetmez ve sitenin geri kalanı çalışmaya devam eder, bu yüzden bir kilitlenme yerine yavaş bir dönüşüm gibi görünür.

Sayfayı Async="true" işaretleyin ve dönüşümü bir sayfa async görevi olarak çalıştırın:

aspx
<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>
csharp
// Web Forms: @Page yönergesi Async="true" gerekir, ve dönüşüm bir sayfa async görevi olarak çalışır.
// Bunun üzerinde bloklama yapmak (.Result, .Wait(), .GetAwaiter().GetResult()) isteği deadlock eder:
// hiçbir zaman dönmez ve hiçbir şey kaydedilmez.
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 değil: bir await'tan sonra ikincisi null olabilir.
            Context.ApplicationInstance.CompleteRequest();
        }
    }));
}

Async="true" olmadan @Page yönergesinde, RegisterAsyncTask sessizce yok sayılır. Bir await sonrası, sayfanın Context kullanın; HttpContext.Current orada null olabilir.

Hedef formatlar

ConversionTarget (namespace Doconut.Configs.Conversion) 45 üyeye sahiptir:

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

Her kaynak her hedefe dönüştürülmez: her kaynağın format ailesi (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, web document, DICOM) kendi izin verilen hedef setine sahiptir. Bir DICOM kaynağını (.dcm, .ima) dönüştürmek ayrıca Dicom yeteneğini veren bir lisans gerektirir; hedefleri Pdf, Png, Jpeg, Bmp, Tiff ve Gif'dır. Bu enum'ı UI'nizin hedef listesi olarak sabit kodlamayın: ?convert=open, yüklenen dosya için allowedTargets döndürür ve bu, bir seçim kutusunu yönlendirmelidir.

Yerleştirilebilir widget

Uç noktaları etkinleştirin

Widget'ın ?convert=open|run|download uç noktaları DocImage.axd tarafından sunulur ve varsayılan olarak kapalıdır. Eklenti kaydının yanına bunları etkinleştirin:

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 bunu görmeden önce tüm yüklemeyi okur: maxRequestLength (KB) ve
// maxAllowedContentLength (bytes) değerini Web.config içinde widget's MaxUploadMb'nin üzerine koyun.

AddConverterWidget() argümansız olarak widget'ı varsayılanlarla etkinleştirir (MaxUploadMb = 25). Tek başına dönüşüm hakları vermez: AddPlugin<ConverterPlugin>() gerekir, aksi takdirde DoconutHost.Initialize hata verir:

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.

Widget hatalı davrandığında kontrol edilmesi gereken iki şey:

  • basePath: '/DocImage.axd'. Widget'ın varsayılanı, /doconut, ASP.NET Core uç noktasıdır. Bu pakette, uç noktalar Web.config'den gelen DocImage.axd işleyicisidir.
  • Betik ve uç noktalar bağımsızdır. Kaynak modülü, widget etkin olsun ya da olmasın doconutConverter.js sunar. AddConverterWidget() olmadan, widget yüklenir, bırakma bölgesini çizer ve tamamen doğru görünür — ve ilk eylemi 404 yanıtını verir.

Yükleme limitleri

ASP.NET, DocImage.axd çalışmadan önce tüm istek gövdesini okur. MaxUploadMb üzerindeki ancak sunucu limitlerinin altında kalan bir yükleme, widget'ın kendi JSON 413'ını (File is too large.) alır. Sunucu limitlerinin üzerindeki bir yükleme önce IIS tarafından reddedilir ve widget'ın okuyamayacağı bir hata sayfası gösterilir. Her iki sunucu limitini de widget'ın sınırının üzerindeki Web.config içinde tutun:

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>

Gömün

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) bir CSS seçicisi ya da bir öğe alır, bağlama bulunamazsa hata fırlatır ve bir tutamaç döndürür. Widget bir dosya yükler, sayfa 1'in önizlemesini gösterir, kullanıcının allowedTargets'den birini seçmesine izin verir, dönüştürür, mümkün olduğunda sonucu önizler ve indirme seçeneği sunar.

Seçenekler

SeçenekTürVarsayılanNotlar
basePathstring/doconutUç nokta URL'si. Bu pakette '/DocImage.axd' ayarlayın
resPathstring/doconut-resDiğer Doconut widget'larıyla tutarlılık sağlamak için kabul edildi; dönüştürücü widget bundan herhangi bir URL oluşturmaz
maxUploadMbnumber25Yalnızca istemci tarafı ön kontrol; sunucu kendi sınırını uygular
licenseUrlstring | nullnullSonuç ekranındaki filigran bildirimini bir bağlantıya dönüştürür
labelsobject{}Widget'ın İngilizce metinlerinin herhangi bir alt kümesini geçersiz kılar

Geri çağrılar

Geri çağrıNe zaman tetiklenirYük
onReady()Widget düşürme ekranını render etti—
onSourceLoaded({ token, pages, sourceExt, allowedTargets })?convert=open başarılı olduğundaKaynak token, sayfa sayısı, kaynak uzantı (başında nokta olmadan), izin verilen hedefler
onConverted({ downloadToken, resultToken, resultPages, downloadName, watermarked, target })?convert=run başarılı olduğundaÇalıştırma yanıtı ve istenen target
onDownload({ downloadName, downloadToken })Kullanıcı İndir'e tıkladığındaTarayıcının kendi indirmesiyle birlikte tetiklenir
onError({ phase, message })Bir açma veya çalıştırma isteği başarısız olduğundaphase, 'open' ya da 'run'; message, temizlenmiş sunucu hatasıdır

Hata fırlatan bir geri çağrı yakalanır ve kaydedilir; widget'ın akışını asla bozmaz.

İmperatif tutamaç

Doconut.convert() widget örneğini döndürür:

javascript
const conv = Doconut.convert('#doconut-convert', { basePath: '/DocImage.axd' });
const file = document.querySelector('#picker').files[0]; // kendi <input type="file" id="picker"> öğenizden bir File
conv.reset();         // bırakma ekranına geri dön; onReady yeniden tetiklenmez
conv.loadFile(file);  // akışı bir File ile başlatır; widget bırakma ekranında değilse hiçbir işlem yapmaz
conv.destroy();       // dinleyicileri kaldırır, mount'ı boşaltır; bu işlemden sonra instance kullanılamaz

Etiketler

Her dize bir İngilizce varsayılan değere sahiptir; labels herhangi bir alt kümeyi geçersiz kılar ve geri kalanlar İngilizce kalır. Çalışma zamanında değişen parçalar {placeholders} kullanır, örneğin uploading: 'Uploading {name}…' ve pages: '{n} pages'.

Anahtarİngilizce varsayılan
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.

Diğer anahtarlar, bırakma bölgesinin aria-label (dropAriaLabel), önizleme alt metinlerini (previewAlt, resultAlt), licenseUrl ile kullanılan filigran bildiriminin bağlantılı biçimini (watermarkNoticePrefix, watermarkNoticeLink, watermarkNoticeSuffix), okunamayan bir yanıtı (badResponse) ve aria-live duyurularını (annReady, annUploading, annLoaded, annLoadedNoTargets, annConverting, annDone, annError) kapsar.

Sunucudan gelen bir JSON hatası, sunucunun yazdığı şekilde gösterilir; serverError yalnızca başarısız bir yanıt JSON hatası içermediğinde, örneğin devre dışı bırakılmış bir widget'ın 404 gibi durumlarda kullanılır.

Tema

Widget, dcw sınıfını bağlama öğesine ekler ve renklerini, yarıçapını ve yazı tipini CSS özel özelliklerinden okur, böylece iç yapısına dokunmadan temalandırabilirsiniz:

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

Varsayılanlar: --dcw-accent: #2b6cb0, --dcw-bg: #ffffff, --dcw-fg: #1a202c, --dcw-muted: #718096, --dcw-border: #cbd5e0, --dcw-radius: 8px ve --dcw-font için bir sistem UI yazı tipi.

Kendi ön ucunuzu oluşturun

Widget, DocImage.axd üzerindeki bu HTTP sözleşmesi için bir istemcidir. Rotalar, AddConverterWidget() çağrılana kadar 404 yanıt verir. Hatalar JSON gövdesi taşır, { "error": "..." }, tablo "status only" dediği yerler hariç. Bilinmeyen bir ?convert= değeri 400 yanıt verir.

RotaAmaçBaşarılı yanıt
POST /DocImage.axd?convert=open (multipart, one file)Bir kaynak belgeyi yükleyin ve açın200 — { token, pages, sourceExt, allowedTargets }
POST /DocImage.axd?token=<token>&convert=run&target=<ext>Yüklenen kaynağı target'ye dönüştürün200 — { downloadToken, resultToken, resultPages, downloadName, watermarked }
GET /DocImage.axd?convert=download&token=<downloadToken>Dönüştürülmüş dosyayı akış olarak gönder200 — dosya, Content-Disposition: attachment, Cache-Control: no-store

sourceExt, open yanıtında başında nokta ("docx") yoktur — ConvertAsync'un sourceExtension parametresinin tersidir. allowedTargets, küçük harf hedef adlarını listeler ("pdf", "html", …); bunlardan birini target olarak geçirin, büyük/küçük harfe duyarsız eşleşir. open, çok parçalı gövdedeki ilk dosyayı kullanır.

resultToken, null'dır ve sonuç ön izlenemediğinde resultPages, 0'dır. downloadName, hedefin uzantısıyla kaynak dosya adıdır.

Ön izleme görüntüleri standart görüntüleyici resim rotasını, /DocImage.axd?token={token}&page=1&thumb=1&width={px}, open'den gelen token veya run'den gelen resultToken ile kullanır. Widget, width=240 ister.

Yüklenen kaynaklar son okunduktan 30 dakika boyunca saklanır; ardından run, 404 yanıt verir ve dosya tekrar açılmalıdır. Dönüşüm tamamlandığında downloadToken kendi 30 dakikalık penceresini alır. resultToken, sonucu ön izlemek için sıradan bir görüntüleyici token'ıdır; sonuç ön izlenebildiğinde, değeri downloadToken ile aynıdır.

RotaDurumNe zamanGövde
herhangi404Widget etkinleştirilmemiş (AddConverterWidget() hiç çağrılmadı)status only
herhangi405Yanlış fiil (open/run, POST gerektirir, download, GET gerektirir)status only
open400Çok parçalı bir yükleme değilExpected a multipart file upload.
open400Dosya yok veya boşNo file uploaded.
open400Dönüştürülemeyen bir türThis file type cannot be converted.
open403Dosya türü, lisansın vermediği bir yetenek gerektirir (Dicom olmadan bir DICOM dosyası)Converting this file type requires the Dicom capability license.
open413Yükleme, MaxUploadMb değerini aşıyor (ancak IIS limitlerini aşmıyor)File is too large.
run400Bozuk bir token (GUID değil)Invalid token.
run400Bir target, bir ConversionTarget'a ayrıştırılamıyorUnknown target format.
run400allowedTargets içinde olmayan bir hedefThat target format is not available for this file.
run404Yükleme süresi doldu veya hiç açılmadıUpload expired — please re-open the file.
open, run500İşleme başarısız olduTemizlenmiş bir mesaj
download400 / 404Bozuk, bilinmeyen veya süresi dolmuş bir indirme token'ıstatus only

fetch ile tam bir tur:

javascript
// file: dönüştürülecek Dosya, örneğin bir <input type="file"> öğesinden.
async function convertFile(file) {
  const base = '/DocImage.axd';

  // 1. open: dosyayı yükle
  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: izin verildiğinde PDF'ye dönüştür, aksi takdirinde ilk izin verilen hedefe
  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: tarayıcının takip edebileceği basit bir GET
  window.location.href = base + '?convert=download&token=' + encodeURIComponent(converted.downloadToken);
}

Uç noktalar same-origin'dır: bu sürüm CORS desteği içermez. UI'nizi ve widget betiğini Doconut ile aynı origin'den sunun, ya da işleyiciyi ve kaynak yollarını UI'nizin origin'i altında ters proxy yapın.

Üretimde

  1. Eklentiyi kurun çekirdek paketinin yanına, aynı sürümde: Install-Package Doconut.NETFramework.Converter.
  2. Lisans dosyasını ekleyin. Doconut.Viewer.Converter.lic'yi Doconut.Viewer.lic ile aynı klasöre yerleştirin.
  3. Yükleme sınırlarını ayarlayın. MaxUploadMb, AddConverterWidget içinde Doconut'un uyguladığı sınırdır; maxRequestLength ve maxAllowedContentLength, Web.config içinde bu sınırın üzerinde tutun (bkz. Yükleme sınırları), ve widget'ın maxUploadMb'ı ona eşit olsun.
  4. Web Forms'ta bir dönüşümde asla bloklamayın (bkz. Web Forms'ta).
  5. Dönüşüm sonuçlarını serbest bırakın. ConvertAsync akışı havuzlanmıştır; serbest bırakmak, tamponlarını havuza geri verir.

Web çiftlikleri

Widget, her yüklemeyi ve sonucunu, open'ı hizmet veren sunucuda bellekte tutar. Yapışkan oturumlar olmadan bir yük dengeleyicinin arkasında, daha sonraki bir run, download veya önizleme isteği başka bir sunucuya ulaşabilir ve yüklemeyi bulamaz. Paylaşılan, şifreli widget deposunu DoconutHost.Initialize'nin ikinci argümanı aracılığıyla kaydedin:

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";   // her sunucunun okuyup yazabileceği bir klasör
        store.FarmKey = farmKey;                   // en az 32 bayt, her sunucuda aynı
        // store.Ttl = TimeSpan.FromMinutes(30);   // bir yüklemenin ne kadar süre saklandığı (varsayılan)
    }));
  • Tek bir sunucu hiçbir şeye ihtiyaç duymaz: bu çağrı olmadan bellek içi mağaza kullanılır.
  • Yüklemeler ve sonuçlar paylaşılda dinlenirken şifrelenir (AES-256, encrypt-then-MAC) ve her dosya token'ına bağlanır, böylece bir token başka birinin dosyasını asla okuyamaz.
  • Paylaşılda, bir yükleme veya sonuç, yazıldıktan sonra Ttl süreyle tutulur; okuma bu süreyi uzatmaz.
  • FarmKey en az 32 bayt olmalı ve her sunucuda aynı olmalıdır. Gizli bir depodan yükleyin; asla sabit kodlamayın. Kayıt, RootPath eksik olduğunda veya FarmKey 32 bayttan kısa olduğunda bir ArgumentException fırlatır.
  • RootPath'i dağıtılmış görüntüleyicinin kullandığı aynı paylaşılan konuma yönlendirin.

API referansı

Facade ve widget seçenekleri Doconut ad alanındadır; ConversionTarget, Doconut.Configs.Conversion içinde bulunur. ConverterPlugin, Doconut.Plugins.Converter içinde bulunur.

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'den çözümlenir; yapıcı dahili. sourceExtension, baştaki noktayı içerir. HtmlToWordAsync, outputFormat ConversionTarget.Doc olduğunda bir .doc dosyası yazar ve diğer tüm değerler için bir .docx dosyası yazar.

ConversionTarget

45 çıktı formatı Hedef formatları içinde listelenmiştir.

ConverterWidgetOptions

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

DoconutOptions.AddConverterWidget(Action<ConverterWidgetOptions>? configure = null) aracılığıyla ayarlanır, bu da DoconutOptions döndürür, böylece çağrılar zincirlenebilir.

Sorun Giderme

SemptomNedenDüzeltme
Eklentiyi ekledikten sonra her istek boş bir 500 yanıtı verir; Windows olay günlüğü (kaynak ASP.NET) The Converter plugin is registered via AddPlugin but no active license grants Converter. gösterirLisans yok, bir TRIAL dosyası, Converter içermeyen bir lisans veya sürüm penceresinin dışında bir ücretli lisansConverter sağlayan bir lisans kurun veya AddPlugin<ConverterPlugin>() kaldırın
Her istek boş bir 500 yanıtı verir; olay günlüğü AddConverterWidget() was called but the Converter plugin is not registered. gösterirWidget, eklentisi olmadan etkinleştirilmişoptions.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>() ekleyin
DocumentConverter çözülürken No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>(). hatası atılırConverterPlugin kayıtlı değilDoconutHost.Initialize içinde AddPlugin<ConverterPlugin>() ekleyin
Web Forms dönüşümü hiçbir zaman geri dönmezSayfa ConvertAsync üzerinde bloklanıyorAsync="true" ve RegisterAsyncTask kullanın
Akış dönüşümü formatın desteklenmediğini söylüyorsourceExtension başında nokta yok"xlsx" yerine ".xlsx" geçirin
ConvertAsync Converting '.dcm' requires the Dicom capability license. hatası atıyorBir DICOM kaynağı ve lisans Dicom sağlamıyorDicom sağlayan bir lisans kullanın
Çıktı su işareti taşıyorLisans geçici (Demo/NFR)Converter sağlayan bir ücretli lisans kullanın
Widget yükleniyor ancak istekleri 404 döndürüyorAddConverterWidget() çağrılmadı veya basePath '/DocImage.axd' değilAddConverterWidget() çağırın; basePath: '/DocImage.axd' ayarlayın
Büyük bir yükleme, widget mesajı yerine bir IIS hata sayfası gösteriyormaxRequestLength / maxAllowedContentLength MaxUploadMb altındaWeb.config limitlerini MaxUploadMb üzerine yükseltin
open 403 Converting this file type requires the Dicom capability license. yanıtı veriyorBir DICOM yüklemesi ve lisans Dicom sağlamıyorDicom sağlayan bir lisans kullanın
run 400 That target format is not available for this file. yanıtı veriyorHedef, kaynağın allowedTargets'lerinden biri değilconvert=open'den sadece allowedTargets sunun
run veya download 404 yanıtı verir (Upload expired — please re-open the file. run'den)30 dakikalık pencere geçti veya bir çiftlikteki başka bir sunucuda yükleme yokDosyayı tekrar açın; bir çiftlikte AddDoconutDistributedWidgets kaydedin
Widget, UI başka bir kökende olduğunda başarısız olurUç noktalar CORS desteğine sahip değilUI'yi aynı kökenden sunun veya Doconut yollarını ters proxy yapın
Tema uygulanmıyorDeğişkenler bir üst öğede veya mount içindeki bir öğede ayarlanmış; widget'ın kendi .dcw kuralı onları mount üzerine ayarlarMount'u doğrudan hedefleyin: #doconut-convert.dcw veya #doconut-convert

Çerçeve notları

ASP.NET Core paketleriyle karşılaştırıldığında, bu paket yalnızca barındırma açısından farklıdır; API, uç nokta sözleşmesi, widget betiği ve lisans kuralları aynıdır.

  • Kayıt Application_Start içinde, DoconutHost.Initialize aracılığıyla, builder.Services.AddDoconut yerine yapılır. AddDoconutDistributedWidgets gibi hizmetler ikinci argümanına gider.
  • Uç noktalar DocImage.axd tarafından ve betik DoconutResourceModule tarafından sunulur, ikisi de Web.config içinde kayıtlı, UseDoconut() ve UseDoconutResources() yerine. Widget basePath: '/DocImage.axd' gerektirir.
  • Başlangıç hataları her istekte boş bir 500 olarak ortaya çıkar, neden Windows olay günlüğünde bulunur.
  • Yüklemeler ASP.NET tarafından Doconut görmeden önce tamamen okunur, bu yüzden IIS limitleri MaxUploadMb'nin üzerinde olmalıdır.
  • Web Forms sayfaları bir dönüşümde bloklanmamalıdır; bkz. Web Forms içinde.
  • Yalnızca Windows, .NET Framework paketinin geri kalanları gibi.

Bu sayfa yardımcı oldu mu?