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

Converter eklentisi Doconut'u bir belge-dönüştürme hizmetine dönüştürür. DocumentConverter genel arayüzü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.

Paketi Yükleyin

Install-Package Doconut.NETFramework.Converter

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

Eklentiyi Kaydedin

Her eklenti aynı şekilde kaydedilir: AddPlugin<TPlugin>() içinde DoconutHost.Initialize.

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

Eğer aktif bir lisans Converter yeteneğini vermiyorsa — lisans yok, eski bir TRIAL dosyası, ya da bu yeteneği içermeyen bir lisans — DoconutHost.Initialize, Application_Start üzerinden fırlatır. System.Web içinde bu, her isteğin boş bir 500 döndürdüğü anlamına gelir ve neden yalnızca Windows olay günlüğünde (kaynak ASP.NET) bulunur. Geçici Demo/NFR lisansları kabul edilir. Bakınız Lisans Kurulumu.

C#'tan Dönüştürme

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

// DocumentConverter'ı DoconutHost.Services'tan çözün; yapıcı içsel olduğu için, asla `new` etmeyin.
Stream pdf = await converter.ConvertAsync("contract.docx", ConversionTarget.Pdf, ct: ct);

// sourceExtension baştaki noktayı içerir. password, belge korunmuyorsa null olur.
Stream png = await converter.ConvertAsync(upload, ".xlsx", ConversionTarget.Png, password: null, ct: ct);

Stream html = await converter.WordToHtmlAsync("report.docx", ct);

Stream docx = await converter.HtmlToWordAsync(html, ConversionTarget.Docx, ct);

Yanlış yapılması kolay iki detay: stream overload'unda sourceExtension, baştaki noktayı (".xlsx", "xlsx" değil) içermelidir, aksi takdirde çözülmez. Ve adının aksine, WordToHtmlAsync Task<Stream> döndürür, Task<string> değil — HTML belge (Base64 olarak gömülü görüntüler) bir stream olarak gelir, diğer tüm sonuçlar gibi.

MVC 5 denetleyicisinde

Eylemi asenkron yapın ve dönüşümü await.

[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 bloklamayın

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 da bir deadlock 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:

<%@ Page Language="C#" Async="true" CodeBehind="Convert.aspx.cs" Inherits="MyApp.Convert" %>

// Web Forms: @Page yönergesi Async="true" gerektirir ve dönüşüm bir sayfa async görevi olarak çalışır.
// Bunun üzerine bloklama yapmak (.Result, .Wait(), .GetAwaiter().GetResult()) isteği kilitler:
// asla geri 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();
        }
    }));
}

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

Hedef formatlar

Pdf, Docx, Doc, Html, Xlsx, Pptx, Png, Jpeg, Csv, Tiff, Bmp, Gif, Svg, Xml,
Txt, Xls, Jp2, Rtf, Odt, Ods, Odp, Epub, Xps, Webp

Her kaynak her hedefe dönüştürülemez: her kaynağın format ailesi (Word, Excel, PowerPoint, PDF, CAD, Image, Email, Diagram, Project, PSD, web document) kendi izin verilen hedef setine sahiptir. Bu enum'ı UI'nizin hedef listesi olarak sabitlemeyin: ?convert=open, yüklenen dosya için allowedTargets döndürür ve bu, bir seçim kutusunu yönlendirmelidir.

Drop-in widget

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

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 görmeden önce tüm yüklemeyi okur: maxRequestLength (KB) ve
// maxAllowedContentLength (bytes) Web.config içinde widget'in MaxUploadMb'sinin üzerinde.

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

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

• basePath: '/DocImage.axd'. Widget'ın varsayılanı, /doconut, ASP.NET Core uç noktasındır. Bu pakette, uç noktalar DocImage.axd işleyicisidir Web.config'dan.
• 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 sınırlamaları

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

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

Widget'ı özelleştir

Doconut.convert(selector, options)'a geçirilen seçenekler:

Geri çağrılar:

Doconut.convert() widget örneğini döndürür: reset() bırakma ekranına döner, loadFile(file) bir File ile akışı başlatır ve destroy() onu kaldırır.

Kendi ön ucunuzu oluşturun

Widget, DocImage.axd üzerindeki bu HTTP sözleşmesi için bir istemcidir:

Yüklenen kaynaklar 30 dakika saklanır; bu sürenin ardından run, 404 yanıtını verir ve dosya yeniden açılmalıdır. Dönüşüm tamamlandığında downloadToken kendi 30 dakikalık penceresini alır. resultToken, görüntüleyici oturumunun ömrünü izleyen sıradan bir görüntüleyici belirtecidir.

sourceExt, open yanıtında başında nokta ("docx") bulunmaz — bu, ConvertAsync'in sourceExtension parametresinin tersidir.

Kaynak sahipliği

Çağıran, dönüşümün döndürdüğü MemoryStream'i sahiplenir ve kopyaladıktan veya döndürdükten sonra serbest bırakmalıdır (MVC'nin File(stream, …) sizin için serbest bırakır). DocumentConverter'i kendiniz oluşturmayın veya serbest bırakmayın — yapıcı içtedir.

Filigran ekleme

Bir entegrasyon, satın almadan önce değerlendirme lisansı üzerinde uçtan uca oluşturulup test edilebilir — yalnızca çıktı baytları değişir.

Sorun giderme