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

Artykuł
10/18/2023

Transformacja kodu źródłowego stosuje jednokierunkowe zastąpienie tokenu do plików w folderze lub contentFiles pakiecie content (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. Dzięki temu można wstawić plik do przestrzeni nazw projektu lub dostosować kod, który zazwyczaj przechodzi do 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 i contentFiles pakietachcontent. 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$ Fabrikam element przy założeniu, że projekt docelowy, którego główna 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 app.config.transform pliki i web.config.transform do folderu pakietu content , w którym .transform rozszerzenie 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.
Dołącz app.config.install.xdt pliki i web.config.install.xdt do folderu 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

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

Zaletą korzystania z XDT jest to, że zamiast po prostu scalać dwa pliki statyczne, zapewnia składnię manipulowania strukturą modelu DOM XML przy użyciu elementu i dopasowywania atrybutów przy użyciu 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ć przekształcenia dezinstalacji, które wycofają wszystkie przekształcenia wykonywane podczas instalacji pakietu.

Przekształcenia XML

Folder app.config.transform i web.config.transform w folderze pakietu content zawiera tylko te elementy do scalenia z istniejącymi app.config plikami 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ć MyNuModule element do modules sekcji podczas instalacji pakietu, utwórz web.config.transform plik 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 web.config NuGet zostanie wyświetlony 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 pakiet NuGet nie zastąpił modules sekcji, właśnie scalił nowy wpis, 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.

W bardziej rozbudowanym przykładzie moduły rejestrowania błędów i programy obsługi dla pakietu ASP.NET (ELMAH) dodaje wiele wpisów do web.configprogramu , które są ponownie 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 Sieć Web programu Visual C# > 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 i zobaczysz web.config jego przywrócenie poprzedniego stanu.

Przekształcenia XDT

Uwaga

Jak wspomniano w sekcji problemy ze zgodnością pakietów w dokumentacji dotyczącej migracji z packages.config do PackageReferencesystemu , przekształcenia XDT zgodnie z poniższym opisem są obsługiwane tylko przez packages.configprogram . W przypadku dodania poniższych plików do pakietu użytkownicy korzystający z PackageReference pakietu nie będą mieli zastosowanych przekształceń (zapoznaj się z tym przykładem , aby przekształcenia XDT działały zPackageReference).

Pliki konfiguracji można modyfikować przy użyciu składni XDT. Możesz również zastąpić tokeny tokenami 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 app.config.install.xdt plik wstawi element appSettings do app.config elementu zawierającego FullPathwartości , FileNamei 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>