Derleme sürümlerini yeniden yönlendirme

Makale
2025-03-06

Not

Bu makale .NET Framework'e özgüdür. .NET 6 ve sonraki sürümleri de dahil olmak üzere daha yeni .NET uygulamaları için geçerli değildir.

Derleme zamanı bağlama başvurularını .NET Framework derlemelerine, üçüncü taraf derlemelerine veya kendi uygulamanızın derlemelerine yeniden yönlendirebilirsiniz. Uygulamanızı bir derlemenin farklı bir sürümünü kullanmak için çeşitli yollarla yönlendirebilirsiniz: yayımcı ilkesi aracılığıyla, uygulama yapılandırma dosyası aracılığıyla veya makine yapılandırma dosyası aracılığıyla. Bu makalede derleme bağlamanın .NET Framework'te nasıl çalıştığı ve bunu nasıl yapılandırabileceğiniz açıklanır.

Bahşiş

Bu makale .NET Framework uygulamalarına özgüdür. .NET 5+ (ve .NET Core) içinde derleme yükleme hakkında bilgi için bkz. .NET'te bağımlılık yükleme.

Derleme birleştirme ve varsayılan bağlama

.NET Framework derlemelerine yapılan bağlamalar, bazen derleme birleştirmeadı verilen bir işlemle yeniden yönlendirilir. .NET Framework, ortak dil çalışma zamanının bir sürümünden ve tür kitaplığını oluşturan yaklaşık iki düzine .NET Framework derlemelerinden oluşur. Bu .NET Framework derlemeleri çalışma zamanı tarafından tek bir birim olarak değerlendirilir. Varsayılan olarak, bir uygulama başlatıldığında, çalışma zamanı tarafından çalıştırılan koddaki türlere yapılan tüm başvurular, bir işlemde yüklenen çalışma zamanıyla aynı sürüm numarasına sahip .NET Framework derlemelerine yönlendirilir. Bu modelde gerçekleşen yeniden yönlendirmeler çalışma zamanı için varsayılan davranıştır.

Örneğin, uygulamanız System.XML ad alanında türlere başvurursa ve .NET Framework 4.5 kullanılarak oluşturulduysa, çalışma zamanı sürümü 4.5 ile birlikte gelen System.XML derlemesine statik başvurular içerir. Bağlama başvuruyu .NET Framework 4 ile birlikte gelen System.XML derlemesine yönlendirmek istiyorsanız, yeniden yönlendirme bilgilerini uygulama yapılandırma dosyasına yerleştirebilirsiniz. Birleşik bir .NET Framework derlemesi için yapılandırma dosyasındaki bağlama yeniden yönlendirmesi, bu derlemenin birleştirilmesini iptal eder.

Ayrıca, birden çok sürüm varsa üçüncü taraf derlemeler için derleme bağlamasını el ile yeniden yönlendirmek isteyebilirsiniz.

İpucu

Uygulamanızın dolaylı olarak başvurduğunu bir NuGet paketini güncelleştirir ve FileLoadException, MissingMethodException, TypeLoadExceptionveya FileNotFoundExceptiongibi yeni hataları görmeye başlarsanız, otomatik bağlama yeniden yönlendirmelerini etkinleştirmeniz veya el ile bağlama yeniden yönlendirmesi eklemeniz gerekebilir. NuGet paketleri güncelleştirilirken bu normaldir ve bazı paketlerin bağımlılığın eski bir sürümüne göre derlenmesinin bir sonucudur. Aşağıdaki uygulama yapılandırma dosyası alıntısı, System.Memory paketiiçin bir bağlama yeniden yönlendirmesi ekler:

<dependentAssembly>
   <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
   <bindingRedirect oldVersion="0.0.0.0-4.0.2.0" newVersion="4.0.2.0" />
</dependentAssembly>

Yayımcı ilkesini kullanarak sürümleri yeniden yönlendirme

Derleme satıcıları, yeni derlemeye yayımcı ilke dosyası ekleyerek uygulamaları derlemenin daha yeni bir sürümüne yönlendirebilir. Genel derleme önbelleğinde bulunan yayımcı ilkesi dosyası, derleme yeniden yönlendirme ayarlarını içerir.

