Przekształcanie kodu źródłowego i plików konfiguracji

Transformacja kodu źródłowego stosuje jednokierunkowe zastąpienie tokenu do plików w folderze lub content pakiecie contentFiles (contentw przypadku klientów korzystających z programów packages.config i contentFilesPackageReference) podczas instalowania pakietu, gdzie tokeny odwołują się do właściwości projektu programu Visual Studio. Umożliwia to wstawienie pliku do przestrzeni nazw projektu lub dostosowanie kodu, który zazwyczaj znajdowałby się w oznaczeniu global.asax projektu ASP.NET.

Przekształcenie pliku konfiguracji umożliwia modyfikowanie plików, które już istnieją w projekcie docelowym, takich jak web.config i app.config. Na przykład pakiet może wymagać dodania elementu do modules sekcji w pliku konfiguracji. Ta transformacja jest wykonywana przez dołączenie plików specjalnych w pakiecie opisujących sekcje, które mają zostać dodane do plików konfiguracji. Po odinstalowaniu pakietu te same zmiany zostaną następnie odwrócone, co spowoduje przekształcenie dwukierunkowe.

Określanie przekształceń kodu źródłowego

Pliki, które chcesz wstawić z pakietu do projektu, muszą znajdować się w folderach content i contentFiles pakietu. Jeśli na przykład chcesz, aby plik o nazwie ContosoData.cs został zainstalowany w Models folderze projektu docelowego, musi znajdować się wewnątrz content\Models folderów i contentFiles\{lang}\{tfm}\Models w pakiecie.
Aby poinstruować nuGet o zastosowaniu zastąpienia tokenu w czasie instalacji, dołącz .pp do nazwy pliku kodu źródłowego. Po zakończeniu instalacji plik nie będzie miał .pp rozszerzenia.

Aby na przykład wykonać przekształcenia w pliku ContosoData.cs, nadaj plikowi nazwę w pakiecie ContosoData.cs.pp. Po zakończeniu instalacji będzie ona wyświetlana jako ContosoData.cs.
W pliku kodu źródłowego użyj tokenów bez uwzględniania wielkości liter w formularzu $token$ , aby wskazać wartości, które nuGet powinny zastąpić właściwościami projektu:
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Podczas instalacji program NuGet zastępuje $rootnamespace$ na Fabrikam, zakładając iż projekt docelowy, którego wiodąca przestrzeń nazw to Fabrikam.

Token $rootnamespace$ jest najczęściej używaną właściwością projektu; wszystkie inne są wymienione we właściwościach projektu. Należy pamiętać, że niektóre właściwości mogą być specyficzne dla typu projektu.

Określanie przekształceń plików konfiguracji

Zgodnie z opisem w poniższych sekcjach przekształcenia plików konfiguracji można wykonać na dwa sposoby:

Dołącz pliki app.config.transform i web.config.transform do folderu pakietu content, gdzie rozszerzenie .transform informuje NuGet, że te pliki zawierają kod XML do scalenia z istniejącymi plikami konfiguracji podczas instalowania pakietu. Po odinstalowaniu pakietu ten sam kod XML zostanie usunięty.
Uwzględnij pliki app.config.install.xdt i web.config.install.xdt w folderze pakietu content, używając składni XDT do opisania żądanych zmian. Za pomocą tej opcji można również uwzględnić .uninstall.xdt plik, aby odwrócić zmiany po usunięciu pakietu z projektu.

Uwaga / Notatka

Przekształcenia nie są stosowane do .config plików, do których prowadzi link w programie Visual Studio.

Zaletą korzystania z XDT jest to, że zamiast po prostu scalać dwa pliki statyczne, zapewnia składnię do manipulowania strukturą modelu DOM XML przez dopasowywanie elementów i atrybutów, korzystając z pełnej obsługi XPath. Następnie XDT może dodawać, aktualizować lub usuwać elementy, umieszczać nowe elementy w określonej lokalizacji lub zastępować/usuwać elementy (w tym węzły podrzędne). Dzięki temu można łatwo utworzyć transformacje dezinstalacyjne, które wycofają wszystkie transformacje wykonane podczas instalacji pakietu.

