Kaynak kodu ve yapılandırma dosyalarını dönüştürme

Makale
10/18/2023

Kaynak kodu dönüşümü, paket yüklendiğinde paketin content veya contentFiles klasöründeki dosyalara (contentve contentFiles kullanan packages.config müşteriler içinPackageReference) tek yönlü belirteç değişimi uygular ve burada belirteçler Visual Studio proje özelliklerine başvurur. Bu, projenin ad alanına bir dosya eklemenize veya genellikle bir ASP.NET projesinde girebilecek global.asax kodu özelleştirmenize olanak tanır.

Yapılandırma dosyası dönüşümü, ve app.configgibi web.config bir hedef projede zaten var olan dosyaları değiştirmenize olanak tanır. Örneğin, paketinizin yapılandırma dosyasındaki modules bölüme bir öğe eklemesi gerekebilir. Bu dönüştürme işlemi, yapılandırma dosyalarına eklenecek bölümleri açıklayan özel dosyalar pakete eklenerek gerçekleştirilir. Bir paket kaldırıldığında, aynı değişiklikler geri alınır ve bu iki yönlü bir dönüştürme olur.

Kaynak kodu dönüştürmelerini belirtme

Paketten projeye eklemek istediğiniz dosyalar paketin content ve contentFiles klasörlerinin içinde bulunmalıdır. Örneğin, adlı ContosoData.cs bir dosyanın hedef projenin bir Models klasörüne yüklenmesini istiyorsanız, dosyanın paketteki ve contentFiles\{lang}\{tfm}\Models klasörlerinin content\Models içinde olması gerekir.
NuGet'e yükleme zamanında belirteç değiştirme uygulaması talimatı vermek için kaynak kod dosya adına ekleyin .pp . Yüklemeden sonra dosya uzantısına .pp sahip olmayacaktır.

Örneğin, içinde ContosoData.csdönüştürmeler yapmak için paketindeki ContosoData.cs.ppdosyayı olarak adlandırın. Yüklemeden sonra olarak ContosoData.csgörünür.
Kaynak kod dosyasında, NuGet'in proje özellikleriyle değiştirmesi gereken değerleri belirtmek için formun $token$ büyük/küçük harfe duyarlı olmayan belirteçlerini kullanın:
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Yüklemeden sonra NuGet, kök ad alanı Fabrikamolan hedef projenin olduğunu varsayarak değerini ile Fabrikam değiştirir $rootnamespace$ .

Belirteç $rootnamespace$ en yaygın kullanılan proje özelliğidir; diğer tüm özellikler proje özelliklerinde listelenir. Bazı özelliklerin proje türüne özgü olabileceğine dikkat edin.

Yapılandırma dosyası dönüştürmelerini belirtme

Sonraki bölümlerde açıklandığı gibi, yapılandırma dosyası dönüştürmeleri iki şekilde yapılabilir:

Uzantının NuGet'e content paket yüklendiğinde var olan yapılandırma dosyalarıyla birleştirmesi için XML'yi içerdiğini bildirdiği .transform paketinizin klasörüne ve web.config.transform dosyalarını ekleyinapp.config.transform. Bir paket kaldırıldığında, aynı XML kaldırılır.
İstediğiniz değişiklikleri açıklamak için XDT söz dizimini kullanarak paketinizin content klasörüne ve web.config.install.xdt dosyalarını ekleyinapp.config.install.xdt. Bu seçenekle, paket projeden .uninstall.xdt kaldırıldığında değişiklikleri tersine çevirmek için bir dosya da ekleyebilirsiniz.

Not

Dönüştürmeler, Visual Studio'da bağlantı olarak başvuruda bulunan dosyalara .config uygulanmaz.

XDT kullanmanın avantajı, yalnızca iki statik dosyayı birleştirmek yerine, tam XPath desteği kullanılarak öğe ve öznitelik eşleştirme kullanarak XML DOM'unun yapısını düzenlemeye yönelik bir söz dizimi sağlamasıdır. XDT daha sonra öğeleri ekleyebilir, güncelleştirebilir veya kaldırabilir, belirli bir konuma yeni öğeler yerleştirebilir veya öğeleri (alt düğümler dahil) değiştirebilir/kaldırabilir. Bu, paket yüklemesi sırasında yapılan tüm dönüştürmeleri geri alan kaldırma dönüşümleri oluşturmayı kolaylaştırır.

XML dönüşümleri

app.config.transform Bir paketin content klasöründeki ve web.config.transform yalnızca projenin mevcut app.config ve web.config dosyalarıyla birleştirilecek öğeleri içerir.