Her ana. Bir derlemeninikincil sürümü kendi yayımcı ilkesi dosyasına sahiptir. Örneğin, sürüm 2.0.2.222'den 2.0.3.000'e ve sürüm 2.0.2.321'den sürüm 2.0.3.000'e yeniden yönlendirmeler aynı dosyaya gider, çünkü bunlar sürüm 2.0 ile ilişkilidir. Ancak, sürüm 3.0.0.999'dan sürüm 4.0.0.000'e yeniden yönlendirme, 3.0.999 sürümü için dosyaya gider. .NET Framework'ün her ana sürümünün kendi yayımcı ilkesi dosyası vardır.

Bütünleştirilmiş kod için bir yayımcı ilkesi dosyası varsa, çalışma zamanı, bütünleştirilmiş kod bildirimi ve uygulama yapılandırma dosyasını denetledikten sonra bu dosyayı kontrol eder. Satıcılar, yayıncı ilkesi dosyalarını yalnızca yeni derleme, yönlendirilen derlemeyle geriye dönük uyumlu olduğunda kullanmalıdır.

Yayımcı ilkesini atla bölümünde açıklandığı gibi, uygulama yapılandırma dosyasında ayarları belirterek uygulamanız için yayımcı ilkesini atlayabilirsiniz.

Sürümleri uygulama düzeyinde yeniden yönlendirme

Uygulama yapılandırma dosyası aracılığıyla uygulamanız için bağlama davranışını değiştirmek için birkaç farklı teknik vardır: dosyayı el ile düzenleyebilirsiniz, otomatik bağlama yeniden yönlendirmesine güvenebilirsiniz veya yayımcı ilkesini atlayarak bağlama davranışını belirtebilirsiniz .

Uygulama yapılandırma dosyasını el ile düzenleme

Derleme sorunlarını çözmek için uygulama yapılandırma dosyasını el ile düzenleyebilirsiniz. Örneğin, bir satıcı uygulamanızın yayımcı ilkesi sağlamadan kullandığı derlemenin daha yeni bir sürümünü yayınlarsa (geriye dönük uyumluluğu garanti etmediğinden), uygulamanızı derleme bağlama bilgilerini uygulamanızın yapılandırma dosyasına aşağıdaki gibi koyarak derlemenin daha yeni sürümünü kullanmaya yönlendirebilirsiniz.

<dependentAssembly>
  <assemblyIdentity name="someAssembly"
    publicKeyToken="32ab4ba45e0a69a1"
    culture="en-us" />
  <bindingRedirect oldVersion="7.0.0.0" newVersion="8.0.0.0" />
</dependentAssembly>

Otomatik bağlama yeniden yönlendirmesine güvenme

Visual Studio'da .NET Framework 4.5.1 veya sonraki bir sürümü hedefleyen bir masaüstü uygulaması oluşturduğunuzda, uygulama otomatik bağlama yeniden yönlendirmesini kullanır. Başka bir deyişle, iki bileşen aynı tanımlayıcı adlandırılmış derlemenin farklı sürümlerine başvuruyorsa, çalışma zamanı otomatik olarak çıkış uygulaması yapılandırması (app.config) dosyasında derlemenin daha yeni sürümüne bağlama yeniden yönlendirmesi ekler. Bu yeniden yönlendirme, aksi takdirde gerçekleşebilecek derleme birleştirmeyi geçersiz kılar. Kaynak app.config dosyası değiştirilmez. Örneğin, uygulamanızın bant dışı bir .NET Framework bileşenine doğrudan başvurduğunu ancak aynı bileşenin eski bir sürümünü hedefleyen bir üçüncü taraf kitaplığı kullandığını düşünelim. Uygulamayı derlediğinizde, çıkış uygulaması yapılandırma dosyası bileşenin daha yeni sürümüne bağlama yeniden yönlendirmesi içerecek şekilde değiştirilir.

Bir web uygulaması oluşturursanız, bağlama çakışması ile ilgili bir derleme uyarısı alırsınız ve bu da size kaynak web yapılandırma dosyasına gerekli bağlama yeniden yönlendirmesini ekleme seçeneği sunar.

Bağlama yeniden yönlendirmelerini kaynak app.config dosyasına el ile eklerseniz, Visual Studio derlemeleri eklediğiniz bağlama yeniden yönlendirmelerine göre birleştirmeye çalışır. Örneğin, bir bileşen için aşağıdaki bağlama yeniden yönlendirmesini eklediğinizi varsayalım:

