MSBuild 항목MSBuild Items

MSBuild 항목은 빌드 시스템에 대한 입력이며, 일반적으로 파일을 나타냅니다.MSBuild items are inputs into the build system, and they typically represent files. 항목은 해당 요소 이름에 따라 항목 종류로 그룹화됩니다.Items are grouped into item types based on their element names. 항목 종류는 작업의 매개 변수로 사용할 수 있는 명명된 항목 목록입니다.Item types are named lists of items that can be used as parameters for tasks. 작업은 항목 값을 사용하여 빌드 프로세스의 단계를 수행합니다.The tasks use the item values to perform the steps of the build process.

항목은 속하는 항목 종류를 기준으로 이름이 지정되므로 "항목"과 "항목 값"이라는 용어는 동일한 의미로 사용할 수 있습니다.Because items are named by the item type to which they belong, the terms "item" and "item value" can be used interchangeably.

항목 내용In this topic

프로젝트 파일에 항목 만들기Creating Items in a Project File

프로젝트 파일에서 ItemGroup 요소의 자식 요소로 항목을 선언합니다.You declare items in the project file as child elements of an ItemGroup element. 자식 요소의 이름은 항목의 종류입니다.The name of the child element is the type of the item. 요소의 Include 특성은 해당 항목 종류에 포함할 항목(파일)을 지정합니다.The Include attribute of the element specifies the items (files) to be included with that item type. 예를 들어 다음 XML은 두 개의 파일을 포함하는 Compile이라는 항목 종류를 만듭니다.For example, the following XML creates an item type that's named Compile, which includes two files.

<ItemGroup>  
    <Compile Include = "file1.cs"/>  
    <Compile Include = "file2.cs"/>  
</ItemGroup>  

“file1.cs” 항목이 “file2.cs” 항목으로 바뀌지는 않으며, 대신 Compile 항목 종류의 값 목록에 파일 이름이 추가됩니다.The item "file2.cs" doesn't replace the item "file1.cs"; instead, the file name is appended to the list of values for the Compile item type. 빌드의 평가 단계 중에는 항목 종류에서 항목을 제거할 수 없습니다.You can't remove an item from an item type during the evaluation phase of a build.

다음 XML은 Include 특성 하나에서 두 파일을 모두 선언하여 같은 항목 종류를 만듭니다.The following XML creates the same item type by declaring both files in one Include attribute. 파일 이름은 세미콜론으로 구분됩니다.Notice that the file names are separated by a semicolon.

<ItemGroup>  
    <Compile Include = "file1.cs;file2.cs"/>  
</ItemGroup>  

실행 중에 항목 만들기Creating Items During Execution

Target 요소 외부에 있는 항목의 경우 빌드의 평가 단계에서 값이 할당됩니다.Items that are outside Target elements are assigned values during the evaluation phase of a build. 후속 실행 단계 중에 다음과 같은 방식으로 항목을 만들거나 수정할 수 있습니다.During the subsequent execution phase, items can be created or modified in the following ways:

  • 모든 작업이 항목을 내보낼 수 있습니다.Any task can emit an item. 항목을 내보내려면 Task 요소에 ItemName 특성이 포함된 자식 Output 요소가 있어야 합니다.To emit an item, the Task element must have a child Output element that has an ItemName attribute.

  • CreateItem 작업이 항목을 내보낼 수 있습니다.The CreateItem task can emit an item. 이러한 사용법은 더 이상 사용되지 않습니다.This usage is deprecated.

  • .NET Framework 3.5부터는 Target 요소가 항목 요소가 들어 있을 수 있는 ItemGroup 요소를 포함할 수 있습니다.Starting in the .NET Framework 3.5, Target elements may contain ItemGroup elements that may contain item elements.

프로젝트 파일의 항목 참조Referencing Items in a Project File

