Giriş

Bir meslektaşınız bir sözleşmenin iki revizyonunu gönderir ve sizden bunları karşılaştırmanızı ister. İkisini de karşılaştırma hizmetinize bırakırsınız, sonuç geri döner ve her şey normal görünür. Görmediğiniz şey, bu belgelerden birinin bir URL’ye işaret eden bağlı bir resim içermesiydi ve dosya açıldığı anda sunucunuz o hosta bağlandı. Çıktıda bunun gerçekleştiğine dair hiçbir şey yok.

Bu bir hata değildir – bir belgenin sadakatle yüklenmesinin ne anlama geldiğidir. OOXML dosyası, paketin içinde değil bir web sunucusunda bulunan bir resmi referans alabilir ve hem Word hem de belgeyi doğru şekilde yükleyen herhangi bir kütüphane bu referansı çözer. GroupDocs.Comparison for .NET, bu davranışı kontrol etmenizi sağlayan LoadOptions üzerinde iki özellik sunar: SkipExternalResources ve WhitelistedResources.

Bu iki özellik üç yapılandırma seçeneği sunar ve bu makale üçünü karşılaştırır – izin verici varsayılan, her şeyi engelleme ve adlandırılmış referanslar dışındaki her şeyi engelleme. Sonunda, belirli bir belge kaynağı için hangi seçeneği seçeceğinizi ve bu ayarların çalışmadığını düşündüren iki hatayı öğreneceksiniz.

💡 Tam çalışan örnek: block-external-resources-on-document-load-dotnet – referans verilen resimleri kendisi sunan ve her isteği kaydeden çalıştırılabilir bir konsol projesi; böylece her ayarın etkisini izleyebilirsiniz.

Dış Referansların Nerede Gizlendiği

Bir ayarı seçmeden önce, neyi seçtiğinizi bilmek gerekir. Bir .docx dosyası dış referansları iki ayrı yerde barındırır ve ikisi de belge metninde görünmediği için gözden kaçması kolaydır.

İlk olarak, word/_rels/document.xml.rels içinde TargetMode="External" ve mutlak bir URL içeren bir ilişki bulunur. Resim, içerikte bir çizim olarak görünür ve ilişki ID’siyle işaretlenir; bu yüzden URL, etkilediği içerik yakınında hiç görülmez.

İkinci olarak, belge gövdesinde bir INCLUDEPICTURE alan kodu bulunur; URL bu alan talimatı içinde saklanır. Word sayfa render edildiğinde bu URL’yi çözer; bir karşılaştırma kütüphanesi ise belge yüklendiğinde çözer.

Her iki mekanizma da aşağıda tartışılan iki yükleme seçeneğine saygı gösterir; bu önemlidir çünkü bir belge birini, diğerini ya da her ikisini de kullanabilir. İlişkiler dosyasında gördüğünüz bir referans, alan kodunda ikinci bir referans olmadığı anlamına gelmez.

Yaklaşım 1: Varsayılan – Referanslar Çözülür

SkipExternalResources varsayılan olarak false olduğundan, yapılandırma olmadan yüklenen bir belge uzaktaki referanslarını çözer:

LoadOptions loadOptions = new LoadOptions
{
    SkipExternalResources = false
};

using (Comparer comparer = new Comparer(sourcePath, loadOptions))
{
    comparer.Add(targetPath, loadOptions);
    comparer.Compare(outputPath);
}

Bu, en yüksek sadakati sağlar: karşılaştırılan belgeler, Word’ün render edeceği şekilde, referans verdikleri her şeyi içerir. Kendi uygulamanız ya da şablonlarınız tarafından üretilen belgeler için, her referans URL’si sizin kontrol ettiğiniz altyapıya işaret ettiğinden bu doğru seçimdir – ve eksik bir bağlı resim, karşılaştırmayı aktif olarak yanıltıcı hâle getirebilir.