<bindingRedirect oldVersion="3.0.0.0" newVersion="2.0.0.0" />

Uygulamanızdaki başka bir proje aynı derlemenin 1.0.0.0 sürümüne başvuruyorsa, otomatik bağlama yeniden yönlendirmesi çıkış app.config dosyasına aşağıdaki girdiyi ekler, böylece uygulama bu derlemenin 2.0.0.0 sürümünde birleştirilir:

<bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />

Uygulamanız .NET Framework'ün eski sürümlerini hedeflerse otomatik bağlama yeniden yönlendirmesini etkinleştirebilirsiniz. Herhangi bir derleme için app.config dosyasında bağlama yeniden yönlendirme bilgileri sağlayarak veya bağlama yeniden yönlendirme özelliğini kapatarak bu varsayılan davranışı geçersiz kılabilirsiniz. Bu özelliği açma veya kapatma hakkında bilgi için bkz. Nasıl yapılır: Otomatik Bağlama Yeniden Yönlendirmesini Etkinleştirme ve Devre Dışı Bırakma.

Yayıncı politikasını atlamak

Gerekirse uygulama yapılandırma dosyasında yayımcı ilkesini geçersiz kılabilirsiniz. Örneğin, geriye dönük uyumlu olduğunu iddia eden derlemelerin yeni sürümleri yine de bir uygulamayı bozabilir. Yayımcı ilkesini atlamak istiyorsanız, uygulama yapılandırma dosyasındaki <dependentAssembly> öğesine bir <publisherPolicy> öğesi ekleyin ve önceki tüm yes ayarlarını geçersiz kılan apply özniteliğini noolarak ayarlayın.

<publisherPolicy apply="no" />

Uygulamanızı kullanıcılarınız için çalışır durumda tutmak için yayımcı ilkesini atla, ancak sorunu derleme satıcısına bildirdiğinizden emin olun. Bir derlemenin yayımcı ilkesi dosyası varsa, satıcı derlemenin geriye dönük olarak uyumlu olduğundan ve istemcilerin yeni sürümü mümkün olduğunca kullanabileceğinden emin olmalıdır.

Başka bir bileşen tarafından kullanılan testler, eklentiler veya kitaplıklar için yeniden yönlendirme sürümleri

Testler için bir .dll.config dosyası oluşturmanız gerekir. Mevcut birim testi çerçevelerinin çoğu, testleri yüklerken bu dosyalara uyar.

Eklentiler .dll.config dosyalarını kabul edebilir, ancak aynı şekilde kabul etmeyebilirler. Yeniden yönlendirmeler için tek garantili mekanizma, AppDomain oluşturulduğunda bindingRedirects sağlamaktır.

Bu sorunu AssemblyResolve olay işleyicileriyle çözmeyi deneyebilirsiniz, ancak bu işleyiciler yalnızca başarısız bir yükte çağrıldığından bu işe yaramaz. Derleme yükü, başka bir derleme veya ana bilgisayar tarafından yüklendiği veya GAC'de mevcut olduğu için başarılı olursa, AssemblyResolve işleyici çağrılmaz.

Sürümleri makine düzeyinde yeniden yönlendirme

Bir makine yöneticisinin bilgisayardaki tüm uygulamaların bir derlemenin belirli bir sürümünü kullanmasını istediği nadir durumlar olabilir. Örneğin, belirli bir sürüm bir güvenlik deliğini düzeltebilir. Bir derleme, machine.configolarak adlandırılan makinenin yapılandırma dosyasında yeniden yönlendirilirse, bu makinedeki eski sürümü kullanan tüm uygulamalar yeni sürümü kullanmaya yönlendirilir. Makine yapılandırma dosyası, uygulama yapılandırma dosyasını ve yayımcı ilkesi dosyasını geçersiz kılar. Bu machine.config dosyası 32 bit makineler için %windir%\Microsoft.NET\Framework[version]\config\machine.config veya 64 bit makineler için %windir%\Microsoft.NET\Framework64[version]\config\machine.config bulunur.

Yapılandırma dosyalarında montaj bağlamasını belirtin