프로젝트 파일 전체에서 항목 종류를 참조하려면 (ItemType) 구문을 사용합니다.To reference item types throughout the project file, you use the syntax @(ItemType). 예를 들어 @(Compile)을 사용하여 이전 예제의 항목 종류를 참조합니다.For example, you would reference the item type in the previous example by using @(Compile). 이 구문을 사용하면 항목 종류를 작업의 매개 변수로 지정하여 해당 작업에 항목을 전달할 수 있습니다.By using this syntax, you can pass items to tasks by specifying the item type as a parameter of that task. 자세한 내용은 방법: 빌드할 파일 선택을 참조하세요.For more information, see How to: Select the Files to Build.

기본적으로 항목 종류를 확장하면 해당 항목이 세미콜론(;)으로 구분됩니다.By default, the items of an item type are separated by semicolons (;) when it's expanded. @(ItemType, 'separator') 구문을 사용하면 기본값이 아닌 구분 기호를 지정할 수 있습니다.You can use the syntax @(ItemType, 'separator') to specify a separator other than the default. 자세한 내용은 방법: 항목 목록을 쉼표로 구분하여 표시를 참조하세요.For more information, see How to: Display an Item List Separated with Commas.

와일드카드를 사용하여 항목 지정Using Wildcards to Specify Items

**, * 및 ?You can use the **, *, and ? 와일드카드 문자를 사용하여 각 파일을 개별적으로 나열하는 대신 파일 그룹을 빌드의 입력으로 지정할 수 있습니다.wildcard characters to specify a group of files as inputs for a build instead of listing each file separately.

  • ?The ? 와일드카드 문자는 단일 문자를 찾습니다.wildcard character matches a single character.

  • * 와일드카드 문자는 0개 이상의 문자를 찾습니다.The * wildcard character matches zero or more characters.

  • ** 와일드카드 문자 시퀀스는 부분 경로를 찾습니다.The ** wildcard character sequence matches a partial path.

    예를 들어 프로젝트 파일에서 다음 요소를 사용하여 프로젝트 파일이 포함된 디렉터리의 모든 .cs 파일을 지정할 수 있습니다.For example, you can specify all the .cs files in the directory that contains the project file by using the following element in your project file.

<CSFile Include="*.cs"/>  

다음 요소는 D: 드라이브에 있는 모든 .vb 파일을 선택합니다.The following element selects all .vb files on the D: drive:

<VBFile Include="D:/**/*.vb"/>  

와일드카드 문자에 대한 자세한 내용은 방법: 빌드할 파일 선택을 참조하세요.For more information about wildcard characters, see How to: Select the Files to Build.

Exclude 특성 사용Using the Exclude Attribute

Item 요소는 Exclude 특성을 포함할 수 있습니다. 이 특성은 항목 종류에서 특정 항목(파일)을 제외합니다.Item elements can contain the Exclude attribute, which excludes specific items (files) from the item type. Exclude 특성은 일반적으로 와일드카드 문자와 함께 사용됩니다.The Exclude attribute is typically used together with wildcard characters. 예를 들어 다음 XML은 DoNotBuild.cs 파일을 제외한 디렉터리의 모든 .cs 파일을 CSFile 항목 종류에 추가합니다.For example, the following XML adds every .cs file in the directory to the CSFile item type, except the DoNotBuild.cs file.

<ItemGroup>  
    <CSFile  Include="*.cs"  Exclude="DoNotBuild.cs"/>  
</ItemGroup>  

Exclude 특성은 Include 특성에 의해 추가된 항목에만 영향을 줍니다(이 두 특성이 모두 포함된 항목 요소에서).The Exclude attribute affects only the items that are added by the Include attribute in the item element that contains them both. 다음 예제에서는 이전 항목 요소에서 추가된 Form1.cs 파일을 제외하지 않습니다.The following example wouldn't exclude the file Form1.cs, which was added in the preceding item element.

<Compile Include="*.cs" />  
<Compile Include="*.res" Exclude="Form1.cs">  