Maliyeti ise, her referansın, onu ekleyen tarafın sunucusuna bağlanmasıdır. Güvenle ilgili olmayan bir zaman maliyeti de vardır: artık çözülemeyen bir referans URL’si, her karşılaştırmada tam bağlantı denemesini bekletir.

Yaklaşım 2: Her Dış Kaynağı Engelle

Bir özellik, o belge için uzaktan referans çözümlemesini kapatır:

LoadOptions loadOptions = new LoadOptions
{
    SkipExternalResources = true
};

using (Comparer comparer = new Comparer(sourcePath, loadOptions))
{
    comparer.Add(targetPath, loadOptions);
    comparer.Compare(outputPath);
}

Hiç istek gönderilmez. Referans verilen resimler sonuçtan eksik olur ve – burada net olmak gerekir – başka hiçbir şey değişmez. Ayar, neyin yükleneceğini belirler, farkların nasıl bulunacağını değil; bu yüzden iki belge arasındaki metinsel ve yapısal değişiklikler aynı şekilde tespit edilir. Kaybettiğiniz tek şey, hiç yüklenmemiş bir referans resmindeki değişikliği algılayabilme yeteneğidir.

Bu yapılandırma, siz tarafından oluşturulmamış belgeler için temel (baseline) olarak kullanılmalıdır: bir web uygulamasına kullanıcı yüklemeleri, e‑posta ile gelen dosyalar, bir build ajanı üzerinde karşılaştırılan her şey – dışarıya çıkış isteği nadiren istenen durumlar. Bu “her şey ya da hiç” yaklaşımı, istediğiniz bir bağlı resmi de diğerleriyle birlikte engeller; sonuçta eksik bir resim olur ve bu eksiklik bildirilmez.

Yaklaşım 3: Adlandırılmış Referanslar Dışında Her Şeyi Engelle

Üçüncü yapılandırma, dikkatli bir okuma gerektiren seçenektir. WhitelistedResources, bir List<string> alır ve yalnızca SkipExternalResources true olduğunda değerlendirilir:

LoadOptions loadOptions = new LoadOptions
{
    SkipExternalResources = true,
    WhitelistedResources = new List<string> { "includepicture-field.png" }
};

using (Comparer comparer = new Comparer(sourcePath, loadOptions))
{
    comparer.Add(targetPath, loadOptions);
    comparer.Compare(outputPath);
}

Girişler URL parçacıklarıdır, dosya adları değil. Her biri referans URL’si içinde aranır; bir eşleşme bulunduğunda o kaynak kabul edilir. Bu, beyaz listenin taşınabilir olmasını sağlar: "includepicture-field.png" ifadesi, önünde ne protokol, host ya da yol olursa olsun resmi kabul eder; böylece aynı liste geliştirme ve üretim ortamlarında yeniden yazılmadan kullanılabilir.

Aynı özellik ters yönde de çalışır. Kısa ya da genel bir parçacık – logo.png ya da daha da kötüsü .png – izin vermek istemediğiniz referansları da eşleştirebilir. İzin vermek istediğiniz tek kaynağı tanımlayacak kadar özgül bir parçacık seçin.

Örnek referansta, bu yapılandırma beyaz listedeki resmi getirir, ikinci referanslı resmi ise (liste içinde olmayan) engeller. İstek günlüğü, izin verici varsayılanın beş istek gönderdiği durumda üç istek gösterir ve yalnızca beyaz listedeki dosyayı adlandırır.

Hangi Yapılandırmayı Kullanmalısınız?

Ayarı, belgenin geldiği yere göre eşleştirin. Kendi uygulamanız ya da şablonlarınız tarafından üretilen belgeler varsayılanı koruyabilir, çünkü her referans URL’si zaten kontrol ettiğiniz altyapıya işaret eder. Dışarıdan gelen her şey – kullanıcı yüklemeleri, e‑posta ekleri, üçüncü taraf dosyalar – SkipExternalResources = true ile kullanılmalıdır. Yalnızca gerçekten çözülmesi gereken güvenilir bir referans varsa dar bir WhitelistedResources parçacığı ekleyin.

