Mengubah kode sumber dan file konfigurasi

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 proyek, atau untuk menyesuaikan kode yang biasanya dimasukkan 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.

Nota

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 pencopotan pemasangan yang mengembalikan semua transformasi yang dilakukan selama penginstalan paket.

Proses Transformasi XML

app.config.transform dan web.config.transform dalam folder content paket hanya berisi elemen-elemen yang perlu digabungkan ke dalam file app.config dan web.config proyek yang sudah ada.

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, paket Modul pengelogan kesalahan dan Handler untuk ASP.NET (ELMAH) menambahkan banyak entri ke dalam web.config, yang lagi-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

Nota

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 menggunakan paket Anda dengan PackageReference tidak akan mendapatkan transformasi yang diterapkan (lihat sampel ini untuk membuat transformasi XDT berfungsi dengan PackageReference).

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

Misalnya, file berikut app.config.install.xdt akan menyisipkan elemen appSettings ke dalam app.config yang berisi nilai FullPath, FileName, dan 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>

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-10-31