자세한 내용은 방법: 빌드에서 파일 제외를 참조하세요.For more information, see How to: Exclude Files from the Build.

항목 메타데이터Item Metadata

항목은 IncludeExclude 특성의 정보 이외에 메타데이터를 포함할 수 있습니다.Items may contain metadata in addition to the information in the Include and Exclude attributes. 이 메타데이터는 항목에 대한 추가 정보를 필요로 하는 작업이나 일괄 처리 작업 및 대상에 사용할 수 있습니다.This metadata can be used by tasks that require more information about the items or to batch tasks and targets. 자세한 내용은 일괄 처리를 참조하세요.For more information, see Batching.

메타데이터는 프로젝트 파일에서 항목 요소의 자식 요소로 선언된 키/값 쌍의 컬렉션입니다.Metadata is a collection of key-value pairs that are declared in the project file as child elements of an item element. 자식 요소의 이름은 메타데이터의 이름이고 자식 요소의 값은 메타데이터의 값입니다.The name of the child element is the name of the metadata, and the value of the child element is the value of the metadata.

메타데이터는 포함되어 있는 항목 요소와 연결됩니다.The metadata is associated with the item element that contains it. 예를 들어 다음 XML은 값 Fr이 포함된 Culture 메타데이터를 CSFile 항목 종류의 "one.cs" 및 "two.cs" 항목에 모두 추가합니다.For example, the following XML adds Culture metadata that has the value Fr to both the "one.cs" and the "two.cs" items of the CSFile item type.

<ItemGroup>  
    <CSFile Include="one.cs;two.cs">  
        <Culture>Fr</Culture>  
    </CSFile>  
</ItemGroup>  

항목은 메타데이터 값을 포함하지 않을 수도 있고 하나 이상 포함할 수도 있습니다.An item can have zero or more metadata values. 언제든지 메타데이터 값을 변경할 수 있습니다.You can change metadata values at any time. 메타데이터를 빈 값으로 설정하면 실제로는 빌드에서 메타데이터가 제거됩니다.If you set metadata to an empty value, you effectively remove it from the build.

프로젝트 파일에서 항목 메타데이터 참조Referencing Item Metadata in a Project File

프로젝트 파일 전체에서 %(ItemMetadataName) 구문을 사용하여 항목형 메타데이터를 참조할 수 있습니다.You can reference item metadata throughout the project file by using the syntax %(ItemMetadataName). 메타데이터가 명확하지 않은 경우에는 항목 종류의 이름을 사용하여 참조를 한정할 수 있습니다.If ambiguity exists, you can qualify a reference by using the name of the item type. 예를 들어 %(ItemType.ItemMetaDataName)을 지정할 수 있습니다. 다음 예에서는 Display 메타데이터를 사용하여 Message 작업을 일괄 처리합니다.For example, you can specify %(ItemType.ItemMetaDataName).The following example uses the Display metadata to batch the Message task. 일괄 처리에 항목 메타데이터를 사용하는 방법에 대한 자세한 내용은 작업 일괄 처리의 항목 메타데이터를 참조하세요.For more information about how to use item metadata for batching, see Item Metadata in Task Batching.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  
    <ItemGroup>  
        <Stuff Include="One.cs" >  
            <Display>false</Display>  
        </Stuff>  
        <Stuff Include="Two.cs">  
            <Display>true</Display>  
        </Stuff>  
    </ItemGroup>  
    <Target Name="Batching">  
        <Message Text="@(Stuff)" Condition=" '%(Display)' == 'true' "/>  
    </Target>  
</Project>  

잘 알려진 항목 메타데이터Well-known Item Metadata

항목 종류에 항목을 추가하면 해당 항목에는 몇 가지 잘 알려진 메타데이터가 할당됩니다.When an item is added to an item type, that item is assigned some well-known metadata. 예를 들어 모든 항목에는 잘 알려진 메타데이터 %(Filename)이 포함되며, 이 메타데이터의 값은 항목의 파일 이름입니다.For example, all items have the well-known metadata %(Filename), whose value is the file name of the item. 자세한 내용은 잘 알려진 항목 메타데이터를 참조하세요.For more information, see Well-known Item Metadata.

