Преобразование исходного кода и файлов конфигурации

Преобразование исходного кода выполняет одностороннюю замену маркеров в файлах, находящихся в папке content или contentFiles пакета (content для клиентов, использующих packages.config и contentFiles для PackageReference), при установке пакета, где маркеры относятся к свойствам проекта в Visual Studio. Это позволяет вставить файл в пространство имен проекта, или настроить код, который обычно помещается в элемент global.asax проекта ASP.NET.

Преобразование файла конфигурации позволяет изменять файлы, которые уже существуют в целевом проекте, например web.config и app.config. Например, вам может потребоваться, чтобы пакет добавил элемент modules в раздел в файле конфигурации. Это преобразование выполняется путем включения специальных файлов в пакет, описывающих разделы для добавления в файлы конфигурации. При удалении пакета эти же изменения будут отменены, что делает это двустороннее преобразование.

Указание преобразований исходного кода

Файлы, которые необходимо вставить из пакета в проект, должны находиться в пределах пакета content и contentFiles папок. Например, если требуется установить файл ContosoData.cs в Models папке целевого проекта, он должен находиться в content\Models пакете и contentFiles\{lang}\{tfm}\Models папках.
Чтобы указать NuGet применить замену маркера во время установки, добавьте .pp к имени файла исходного кода. После установки файл не будет иметь .pp расширения.

Например, чтобы сделать преобразования в ContosoData.cs, присвойте файлу в пакете ContosoData.cs.ppимя. После установки он будет отображаться как ContosoData.cs.
В файле исходного кода используйте маркеры без учета регистра формы $token$ , чтобы указать значения, которые NuGet следует заменить свойствами проекта:
```
namespace $rootnamespace$.Models
{
    public struct CategoryInfo
    {
        public string categoryid;
        public string description;
        public string htmlUrl;
        public string rssUrl;
        public string title;
    }
}
```
После установки NuGet заменяет $rootnamespace$ на Fabrikam, если целевой проект имеет корневое пространство имен Fabrikam.

Маркер $rootnamespace$ является наиболее часто используемым свойством проекта; все остальные перечислены в свойствах проекта. Помните, конечно, что некоторые свойства могут быть характерными для типа проекта.

Указание преобразований файлов конфигурации

Как описано в следующих разделах, преобразования файлов конфигурации можно выполнить двумя способами:

Включите app.config.transform и web.config.transform файлы в папку пакета content , где .transform расширение сообщает NuGet, что эти файлы содержат XML для слияния с существующими файлами конфигурации при установке пакета. При удалении пакета этот же XML удаляется.
Включите app.config.install.xdt и web.config.install.xdt файлы в папку пакета content , используя синтаксис XDT для описания требуемых изменений. С помощью этого параметра можно также включить .uninstall.xdt файл для отмены изменений при удалении пакета из проекта.

Замечание

Преобразования не применяются к .config файлам, на которые ссылается ссылка в Visual Studio.

Преимущество использования XDT заключается в том, что вместо простого объединения двух статических файлов он предоставляет синтаксис для управления структурой XML-DOM с помощью элемента и сопоставления атрибутов с помощью полной поддержки XPath. Затем XDT может добавлять, обновлять или удалять элементы, размещать новые элементы в определенном расположении или заменять или удалять элементы (включая дочерние узлы). Это упрощает создание преобразований удаления, которые возвращают все преобразования, выполненные во время установки пакета.

Преобразования XML

В папке content пакета содержатся app.config.transform и web.config.transform, которые включают только те элементы, которые необходимо объединить в уже существующие файлы проекта app.config и web.config.

Например, предположим, что проект изначально содержит следующее содержимое:web.config

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

Чтобы добавить MyNuModule элемент в modules раздел при установке пакета, создайте web.config.transform файл в папке пакета content, который выглядит следующим образом:

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

После установки пакета NuGet, web.config будет отображаться следующим образом:

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

Обратите внимание, что NuGet не заменил раздел modules , он просто объединил новую запись в нее, добавив только новые элементы и атрибуты. NuGet не изменит существующие элементы или атрибуты.

При удалении пакета NuGet снова проверяет .transform файлы и удаляет элементы, содержащиеся в соответствующих .config файлах. Обратите внимание, что этот процесс не повлияет на строки в .config файле, который вы изменяете после установки пакета.

В качестве более развернутого примера, пакет модулей и обработчиков ведения журнала ошибок для ASP.NET (ELMAH) добавляет множество записей в web.config, которые снова удаляются при удалении пакета.

Чтобы проверить его web.config.transform файл, скачайте пакет ELMAH из приведённой выше ссылки, измените расширение пакета на .nupkg.zip, а затем откройте content\web.config.transform в этом ZIP-файле.

Чтобы увидеть эффект установки и удаления пакета, создайте новый проект ASP.NET в Visual Studio (шаблон находится в разделе Visual C# > Web в диалоговом окне создания проекта) и выберите пустое приложение ASP.NET. Откройте web.config , чтобы увидеть начальное состояние. Затем щелкните проект правой кнопкой мыши, выберите "Управление пакетами NuGet", найдите ELMAH в nuget.org и установите последнюю версию. Обратите внимание на все изменения web.config. Теперь удалите пакет, и web.config вернется к предыдущему состоянию.

Преобразования XDT

Замечание

Как упоминалось в разделе о проблемах совместимости пакетов документации по миграции с packages.config на PackageReference, преобразования XDT, как описано ниже, поддерживаются только packages.config. При добавлении приведенных ниже файлов в ваш пакет, потребители, которые используют ваш пакет с PackageReference, не будут иметь преобразования, примененные (см. этот пример, чтобы сделать преобразования XDT работающими с PackageReference).

Файлы конфигурации можно изменить с помощью синтаксиса XDT. Кроме того, можно заменить маркеры NuGet свойствами проекта , включив имя свойства в $ разделители (без учета регистра).

Например, следующий app.config.install.xdt файл вставит appSettings элемент в app.config, содержащий FullPath, FileName, и ActiveConfigurationSettings значения из проекта:

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

Например, предположим, что проект изначально содержит следующее содержимое:web.config

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

Чтобы добавить MyNuModule элемент в modules раздел во время установки пакета, пакет web.config.install.xdt будет содержать следующее:

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

После установки пакета web.config будет выглядеть следующим образом:

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

Чтобы удалить только MyNuModule элемент во время удаления пакета, web.config.uninstall.xdt файл должен содержать следующее:

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

Обратная связь

Была ли эта страница полезна?

Last updated on 2025-10-31