Uygulama yapılandırma dosyasında, makine yapılandırma dosyasında veya yayımcı ilkesi dosyasında yer alan bağlama yeniden yönlendirmelerini belirtmek için aynı XML biçimini kullanırsınız. Bir derleme sürümünü başka bir derlemeye yeniden yönlendirmek için bindingRedirect><öğesini kullanın. oldVersion özniteliği tek bir derleme sürümü veya bir sürüm aralığı belirtebilir. newVersion özniteliği tek bir sürüm belirtmelidir. Örneğin, <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> çalışma zamanının 1.1.0.0 ile 1.2.0.0 arasındaki derleme sürümleri yerine 2.0.0.0 sürümünü kullanması gerektiğini belirtir.

Aşağıdaki kod örneği çeşitli bağlama yeniden yönlendirme senaryolarını gösterir. Örnek, myAssemblyiçin bir sürüm aralığı için bir yeniden yönlendirme ve mySecondAssemblyiçin tek bir bağlama yeniden yönlendirmesi belirtir. Örnek ayrıca yayımcı ilkesi dosyasının myThirdAssemblyiçin bağlama yeniden yönlendirmelerini geçersiz kılmayacağını belirtir.

Bir derlemeyi bağlamak için, <assemblyBinding> etiketinde xmlns özniteliğiyle "urn:schemas-microsoft-com:asm.v1" dizesini belirtmeniz gerekir.

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="myAssembly"
          publicKeyToken="32ab4ba45e0a69a1"
          culture="en-us" />
        <!-- Assembly versions can be redirected in app,
          publisher policy, or machine configuration files. -->
        <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="3.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="mySecondAssembly"
          publicKeyToken="32ab4ba45e0a69a1"
          culture="en-us" />
             <bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
      <assemblyIdentity name="myThirdAssembly"
        publicKeyToken="32ab4ba45e0a69a1"
        culture="en-us" />
        <!-- Publisher policy can be set only in the app
          configuration file. -->
        <publisherPolicy apply="no" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Derleme bağlamalarını belirli bir sürümle sınırlama

Derleme bağlama başvurularını belirli bir .NET Framework sürümüne yönlendirmek için bir uygulama yapılandırma dosyasındaki <assemblyBinding> öğesinde appliesTo özniteliğini kullanabilirsiniz. Bu isteğe bağlı öznitelik, hangi sürüm için geçerli olduğunu belirtmek için bir .NET Framework sürüm numarası kullanır. appliesTo özniteliği belirtilmezse, <assemblyBinding> öğesi .NET Framework'ün tüm sürümleri için geçerlidir.

Örneğin, .NET Framework 3.5 derlemesi için derleme bağlamasını yeniden yönlendirmek için uygulama yapılandırma dosyanıza aşağıdaki XML kodunu eklersiniz.

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"
    appliesTo="v3.5">
    <dependentAssembly>
      <!-- assembly information goes here -->
    </dependentAssembly>
  </assemblyBinding>
</runtime>

Yeniden yönlendirme bilgilerini sürümlere göre sıralayarak girmelisiniz. Örneğin, .NET Framework 3.5 derlemeleri için derleme bağlama yeniden yönlendirme bilgilerini ve ardından .NET Framework 4.5 derlemelerini girin. Son olarak, appliesTo özniteliğini kullanmayan ve bu nedenle .NET Framework'ün tüm sürümleri için geçerli olan herhangi bir .NET Framework derleme yeniden yönlendirmesi için derleme bağlama yeniden yönlendirme bilgilerini girin. Yeniden yönlendirmede çakışma varsa, yapılandırma dosyasındaki ilk eşleşen yeniden yönlendirme deyimi kullanılır.

Örneğin, bir başvuruyu .NET Framework 3.5 derlemesine ve başka bir başvuruyu .NET Framework 4 derlemesine yeniden yönlendirmek için aşağıdaki sahte kodda gösterilen deseni kullanın.

<assemblyBinding xmlns="..." appliesTo="v3.5 ">
  <!--.NET Framework version 3.5 redirects here -->
</assemblyBinding>

<assemblyBinding xmlns="..." appliesTo="v4.0.30319">
  <!--.NET Framework version 4.0 redirects here -->
</assemblyBinding>

<assemblyBinding xmlns="...">
  <!-- redirects meant for all versions of the runtime -->
</assemblyBinding>

Aracılığıyla paylaş