메타데이터를 사용하여 항목 종류 변환Transforming Item Types By Using Metadata

메타데이터를 사용하여 항목 목록을 새 항목 목록으로 변환할 수 있습니다.You can transform item lists into new item lists by using metadata. 예를 들어 @(CppFiles -> '%(Filename).obj') 식을 사용하면 .cpp 파일을 나타내는 항목이 포함된 항목 종류 CppFiles를 해당하는 .obj 파일 목록으로 변환할 수 있습니다.For example, you can transform an item type CppFiles that has items that represent .cpp files into a corresponding list of .obj files by using the expression @(CppFiles -> '%(Filename).obj').

다음 코드는 Culture 메타데이터가 있는 모든 EmbeddedResource 항목의 복사본이 포함된 CultureResource 항목 종류를 만듭니다.The following code creates a CultureResource item type that contains copies of all EmbeddedResource items with Culture metadata. Culture 메타데이터 값이 새 메타데이터 CultureResource.TargetDirectory의 값이 됩니다.The Culture metadata value becomes the value of the new metadata CultureResource.TargetDirectory.

<Target Name="ProcessCultureResources">  
    <ItemGroup>  
        <CultureResource Include="@(EmbeddedResource)"  
            Condition="'%(EmbeddedResource.Culture)' != ''">  
            <TargetDirectory>%(EmbeddedResource.Culture) </TargetDirectory>  
        </CultureResource>  
    </ItemGroup>  
</Target>  

자세한 내용은 변환을 참조하세요.For more information, see Transforms.

항목 정의Item Definitions

.NET Framework 3.5부터는 ItemDefinitionGroup 요소를 사용하여 모든 항목 종류에 기본 메타데이터를 추가할 수 있습니다.Starting in the .NET Framework 3.5, you can add default metadata to any item type by using the ItemDefinitionGroup element. 잘 알려진 메타데이터와 마찬가지로 기본 메타데이터는 지정한 항목 종류의 모든 항목과 연결됩니다.Like well-known metadata, the default metadata is associated with all items of the item type that you specify. 항목 정의에서 기본 메타데이터를 명시적으로 재정의할 수 있습니다.You can explicitly override default metadata in an item definition. 예를 들어 다음 XML은 Compile 항목 "one.cs" 및 "three.cs"에 값이 "Monday"인 메타데이터 BuildDay를 제공합니다.For example, the following XML gives the Compile items "one.cs" and "three.cs" the metadata BuildDay with the value "Monday". 이 코드는 "two.cs" 항목에는 값이 "Tuesday"인 메타데이터 BuildDay를 제공합니다.The code gives the item "two.cs" the metadata BuildDay with the value "Tuesday".

<ItemDefinitionGroup>  
    <Compile>  
        <BuildDay>Monday</BuildDay>  
    </Compile>  
</ItemDefinitionGroup>  
<ItemGroup>  
    <Compile Include="one.cs;three.cs" />  
    <Compile Include="two.cs">  
        <BuildDay>Tuesday</BuildDay>  
    </Compile>  
</ItemGroup>  

자세한 내용은 항목 정의를 참조하세요.For more information, see Item Definitions.

대상의 ItemGroup에 있는 항목에 대한 특성Attributes for Items in an ItemGroup of a Target

.NET Framework 3.5부터는 Target 요소가 항목 요소가 들어 있을 수 있는 ItemGroup 요소를 포함할 수 있습니다.Starting in the .NET Framework 3.5, Target elements may contain ItemGroup elements that may contain item elements. 이 섹션의 특성은 Target에 있는 ItemGroup에서 항목에 대해 지정되는 경우 유효합니다.The attributes in this section are valid when they are specified for an item in an ItemGroup that's in a Target.

특성 제거Remove Attribute

