Doconut ile .NET'te Sunucu Tarafı Belge Dönüştürme

Giriş

Sunucu tarafı belge dönüştürme, bir uygulamanın Microsoft Office otomasyonu yapmadan veya kaynağı ayrı bir çevrimiçi dönüştürme hizmetine göndermeden normalleştirilmiş bir çıktı üretmesini sağlar. Bu, belge portalları, arka plan işleri ve kontrol edilen dışa aktarma iş akışlarını basitleştirebilir—ancak barındırma uygulaması hâlâ erişim kontrolü, depolama, saklama, izleme ve sonucun tesliminden sorumludur.

Doconut'un .NET 8 Dönüştürücü Eklentisi, bağımlılık‑enjeksiyonlu DocumentConverter servisi aracılığıyla dönüşümü sunar. Bu kılavuz, mevcut kayıt ve API modeline odaklanır ve dönüşümü bir görüntüleyici oturumuna bağlamaktan kaçınır.

---

Uyumlu paketleri kurun

Temel görüntüleyici ve dönüştürücü paketlerini kurun:

dotnet add package Doconut.NET8
dotnet add package Doconut.NET8.Converter

Her iki paketi aynı sürümde tutun. Tekrarlanabilir derlemeler önemliyse, sürümü proje dosyasında sabitleyin veya her iki komuta aynı --version değerini geçirin.

Dönüştürücü Eklentisini Kaydedin

Eklentiler, AddDoconut seçenek geri çağırması içinde kaydedilir. Ayrı bir AddConverter() kayıt yöntemi yoktur:

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "doconut.lic";
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
});

Uygulama, Dönüştürücü yeteneğini veren bir lisans kullanmalıdır. Başlangıç ve lisanslama hatalarını, dönüşüm işini kabul etmeden önce çözün; bunları, tanılaması daha zor olan bir arka plan kuyruğuna bırakmayın.

C# ile bir dosyayı dönüştürün

DocumentConverter'ı, dönüşüm isteğini yöneten uç nokta ya da hizmete enjekte edin. Dönüştürücünün yapıcı metodu içtedir, bu yüzden uygulama kodu doğrudan örneklememelidir.

app.MapPost("/api/convert", async (
    DocumentConverter converter,
    CancellationToken ct) =>
{
    await using Stream pdf = await converter.ConvertAsync(
        "documents/contract.docx",
        ConversionTarget.Pdf,
        ct: ct);

    using var copy = new MemoryStream();
    await pdf.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "contract.pdf");
});

Dönen akış aranabilir ve başlangıçta konumlandırılmıştır. Çağıran, akışı kopyaladıktan ya da içeriği döndürdükten sonra sorumludur ve serbest bırakmalıdır.

Yüklenen bir akışı dönüştürün

Akış aşırı yüklemesi, kaynağın uzantısını—başındaki nokta dahil—gerektirir; çünkü dönüştürücü, kaynak biçimini bu uzantı üzerinden çözer:

app.MapPost("/api/convert-upload", async (
    IFormFile file,
    DocumentConverter converter,
    CancellationToken ct) =>
{
    var extension = Path.GetExtension(file.FileName);
    await using var source = file.OpenReadStream();
    await using Stream output = await converter.ConvertAsync(
        source,
        extension,
        ConversionTarget.Pdf,
        password: null,
        ct: ct);

    using var copy = new MemoryStream();
    await output.CopyToAsync(copy, ct);
    return Results.File(copy.ToArray(), "application/pdf", "converted.pdf");
});

Dosya adı ve uzantıyı güvenilir olmayan girdi olarak ele alın. Yükleme limitlerini zorlayın, kaynak türünü doğrulayın, isteği yapan kullanıcıyı yetkilendirin ve gönderilen dosya adını bir depolama yolu olarak kullanmaktan kaçının.

Gerçek yeteneklerden hedef seçin

Eklenti bir ConversionTarget enum’u sunar, ancak her kaynak biçim her hedefi üretemez. Özel bir UI, tüm enum değerlerini göstermek yerine yalnızca yüklenen kaynak için izin verilen hedefleri göstermelidir.

Doconut'un isteğe bağlı dönüştürücü widget'ını kullandığınızda, yanıt içinde allowedTargets bulunur. Bu yanıtı, geçerli dosya için gerçek kaynak olarak kullanın.

Arka plan dönüşümünü bir uygulama iş akışı olarak tasarlayın

Dönüştürücü, bir uygulama hizmetinden ya da kuyruğa alınmış bir işçi üzerinden çağrılabilir. Sağlam bir iş genellikle şunları içerir:

1. Kaynağı ve istenen hedefi kaydeden kimliği doğrulanmış bir istek.
2. Ham kimlik bilgileri yerine bir uygulama iş kimliği içeren bir kuyruk mesajı.
3. Yetkilendirilmiş bir depolama soyutlaması üzerinden kaynağı getiren bir işçi.
4. İptal edilebilen sınırlı bir dönüşüm işlemi.
5. Açık saklama kurallarıyla dayanıklı çıktı depolama.
6. İç yolları ya da hassas istisna ayrıntılarını ifşa etmeyen bir durum güncellemesi.

İşçi sayısını belirlemeden önce temsilci belgelerle eşzamanlılığı ölçün. Dönüştürme maliyeti, kaynak biçimi, belge karmaşıklığı, yazı tipleri, görseller ve çıktı hedefi gibi faktörlere bağlı olarak değişir.

Güvenlik iddialarını net tutun

Dönüştürücüyü .NET uygulamanız içinde çalıştırmak, dönüşüm işleminin Microsoft Office otomasyonu ya da ayrı bir çevrimiçi dönüşüm API'si gerektirmediği anlamına gelir. Bu, sistemin gizlilik, uyumluluk, silme veya şifreleme gibi tüm yönlerini otomatik olarak garanti etmez.

Bu özellikler, uygulamanın kullanıcıları nasıl kimlik doğruladığı, kaynak dosyaları nasıl aldığı, depolamayı nasıl yapılandırdığı, günlükleri nasıl koruduğu, çıktıyı nasıl dağıttığı ve geçici ya da saklanan verileri nasıl sildiği gibi faktörlere bağlıdır.

Operasyonel kontrol listesi

• Doconut.NET8 ve Doconut.NET8.Converter sürümlerinin uyumlu olduğundan emin olun.
• Servis yapılandırması sırasında ConverterPlugin'i kaydedin.
• DocumentConverter'ı bağımlılık enjeksiyonu ile alın.
• Akış kaynak uzantılarında baştaki noktayı ekleyin.
• Kaynak ve sonuç akışlarını serbest bırakın.
• İptal ve uygulama‑seviyesi dosya‑boyutu limitlerini kullanın.
• Her çiftin çalıştığını varsaymak yerine kaynak‑hedef desteğini doğrulayın.
• Temsilci dosyalarla doğruluk ve kaynak kullanımını test edin.
• Depolama, yetkilendirme, denetim ve saklama kararlarını uygulama kodunda tutun.

Resmi Doconut Dönüştürücü Eklentisi incelemesi ve güncel ürün ve entegrasyon bilgileri için Doconut belgeleri sayfasına bakın.