소스 코드 및 구성 파일 변환

아티클
08/10/2023

소스 코드 변환은 패키지를 설치할 때 단방향 토큰 교체를 패키지의 content 또는 contentFiles 폴더(packages.config를 사용하는 고객의 경우 content, PackageReference의 경우 contentFiles)에 있는 파일에 적용합니다. 여기서 토큰은 Visual Studio 프로젝트 속성을 참조합니다. 이렇게 하면 프로젝트의 네임스페이스에 파일을 삽입하거나 일반적으로 ASP.NET 프로젝트에서 global.asax로 이동하는 코드를 사용자 지정할 수 있습니다.

구성 파일 변환을 사용하면 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$ 토큰은 가장 일반적으로 사용되는 프로젝트 속성입니다. 다른 모든 토큰은 프로젝트 속성에 나열됩니다. 물론 일부 속성은 프로젝트 형식에 특정될 수 있습니다.

구성 파일 변환 지정

다음 섹션에서 설명한 대로 구성 파일 변환은 두 가지 방법으로 수행할 수 있습니다.

패키지의 content 폴더에 app.config.transform 및 web.config.transform 파일이 포함됩니다. 여기서 .transform 확장을 통해 NuGet이 이러한 파일에 XML을 포함하여 패키지를 설치할 때 기존 구성 파일과 병합하도록 지시합니다. 패키지를 제거하는 경우 동일한 XML이 제거됩니다.
패키지의 content 폴더에서 app.config.install.xdt 및 web.config.install.xdt 파일이 포함됩니다. XDT 구문을 사용하여 원하는 변경 내용을 설명합니다. 이 옵션에서 .uninstall.xdt 파일이 포함되어 패키지가 프로젝트에서 제거될 때 변경 내용을 되돌릴 수도 있습니다.

참고 항목

변환은 Visual Studio에서 링크로 참조되는 .config 파일에 적용되지 않습니다.

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 섹션에 추가하려면 다음과 같은 패키지의 content 폴더에서 web.config.transform 파일을 만듭니다.

<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으로 변경한 다음 해당 ZIP 파일에서 content\web.config.transform을 엽니다.

패키지를 설치 및 제거하는 영향을 보려면 Visual Studio에서 새 ASP.NET 프로젝트를 만들고(템플릿이 새 프로젝트 대화 상자의 Visual C# > 웹 아래에 있음), 빈 ASP.NET 애플리케이션을 선택합니다. web.config를 열어 초기 상태를 확인합니다. 그런 다음 프로젝트를 마우스 오른쪽 단추로 클릭하고, NuGet 패키지 관리를 선택하고, nuget.org에서 ELMAH를 찾고, 최신 버전을 설치합니다. web.config의 모든 변경 내용을 확인합니다. 이제 패키지를 제거하면 web.config가 이전 상태로 되돌아갑니다.

XDT 변환

참고 항목

packages.config에서 PackageReference로 마이그레이션하는 방법에 대한 문서의 패키지 호환성 이슈 섹션에 설명된 대로, 아래에서 설명하는 XDT 변환은 packages.config에서만 지원됩니다. 패키지에 아래 파일을 추가하는 경우 PackageReference와 함께 패키지를 사용하는 고객에 대해서는 변환이 적용되지 않습니다(PackageReference에서 XDT 변환을 사용하려면 이 샘플 참조).

XDT 구문을 사용하여 구성 파일을 수정할 수 있습니다. $ 구분 기호(대/소문자 구분) 내에서 속성 이름을 포함하여 NuGet에서 토큰을 프로젝트 속성으로 바꿀 수도 있습니다.

예를 들어 다음 app.config.install.xdt 파일은 프로젝트의 FullPath, FileName 및 ActiveConfigurationSettings 값을 포함하는 app.config에 appSettings 요소를 삽입합니다.

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

패키지를 설치하는 동안 modules 섹션에 MyNuModule 요소를 추가하기 위해 패키지의 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>

소스 코드 및 구성 파일 변환

소스 코드 변환 지정

구성 파일 변환 지정

XML 변환

XDT 변환

피드백

피드백

추가 리소스