.NET ile Doconut kullanarak 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 ana uygulama 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üştürmeyi sunar. Bu kılavuz, mevcut kayıt ve API modeline odaklanır ve dönüştürmeyi 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 önemli olduğunda, 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çenekleri geri çağrısı içinde kaydedilir. Ayrı bir AddConverter() kayıt yöntemi yoktur:

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

Uygulama, Dönüştürücü yeteneğini veren bir lisans kullanmalıdır. Başlatma ve lisanslama hatalarını, dönüşüm işini kabul etmeden önce çözün; bunları daha zor teşhis edilebilecek 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 veya servise enjekte edin. Dönüştürücünün yapıcı metodu içtedir, bu yüzden uygulama kodu onu 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öndürülen akış aranabilir ve baştan konumlandırılmıştır. Çağıran onu sahiplenir ve içeriği kopyaladıktan ya da döndürdükten sonra serbest bırakmalıdır.

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

Akış aşırı yüklemesi, kaynak uzantısını—başındaki nokta dahil—gerektirir; çünkü dönüştürücü bunu kaynak formatı çözmek için kullanır:

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üvenilmeyen girdi olarak ele alın. Yükleme limitlerini zorlayın, kaynak tipini 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 hedefler seçin

Eklenti bir ConversionTarget enum’u sunar, ancak her kaynak formatı her hedefi üretemez. Özel bir UI, yüklenen kaynak için izin verilen hedefleri göstermek üzere tüm enum değerlerini listelemek yerine yalnızca geçerli 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ı mevcut 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 servisi ya da kuyruğa alınmış bir işçi tarafından ç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 içermeyen, uygulama iş kimliği taşıyan bir kuyruk mesajı.
3. Yetkilendirilmiş bir depolama soyutlaması üzerinden kaynağı getiren bir işçi.
4. İptal edilebilir sınırlı bir dönüşüm işlemi.
5. Açık saklama kurallarıyla dayanıklı çıktı depolaması.
6. İç yolları ya da hassas istisna detaylarını ortaya çıkarmayan bir durum güncellemesi.

İşçi sayısını seçmeden önce temsilci belgelerle eşzamanlılığı ölçün. Dönüşüm maliyeti, kaynak formatına, belge karmaşıklığına, yazı tiplerine, görsellere ve çıktı hedefine göre değişir.

Güvenlik iddialarını kesin 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 bütünlüğü için gizlilik, uyumluluk, silme ya da şifreleme garantisi vermez.

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 ConverterPlugini 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 tüketimini test edin.
• Depolama, yetkilendirme, denetim ve saklama kararlarını uygulama kodunda tutun.

Resmi Doconut Converter Plugin incelemesi ve güncel ürün ve entegrasyon bilgileri için Doconut documentation sayfasına bakın.