Üç Yapılandırmanın Karşılaştırması

Endişe Varsayılan Hepsini Engelle Engelle + Beyaz Liste
Ayarlanacak özellik sayısı 0 1 2
Giden istekler tüm referanslar hiçbiri yalnızca beyaz listedekiler
Referans başına kontrol hayır hayır evet
Çökmüş URL yük süresini artırır evet hayır yalnızca beyaz listedekiler
En uygun kullanım ürettiğiniz belgeler dış kaynaklı belgeler güvenilir şablonlar içinde güvensiz içerik

Karar, performanstan çok belge kökenine dayanır. Sistemleriniz tarafından üretilen belgeler varsayılanı tutabilir. Dışarıdan gelen belgeler engellenmelidir. Beyaz liste, yalnızca belirli bir referansın gerçekten çözülmesi gerektiği durumlarda kullanılmalıdır – örneğin bir kurumsal şablonun başlık resmini iç içe bir URL’den alması gibi.

İki Hata

Bu iki durum aynı semptomu üretir: ayarı belirlediğiniz halde hiçbir şey değişmemiş gibi görünür.

Beyaz liste, anahtar olmadan. WhitelistedResources yalnızca SkipExternalResources true olduğunda değerlendirilir. Tek başına ayarlandığında hiçbir etkisi yoktur – engelleme olmadığı için istisna yapılacak bir şey de yoktur. Beyaz listenin göz ardı edildiğini düşünüyorsanız, önce bunu kontrol edin.

Seçeneklerin yalnızca kaynakta kullanılması. Bu daha ince bir hatadır. Yükleme seçenekleri, bir belgenin nasıl yükleneceğini tanımlar. Comparer yapıcı (constructor) kaynak için seçenekleri alır; her Add() çağrısı ise hedef için seçenekleri alır:

using (Comparer comparer = new Comparer(sourcePath, loadOptions))
{
    comparer.Add(targetPath, loadOptions);
    comparer.Compare(outputPath);
}

Seçenekleri sadece yapıcıya geçirip Add() çağrısında unutursanız, kaynak korunur fakat her hedef hâlâ referanslarını çeker. Karşılaştırma başarılı olur, sonuç makul görünür ve belgelerinizin yarısı hâlâ ağa bağlanır. Kaynak ve hedefin farklı davranması gerektiğinde, ayrı LoadOptions örnekleri kullanın – API’nin bunu belge başına almasının tam nedeni budur.

Gerçekten Çalıştığını Doğrulama

Engellenen bir kaynak neredeyse hiç iz bırakmaz. Çıktı belgesi bir resim eksik olur; bu da hiç resim olmayan bir belgeye çok benzer. Bu yüzden ayarın etkili olduğunu doğrulamak için sonuç dosyasını okumak yetersizdir.

Bunun yerine sunucu tarafını izleyin. Referans örneği bu yaklaşımı kasıtlı olarak kullanır: boş bir loopback portunda küçük bir HTTP dinleyicisi başlatır, demo belgelerini bu porta işaret edecek şekilde yazar ve aldığı her isteği kaydeder, karşılaştırma başına sayıyı yazdırır. Beş istek, sonra sıfır, sonra üç. Gerçek belge kaynaklarınızda bir ağ izleme yaparak aynı güveni elde edebilirsiniz.

Sonuç

Üç yapılandırma, tek bir karar kuralı: siz üretmiş olduğunuz belgeler varsayılanı korursun, diğer her şey için SkipExternalResources = true ayarlansın ve yalnızca belirli, güvenilir bir referansın hâlâ çözülmesi gerektiği durumlarda dar bir URL parçacığı beyaz listeye eklensin.

Ardından iki sessiz iptali kontrol edin – SkipExternalResources = true olmadan beyaz liste ve Comparer yapıcısına verilen ama Add() çağrısına geçirilmeyen seçenekler – ve ayarın etkisini çıktı dosyasından değil, sunucu tarafından doğrulayın.

Ek Kaynaklar