소스 코드 및 구성 파일 변환

소스 코드 변환은 패키지의 content 또는 contentFiles 폴더(content 사용자의 packages.config 및 contentFiles 사용을 위한 PackageReference)에 있는 파일에 일방향 토큰 대체를 적용합니다. 여기서 토큰은 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은 Fabrikam를 루트 네임스페이스로 갖는 프로젝트를 대상으로 $rootnamespace$ 를 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를 사용하는 이점은 단순히 두 개의 정적 파일을 병합하는 대신 전체 XPath 지원을 사용하여 요소 및 특성 일치를 사용하여 XML DOM의 구조를 조작하는 구문을 제공한다는 것입니다. 그런 다음 XDT는 요소를 추가, 업데이트 또는 제거하거나, 특정 위치에 새 요소를 배치하거나, 요소(자식 노드 포함)를 대체/제거할 수 있습니다. 이렇게 하면 패키지 설치 중에 수행된 모든 변환을 백업하는 제거 변환을 쉽게 만들 수 있습니다.

XML 변환

app.config.transform web.config.transform 패키지의 content 폴더에는 프로젝트의 기존 app.config 파일과 web.config 파일에 병합할 요소만 포함됩니다.

예를 들어 프로젝트에 처음에 다음 콘텐츠가 포함되어 있다고 가정합니다.web.config

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

패키지 설치 중 modules 섹션에 MyNuModule 요소를 추가하려면, 패키지의 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 줄에 영향을 주지 않습니다.

보다 광범위한 예로 ELMAH(ASP.NET 용 오류 로깅 모듈 및 처리기) 패키지는 많은 항목을 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 변환

비고

마이그레이션용 에서 로의 문서 중 패키지 호환성 문제 섹션에서 언급했듯이, 아래에 설명된 XDT 변환은 에서만 지원됩니다. 패키지에 아래 파일을 추가하는 경우 패키지를 PackageReference 사용하는 소비자는 변환을 적용하지 않습니다(XDT 변환이 작동하도록 하려면 PackageReference 참조하세요).

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

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

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

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-10-31