Mengubah kode sumber dan file konfigurasi

Artikel
10/23/2023

Transformasi kode sumber menerapkan penggantian token satu arah ke file di paket content atau contentFiles folder (content untuk pelanggan yang menggunakan packages.config dan contentFiles untuk PackageReference) saat paket diinstal, di mana token merujuk ke properti proyek Visual Studio. Ini memungkinkan Anda menyisipkan file ke dalam namespace layanan proyek, atau untuk menyesuaikan kode yang biasanya akan masuk ke global.asax dalam proyek ASP.NET.

Transformasi file konfigurasi memungkinkan Anda memodifikasi file yang sudah ada dalam proyek target, seperti web.config dan app.config. Misalnya, paket Anda mungkin perlu menambahkan item ke bagian modules dalam file konfigurasi. Transformasi ini dilakukan dengan menyertakan file khusus dalam paket yang menjelaskan bagian yang akan ditambahkan ke file konfigurasi. Ketika paket dihapus instalannya, perubahan yang sama tersebut kemudian dibalik, menjadikannya transformasi dua arah.

Menentukan transformasi kode sumber

File yang ingin Anda sisipkan dari paket ke dalam proyek harus terletak di dalam paket content dan contentFiles folder. Misalnya, jika Anda ingin file yang disebut ContosoData.cs diinstal dalam Models folder proyek target, file harus berada di dalam content\Models folder dan contentFiles\{lang}\{tfm}\Models dalam paket.
Untuk menginstruksikan NuGet untuk menerapkan penggantian token pada waktu penginstalan, tambahkan .pp ke nama file kode sumber. Setelah penginstalan, file tidak akan memiliki .pp ekstensi.

Misalnya, untuk membuat transformasi di ContosoData.cs, beri nama file dalam paket ContosoData.cs.pp. Setelah penginstalan, itu akan muncul sebagai ContosoData.cs.
Dalam file kode sumber, gunakan token formulir $token$ yang tidak peka huruf besar/kecil untuk menunjukkan nilai yang harus diganti NuGet dengan properti proyek:
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Setelah penginstalan, NuGet mengganti $rootnamespace$ dengan Fabrikam asumsi proyek target yang namespace akarnya adalah Fabrikam.

Token $rootnamespace$ adalah properti proyek yang paling umum digunakan; semua yang lain tercantum dalam properti proyek. Berhati-hatilah, tentu saja, bahwa beberapa properti mungkin spesifik untuk jenis proyek.

Menentukan transformasi file konfigurasi

Seperti yang dijelaskan di bagian berikut, transformasi file konfigurasi dapat dilakukan dengan dua cara:

Sertakan app.config.transform dan web.config.transform file dalam folder paket content Anda, di mana .transform ekstensi memberi tahu NuGet bahwa file-file ini berisi XML untuk digabungkan dengan file konfigurasi yang ada saat paket diinstal. Saat paket dihapus instalannya, XML yang sama akan dihapus.
Sertakan app.config.install.xdt file dan web.config.install.xdt dalam folder paket content Anda, menggunakan sintaks XDT untuk menjelaskan perubahan yang diinginkan. Dengan opsi ini, Anda juga dapat menyertakan .uninstall.xdt file untuk membalikkan perubahan saat paket dihapus dari proyek.

Catatan

Transformasi tidak diterapkan ke .config file yang dirujuk sebagai tautan di Visual Studio.

Keuntungan menggunakan XDT adalah alih-alih hanya menggabungkan dua file statis, ia menyediakan sintaks untuk memanipulasi struktur XML DOM menggunakan elemen dan pencocokan atribut menggunakan dukungan XPath penuh. XDT kemudian dapat menambahkan, memperbarui, atau menghapus elemen, menempatkan elemen baru di lokasi tertentu, atau mengganti/menghapus elemen (termasuk simpul anak). Hal ini membuatnya mudah untuk membuat transformasi penghapusan instalan yang memundurkan semua transformasi yang dilakukan selama penginstalan paket.

Transformasi XML

dan dalam folder paket content hanya berisi elemen-elemen tersebut untuk digabungkan ke dalam file dan web.config proyek yang adaapp.config.web.config.transformapp.config.transform

Sebagai contoh, misalkan proyek awalnya berisi konten berikut di web.config:

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

Untuk menambahkan MyNuModule elemen ke modules bagian selama penginstalan paket, buat web.config.transform file di folder paket content yang terlihat seperti ini:

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

Setelah NuGet menginstal paket, web.config akan muncul sebagai berikut:

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

Perhatikan bahwa NuGet tidak mengganti bagian modules , itu hanya menggabungkan entri baru ke dalamnya dengan hanya menambahkan elemen dan atribut baru. NuGet tidak akan mengubah elemen atau atribut yang ada.

Ketika paket dihapus, NuGet akan memeriksa .transform file lagi dan menghapus elemen yang dikandungnya dari file yang sesuai .config . Perhatikan bahwa proses ini tidak akan memengaruhi baris apa pun dalam .config file yang Anda ubah setelah penginstalan paket.

Sebagai contoh yang lebih luas, modul Pengelogan Kesalahan dan Handler untuk paket ASP.NET (ELMAH) menambahkan banyak entri ke dalam web.config, yang lagi dihapus ketika paket dihapus.

Untuk memeriksa filenya web.config.transform , unduh paket ELMAH dari tautan di atas, ubah ekstensi paket dari .nupkg ke .zip, lalu buka content\web.config.transform dalam file ZIP tersebut.

Untuk melihat efek menginstal dan menghapus instalasi paket, buat proyek ASP.NET baru di Visual Studio (templat berada di bawah Visual C# > Web dalam dialog Proyek Baru), dan pilih aplikasi ASP.NET kosong. Buka web.config untuk melihat status awalnya. Kemudian klik kanan proyek, pilih Kelola Paket NuGet, telusuri ELMAH di nuget.org, dan instal versi terbaru. Perhatikan semua perubahan pada web.config. Sekarang hapus instalan paket dan Anda akan melihat web.config kembali ke status sebelumnya.

Transformasi XDT

Catatan

Seperti disebutkan di bagian masalah kompatibilitas paket dari dokumen untuk bermigrasi dari packages.config ke PackageReference, transformasi XDT seperti yang dijelaskan di bawah ini hanya didukung oleh packages.config. Jika Anda menambahkan file di bawah ini ke paket Anda, konsumen yang PackageReference menggunakan paket Anda tidak akan menerapkan transformasi (lihat sampel ini untuk membuat transformasi XDT berfungsi).PackageReference

Anda dapat mengubah file konfigurasi menggunakan sintaks XDT. Anda juga dapat meminta NuGet mengganti token dengan properti proyek dengan menyertakan nama properti dalam $ pemisah (tidak peka huruf besar/kecil).

Misalnya, file berikut app.config.install.xdt akan menyisipkan appSettings elemen ke dalam app.config yang berisi FullPathnilai , , FileNamedan ActiveConfigurationSettings dari proyek:

<?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>

Untuk contoh lain, misalkan proyek awalnya berisi konten berikut di web.config:

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

Untuk menambahkan MyNuModule elemen ke bagian modules selama penginstalan paket, paket web.config.install.xdt akan berisi yang berikut ini:

<?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>

Setelah menginstal paket, web.config akan terlihat seperti ini:

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

Untuk menghapus hanya MyNuModule elemen selama penghapusan instalasi paket, web.config.uninstall.xdt file harus berisi yang berikut ini:

<?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