Örneğin, projenin başlangıçta içinde web.configaşağıdaki içeriği içerdiğini varsayalım:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

Paket yükleme sırasında bölümüne bir MyNuModule öğe modules eklemek için paketin content klasöründe aşağıdakine benzer bir web.config.transform dosya oluşturun:

<configuration>
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

NuGet paketi web.config yükledikten sonra aşağıdaki gibi görünür:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

NuGet'in bölümün yerini modules almadığını, yalnızca yeni öğeler ve öznitelikler ekleyerek yeni girişi birleştirdiğini unutmayın. NuGet var olan öğeleri veya öznitelikleri değiştirmez.

Paket kaldırıldığında NuGet dosyaları yeniden inceler .transform ve içerdiği öğeleri uygun .config dosyalardan kaldırır. Bu işlemin, paket yüklemesinin .config ardından dosyada değiştirdiğiniz satırları etkilemeyeceğini unutmayın.

Daha kapsamlı bir örnek olarak, ASP.NET için Hata Günlüğü Modülleri ve İşleyicileri (ELMAH) paketi içine web.configbirçok girdi ekler ve bu girdiler bir paket kaldırıldığında yeniden kaldırılır.

Dosyasını incelemek web.config.transform için yukarıdaki bağlantıdan ELMAH paketini indirin, paket uzantısını .nupkg.zipolarak değiştirin ve bu ZIP dosyasında açın content\web.config.transform .

Paketi yüklemenin ve kaldırmanın etkisini görmek için Visual Studio'da yeni bir ASP.NET projesi oluşturun (şablon, Yeni Proje iletişim kutusundaki Visual C# > Web altındadır) ve boş bir ASP.NET uygulaması seçin. İlk durumunu görmek için açın web.config . Ardından projeye sağ tıklayın, NuGet Paketlerini Yönet'i seçin, nuget.org ELMAH'a göz atın ve en son sürümü yükleyin. 'de yapılan tüm değişikliklere web.configdikkat edin. Şimdi paketi kaldırdığınızda önceki durumuna geri döndüğünü göreceksiniz web.config .

XDT dönüşümleri

Not

belgelerinden sürümüne geçişpackages.configPackageReferenceiçin belgelerde paket uyumluluğu sorunları bölümünde belirtildiği gibi, aşağıda açıklandığı gibi XDT dönüştürmeleri yalnızca tarafından packages.configdesteklenir. Aşağıdaki dosyaları paketinize eklerseniz, paketinizi kullanan PackageReference tüketicilerin dönüştürmeleri uygulanmaz (XDT dönüşümlerinin birlikte çalışmasınıPackageReference sağlamak için bu örneğe bakın).

XDT söz dizimlerini kullanarak yapılandırma dosyalarını değiştirebilirsiniz. Ayrıca, sınırlayıcılara özellik adını $ ekleyerek (büyük/küçük harfe duyarlı olmayan) NuGet'in belirteçleri proje özellikleriyle değiştirmesini sağlayabilirsiniz.

Örneğin, aşağıdaki app.config.install.xdt dosya içine projeden , FileNameve ActiveConfigurationSettings değerlerini içeren FullPathbir appSettings öğe app.config ekler:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <appSettings xdt:Transform="Insert">
        <add key="FullPath" value="$FullPath$" />
        <add key="FileName" value="$filename$" />
        <add key="ActiveConfigurationSettings " value="$ActiveConfigurationSettings$" />
    </appSettings>
</configuration>

Başka bir örnek için projenin başlangıçta içinde web.configaşağıdaki içeriği içerdiğini varsayalım:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
        </modules>
    </system.webServer>
</configuration>

Paket yükleme sırasında bölümüne bir MyNuModule öğe modules eklemek için, paketin web.config.install.xdt öğeleri şunları içerebilir:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" type="Sample.MyNuModule" xdt:Transform="Insert" />
        </modules>
    </system.webServer>
</configuration>

Paketi yükledikten sonra şöyle web.config görünür:

<configuration>
    <system.webServer>
        <modules>
            <add name="ContosoUtilities" type="Contoso.Utilities" />
            <add name="MyNuModule" type="Sample.MyNuModule" />
        </modules>
    </system.webServer>
</configuration>

Paket kaldırma web.config.uninstall.xdt sırasında yalnızca MyNuModule öğesini kaldırmak için, dosya aşağıdakileri içermelidir:

<?xml version="1.0"?>
<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
    <system.webServer>
        <modules>
            <add name="MyNuModule" xdt:Transform="Remove" xdt:Locator="Match(name)" />
        </modules>
    </system.webServer>
</configuration>

Share via