대상의 ItemGroup에 있는 항목은 Remove 특성을 포함할 수 있습니다. 이 특성은 항목 종류에서 특정 항목(파일)을 제거합니다.Items in an ItemGroup of a target may contain the Remove attribute, which removes specific items (files) from the item type. 이 특성은 .NET Framework 3.5에서 도입되었습니다.This attribute was introduced in the .NET Framework 3.5.

다음 예제에서는 Compile 항목 종류에서 모든.config 파일을 제거합니다.The following example removes every .config file from the Compile item type.

<Target>  
    <ItemGroup>  
        <Compile Remove="*.config"/>  
    </ItemGroup>  
</Target>  

KeepMetadata 특성KeepMetadata Attribute

대상 내에서 항목이 생성되는 경우 항목 요소는 KeepMetadata 특성을 포함할 수 있습니다.If an item is generated within a target, the item element can contain the KeepMetadata attribute. 이 특성을 지정하면 세미콜론으로 구분된 이름 목록에 지정되어 있는 메타데이터만 소스 항목에서 대상 항목으로 전송됩니다.If this attribute is specified, only the metadata that is specified in the semicolon-delimited list of names will be transferred from the source item to the target item. 이 특성에 빈 값을 지정하는 것은 특성을 지정하지 않는 것과 같습니다.An empty value for this attribute is equivalent to not specifying it. KeepMetadata 특성은 .NET Framework 4.5에서 도입되었습니다.The KeepMetadata attribute was introduced in the .NET Framework 4.5.

다음 예제에서는 KeepMetadata 특성을 사용하는 방법을 보여 줍니다.The following example illustrates how to use the KeepMetadata attribute.

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003"  
ToolsVersion="4.0">  

    <ItemGroup>  
        <FirstItem Include="rhinoceros">  
            <Class>mammal</Class>  
            <Size>large</Size>  
        </FirstItem>  

    </ItemGroup>  
    <Target Name="MyTarget">  
        <ItemGroup>  
            <SecondItem Include="@(FirstItem)" KeepMetadata="Class" />  
        </ItemGroup>  

        <Message Text="FirstItem: %(FirstItem.Identity)" />  
        <Message Text="  Class: %(FirstItem.Class)" />  
        <Message Text="  Size:  %(FirstItem.Size)"  />  

        <Message Text="SecondItem: %(SecondItem.Identity)" />  
        <Message Text="  Class: %(SecondItem.Class)" />  
        <Message Text="  Size:  %(SecondItem.Size)"  />  
    </Target>  
</Project>  

<!--  
Output:  
  FirstItem: rhinoceros  
    Class: mammal  
    Size:  large  
  SecondItem: rhinoceros  
    Class: mammal  
    Size:   
-->  

RemoveMetadata 특성RemoveMetadata Attribute

대상 내에서 항목이 생성되는 경우 항목 요소는 RemoveMetadata 특성을 포함할 수 있습니다.If an item is generated within a target, the item element can contain the RemoveMetadata attribute. 이 특성을 지정하면 이름이 세미콜론으로 구분된 이름 목록에 포함되어 있는 메타데이터를 제외한 모든 메타데이터가 소스 항목에서 대상 항목으로 전송됩니다.If this attribute is specified, all metadata is transferred from the source item to the target item except metadata whose names are contained in the semicolon-delimited list of names. 이 특성에 빈 값을 지정하는 것은 특성을 지정하지 않는 것과 같습니다.An empty value for this attribute is equivalent to not specifying it. RemoveMetadata 특성은 .NET Framework 4.5에서 도입되었습니다.The RemoveMetadata attribute was introduced in the .NET Framework 4.5.

