Transformace zdrojového kódu a konfiguračních souborů

Článek
10/18/2023

Transformace zdrojového kódu použije jednosměrnou náhradu tokenu u souborů v balíčku content nebo contentFiles složce (contentpro zákazníky, kteří používají packages.config a contentFiles proPackageReference) při instalaci balíčku, kde tokeny odkazují na vlastnosti projektu sady Visual Studio. To vám umožní vložit soubor do oboru názvů projektu nebo přizpůsobit kód, který by obvykle přešel do global.asax projektu ASP.NET.

Transformace konfiguračního souboru umožňuje upravit soubory, které již existují v cílovém projektu, například web.config a app.config. Balíček může například potřebovat přidat položku do modules oddílu v konfiguračním souboru. Tato transformace se provádí zahrnutím speciálních souborů do balíčku, který popisuje oddíly, které se mají přidat do konfiguračních souborů. Když je balíček odinstalován, tyto stejné změny se pak vrátí zpět, takže se jedná o obousměrnou transformaci.

Určení transformací zdrojového kódu

Soubory, které chcete vložit z balíčku do projektu, musí být umístěny v rámci balíčků content a contentFiles složek. Pokud například chcete, aby se soubor volal ContosoData.cs do Models složky cílového projektu, musí být uvnitř content\Models balíčků a contentFiles\{lang}\{tfm}\Models složek.
Pokud chcete nuGet instruovat, aby při instalaci použil nahrazení tokenu, připojte .pp k názvu souboru zdrojového kódu. Po instalaci soubor nebude mít příponu .pp .

Chcete-li například provést transformace v ContosoData.cs, pojmenujte soubor v balíčku ContosoData.cs.pp. Po instalaci se zobrazí jako ContosoData.cs.
V souboru zdrojového kódu použijte tokeny bez rozlišování malých a velkých písmen formuláře $token$ k označení hodnot, které by NuGet měl nahradit vlastnostmi projektu:
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
Při instalaci nuGet nahradí $rootnamespace$ za předpokladu, že cílový projekt, jehož kořenovým oborem Fabrikam názvů je Fabrikam.

Token $rootnamespace$ je nejčastěji používaná vlastnost projektu. Všechny ostatní jsou uvedené ve vlastnostech projektu. Mějte na paměti, že některé vlastnosti můžou být specifické pro typ projektu.

Určení transformací konfiguračního souboru

Jak je popsáno v následujících částech, transformace konfiguračních souborů je možné provádět dvěma způsoby:

Zahrňte app.config.transform a web.config.transform soubory do složky balíčku content , kde .transform rozšíření říká NuGetu, že tyto soubory obsahují XML, aby se při instalaci balíčku sloučily s existujícími konfiguračními soubory. Při odinstalaci balíčku se odebere stejný KÓD XML.
Zahrňte app.config.install.xdt soubory do web.config.install.xdt složky balíčku content pomocí syntaxe XDT a popište požadované změny. Pomocí této možnosti můžete také zahrnout .uninstall.xdt soubor, který se má vrátit zpět, když je balíček odebrán z projektu.

Poznámka:

Transformace nejsou použity na .config soubory odkazované jako odkaz v sadě Visual Studio.

Výhodou použití XDT je, že místo pouhého sloučení dvou statických souborů poskytuje syntaxi pro manipulaci se strukturou XML DOM pomocí elementu a párování atributů pomocí úplné podpory XPath. XDT pak může přidat, aktualizovat nebo odebrat prvky, umístit nové prvky do konkrétního umístění nebo nahradit nebo odebrat prvky (včetně podřízených uzlů). To usnadňuje vytváření transformací odinstalace, které zálohují všechny transformace provedené během instalace balíčku.

Transformace XML

Složka app.config.transform balíčku content obsahuje web.config.transform pouze ty prvky, které se mají sloučit do existujících app.config a web.config souborů projektu.

Předpokládejme například, že projekt zpočátku obsahuje následující obsah:web.config

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

Pokud chcete přidat MyNuModule prvek do oddílu modules během instalace balíčku, vytvořte web.config.transform soubor ve složce balíčku content , který vypadá takto:

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

Po instalaci balíčku web.config NuGet se zobrazí takto:

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

Všimněte si, že NuGet nenahrazuje modules oddíl, pouze sloučil novou položku do ní přidáním pouze nových prvků a atributů. NuGet nezmění žádné existující prvky ani atributy.

Po odinstalaci balíčku NuGet znovu zkontroluje .transform soubory a odebere prvky, které obsahuje z příslušných .config souborů. Všimněte si, že tento proces nebude mít vliv na žádné řádky v .config souboru, který upravíte po instalaci balíčku.

Jako rozsáhlejší příklad přidává moduly a obslužné rutiny protokolování chyb pro balíček ASP.NET (ELMAH) mnoho položek web.config, které se znovu odeberou při odinstalaci balíčku.

Chcete-li prozkoumat jeho web.config.transform soubor, stáhněte balíček ELMAH z výše uvedeného odkazu, změňte příponu balíčku z .nupkg na .zipa pak otevřete content\web.config.transform v daném souboru ZIP.

Pokud chcete zobrazit účinek instalace a odinstalace balíčku, vytvořte nový projekt ASP.NET v sadě Visual Studio (šablona je v dialogovém okně Nový projekt v části Visual C# > Web ) a vyberte prázdnou aplikaci ASP.NET. Otevřete web.config , abyste viděli jeho počáteční stav. Pak klikněte pravým tlačítkem na projekt, vyberte Spravovat balíčky NuGet, vyhledejte ELMAH na nuget.org a nainstalujte nejnovější verzi. Všimněte si všech změn v souboru web.config. Teď balíček odinstalujte a uvidíte web.config návrat k předchozímu stavu.

Transformace XDT

Poznámka:

Jak je uvedeno v části Problémy s kompatibilitou balíčků dokumentace pro migraci z packages.config do PackageReference, transformace XDT, jak je popsáno níže, jsou podporovány packages.configpouze . Pokud do balíčku přidáte následující soubory, příjemci, kteří váš balíček používají, PackageReference nebudou mít použité transformace (pokud chcete, aby transformace XDT fungovaly vPackageReference této ukázce).

Konfigurační soubory můžete upravit pomocí syntaxe XDT. Tokeny NuGet můžete také nahradit vlastnostmi projektu zahrnutím názvu vlastnosti v rámci $ oddělovačů (nerozlišují se malá a velká písmena).

Například následující app.config.install.xdt soubor vloží appSettings prvek do app.config obsahujícího FileNameFullPath, a ActiveConfigurationSettings hodnoty 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>

Předpokládejme například, že projekt zpočátku obsahuje následující obsah:web.config

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

Pokud chcete přidat MyNuModule prvek do oddílu modules během instalace balíčku, web.config.install.xdt balíček bude obsahovat následující:

<?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 instalaci balíčku web.config bude vypadat takto:

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

Chcete-li odebrat pouze MyNuModule prvek během odinstalace balíčku, web.config.uninstall.xdt soubor by měl obsahovat následující:

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