Przekształcenia XML

Folder content pakietu zawiera tylko te elementy w app.config.transform i web.config.transform, które mają zostać scalone z istniejącymi plikami app.config i web.config projektu.

Załóżmy na przykład, że projekt początkowo zawiera następującą zawartość w pliku web.config:

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

Aby dodać element MyNuModule do sekcji modules podczas instalacji pakietu, utwórz plik web.config.transform w folderze pakietu content, który wygląda następująco:

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

Po zainstalowaniu pakietu przez NuGet web.config pojawi się w następujący sposób:

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

Zwróć uwagę, że NuGet nie zastąpił sekcji modules, scalił natomiast nowy wpis do niej, dodając tylko nowe elementy i atrybuty. Program NuGet nie zmieni żadnych istniejących elementów ani atrybutów.

Po odinstalowaniu pakietu program NuGet ponownie zbada .transform pliki i usunie elementy, które zawiera z odpowiednich .config plików. Należy pamiętać, że ten proces nie będzie mieć wpływu na żadne wiersze w .config pliku, które są modyfikowane po instalacji pakietu.

Jako bardziej rozbudowany przykład, pakiet Error Logging Modules and Handlers for ASP.NET (ELMAH) dodaje wiele wpisów do web.config, które są usuwane po odinstalowaniu pakietu.

Aby sprawdzić jego web.config.transform plik, pobierz pakiet ELMAH z powyższego linku, zmień rozszerzenie pakietu z .nupkg na .zip, a następnie otwórz content\web.config.transform go w tym pliku ZIP.

Aby zobaczyć efekt instalowania i odinstalowywania pakietu, utwórz nowy projekt ASP.NET w programie Visual Studio (szablon znajduje się w obszarze Visual C# > Web w oknie dialogowym Nowy projekt) i wybierz pustą aplikację ASP.NET. Otwórz plik , web.config aby zobaczyć jego stan początkowy. Następnie kliknij prawym przyciskiem myszy projekt, wybierz pozycję Zarządzaj pakietami NuGet, wyszukaj pozycję ELMAH w nuget.org i zainstaluj najnowszą wersję. Zwróć uwagę na wszystkie zmiany w pliku web.config. Teraz odinstaluj pakiet, a web.config powróci do swojego poprzedniego stanu.

Przekształcenia XDT

Uwaga / Notatka

Jak wspomniano w sekcji Problemy ze zgodnością pakietów w dokumentacji dotyczącej migracji z packages.config do PackageReference, przekształcenia XDT zgodnie z poniższym opisem są obsługiwane tylko przez packages.confignarzędzie. W przypadku dodania poniższych plików do pakietu użytkownicy korzystający z pakietu z PackageReference nie będą mieli zastosowanych przekształceń. Zapoznaj się z tym przykładem, aby dowiedzieć się, jak przekształcenia XDT mogą działać z PackageReference.

Pliki konfiguracji można modyfikować przy użyciu składni XDT. Możesz również zastąpić tokeny właściwościami projektu, uwzględniając nazwę właściwości w ogranicznikach $ (bez uwzględniania wielkości liter).

Na przykład następujący plik app.config.install.xdt wstawi element appSettings do app.config, zawierającego wartości FullPath, FileName i ActiveConfigurationSettings z projektu:

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

W innym przykładzie załóżmy, że projekt początkowo zawiera następującą zawartość w pliku web.config:

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

Aby dodać MyNuModule element do modules sekcji podczas instalacji pakietu, pakiet web.config.install.xdt będzie zawierał następujące elementy:

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

Po zainstalowaniu pakietu web.config będzie wyglądać następująco:

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

Aby usunąć tylko MyNuModule element podczas odinstalowywania pakietu, web.config.uninstall.xdt plik powinien zawierać następujące elementy:

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

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2025-10-31