다음 예제에서는 RemoveMetadata 특성을 사용하는 방법을 보여 줍니다.The following example illustrates how to use the RemoveMetadata attribute.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  

    <PropertyGroup>  
        <MetadataToRemove>Size;Material</MetadataToRemove>  
    </PropertyGroup>  

    <ItemGroup>  
        <Item1 Include="stapler">  
            <Size>medium</Size>  
            <Color>black</Color>  
            <Material>plastic</Material>  
        </Item1>  
    </ItemGroup>  

    <Target Name="MyTarget">  
        <ItemGroup>  
            <Item2 Include="@(Item1)" RemoveMetadata="$(MetadataToRemove)" />  
        </ItemGroup>  

        <Message Text="Item1: %(Item1.Identity)" />  
        <Message Text="  Size:     %(Item1.Size)" />  
        <Message Text="  Color:    %(Item1.Color)" />  
        <Message Text="  Material: %(Item1.Material)" />  
        <Message Text="Item2: %(Item2.Identity)" />  
        <Message Text="  Size:     %(Item2.Size)" />  
        <Message Text="  Color:    %(Item2.Color)" />  
        <Message Text="  Material: %(Item2.Material)" />  
    </Target>  
</Project>  

<!--  
Output:   
  Item1: stapler  
    Size:     medium  
    Color:    black  
    Material: plastic  
  Item2: stapler  
    Size:       
    Color:    black  
    Material:   
-->  

KeepDuplicates 특성KeepDuplicates Attribute

대상 내에서 항목이 생성되는 경우 항목 요소는 KeepDuplicates 특성을 포함할 수 있습니다.If an item is generated within a target, the item element can contain the KeepDuplicates attribute. KeepDuplicates는 항목이 기존 항목의 정확한 복제본인 경우 대상 그룹에 해당 항목을 추가할지를 지정하는 Boolean 특성입니다.KeepDuplicates is a Boolean attribute that specifies whether an item should be added to the target group if the item is an exact duplicate of an existing item.

소스 항목과 대상 항목의 Include 값은 같고 메타데이터는 다르면 KeepDuplicatesfalse로 설정되어 있어도 항목이 추가됩니다.If the source and target item have the same Include value but different metadata, the item is added even if KeepDuplicates is set to false. 이 특성에 빈 값을 지정하는 것은 특성을 지정하지 않는 것과 같습니다.An empty value for this attribute is equivalent to not specifying it. KeepDuplicates 특성은 .NET Framework 4.5에서 도입되었습니다.The KeepDuplicates attribute was introduced in the .NET Framework 4.5.

다음 예제에서는 KeepDuplicates 특성을 사용하는 방법을 보여 줍니다.The following example illustrates how to use the KeepDuplicates attribute.

<Project ToolsVersion="4.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">  

    <ItemGroup>  
        <Item1 Include="hourglass;boomerang" />  
        <Item2 Include="hourglass;boomerang" />  
    </ItemGroup>  

    <Target Name="MyTarget">  
        <ItemGroup>  
            <Item1 Include="hourglass" KeepDuplicates="false" />  
            <Item2 Include="hourglass" />  
        </ItemGroup>  

        <Message Text="Item1: @(Item1)" />  
        <Message Text="  %(Item1.Identity)  Count: @(Item1->Count())" />  
        <Message Text="Item2: @(Item2)" />  
        <Message Text="  %(Item2.Identity)  Count: @(Item2->Count())" />  
    </Target>  
</Project>  

<!--  
Output:   
  Item1: hourglass;boomerang  
    hourglass  Count: 1  
    boomerang  Count: 1  
  Item2: hourglass;boomerang;hourglass  
    hourglass  Count: 2  
    boomerang  Count: 1  
-->  

참고 항목See Also

MSBuild 개념MSBuild Concepts
MSBuild MSBuild
방법: 빌드할 파일 선택 How to: Select the Files to Build
방법: 빌드에서 파일 제외 How to: Exclude Files from the Build
방법: 항목 목록을 쉼표로 구분하여 표시 How to: Display an Item List Separated with Commas
항목 정의 Item Definitions
일괄 처리 Batching
Item 요소(MSBuild)Item Element (MSBuild)