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

Transformace zdrojového kódu použije jednosměrnou náhradu tokenu u souborů ve složce content nebo contentFiles balíčku (content pro zákazníky, kteří používají packages.config a contentFiles pro PackageReference) při instalaci balíčku, přičemž tokeny odkazují na vlastnosti projektu sady Visual Studio. To vám umožní vložit soubor do názvového prostoru projektu, nebo upravit kód, který by obvykle patřil do global.asax v 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 nazvaný ContosoData.cs nacházel ve složce Models cílového projektu, musí být uvnitř složky content\Models a contentFiles\{lang}\{tfm}\Models v balíčku.
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$ s Fabrikam za předpokladu, že cílový projekt, jehož kořenový obor 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 pro vrácení změn, když je balíček odebrán z projektu.

Poznámka:

Transformace nejsou aplikovány na .config soubory odkazované jako odkazy v aplikaci „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.

XML transformace

Složky app.config.transform a web.config.transform ve složce content balíčku obsahují 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>

Když NuGet nainstaluje balíček, web.config 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 balíček moduly a obslužné rutiny protokolování chyb pro ASP.NET (ELMAH) přidává mnoho položek do web.config, které jsou při odinstalaci balíčku opět odebrány.

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 efekt instalace a odinstalace balíčku, vytvořte v sadě Visual Studio nový projekt ASP.NET (šablona je v dialogovém okně Nový projekt v rámci 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 myši 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. Nyní odinstalujte balíček a uvidíte, jak se web.config vrátí do svého předchozího 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 pouze packages.config. Pokud do balíčku přidáte následující soubory, nebudou mít transformace použité ti příjemci, kteří váš balíček používají s PackageReference (odkažte se na tuto ukázku, abyste zprovoznili transformace XDT s PackageReference).

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 FullPath, FileName, 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 během instalace balíčku přidat prvek MyNuModule do oddílu modules, web.config.install.xdt balíčku obsahuje 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>

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-10-31