MSBuild ItemGroups

Parent Previous Next

The Deployment Framework for BizTalk uses MSBuild ItemGroup elements to identify and locate all of the files that make up your BizTalk solution.  Many of the common artifact types use the same structure, including those for orchestrations, schemas, transforms/maps, pipelines and more.


Element values within an ItemGroup are free to use any MSBuild property in the standard $(propertyName) format.  The most commonly used property is $(Configuration), which contains the name of the active solution configuration (usually Debug or Release).


Typical ItemGroup structure

Most artifact types use a standard ItemGroup structure, shown below:


<ItemGroup>

 <ArtifactName Include="MyFilename.ext">

   <LocationPath>..\ProjectName\bin\$(Configuration)</LocationPath>

 </ArtifactName>

 <ArtifactName Include="MyFilename2.ext">

   <LocationPath>..\ProjectName2\bin\$(Configuration)</LocationPath>

 </ArtifactName>

 ...

</ItemGroup>


ArtifactName is a placeholder for the actual artifact name, such as Orchestrations, Schemas, Pipelines, etc.  One ArtifactName element corresponds to exactly one physical file.  The Include attribute specifies the file name without path information.  The LocationPath element text specifies the path to the file named in the Include attribute, and is always resolved starting in the directory containing the .btdfproj file.  Most of the time the LocationPath text should be a relative path within the BizTalk solution structure, but that is not a restriction.


While most ItemGroups reference files in the file system, some do not.  Those include VDirList, BizTalkHosts, AppsToReference, PropsFromEnvSettings and IisAppPools.


Assemblies containing schemas

The Schemas ItemGroup is appropriate for any BizTalk assembly that contains schemas.  The assembly may contain only schemas, or it may contain a mixture of schemas and other BizTalk artifacts.  Schemas are always deployed early in the deployment cycle because so many other artifacts depend on them.  This is the appropriate choice if your entire BizTalk application is contained in a single assembly.


<ItemGroup>

 <Schemas Include="MySchemas.dll">

   <LocationPath>..\$(ProjectName).Schemas\bin\$(Configuration)</LocationPath>

 </Schemas>

</ItemGroup>


Include attribute: DLL file name

Repeating: 1 or more elements


Assemblies containing pipelines

The Pipelines ItemGroup is appropriate for any BizTalk assembly that contains pipelines (not pipeline components).  The assembly must contain only pipelines.


<ItemGroup>

 <Pipelines Include="MyPipelines.dll">

   <LocationPath>..\$(ProjectName).Pipelines\bin\$(Configuration)</LocationPath>

 </Pipelines>

</ItemGroup>


Include attribute: DLL file name

Repeating: 1 or more elements


Assemblies containing transforms (a.k.a. maps)

The Transforms ItemGroup is appropriate for any BizTalk assembly that contains transforms (a.k.a. maps).  The assembly must contain only transforms.


<ItemGroup>

 <Transforms Include="MyTransforms.dll">

   <LocationPath>..\$(ProjectName).Transforms\bin\$(Configuration)</LocationPath>

 </Transforms>

</ItemGroup>


Include attribute: DLL file name

Repeating: 1 or more elements


Assemblies containing orchestrations

The Orchestrations ItemGroup is appropriate for any BizTalk assembly that contains orchestrations.  The assembly must contain only orchestrations.


<ItemGroup>

 <Orchestrations Include="MyOrchestrations.dll">

   <LocationPath>..\$(ProjectName).Orchestrations\bin\$(Configuration)</LocationPath>

 </Orchestrations>

</ItemGroup>


Include attribute: DLL file name

Repeating: 1 or more elements


Assemblies containing custom functoids

The CustomFunctoids ItemGroup is appropriate for any BizTalk assembly that contains custom functoids.  The assembly must contain only functoids.


<ItemGroup>

 <CustomFunctoids Include="MyFunctoids.dll">

   <LocationPath>..\$(ProjectName).CustomFunctoids\bin\$(Configuration)</LocationPath>

 </CustomFunctoids>

</ItemGroup>


Include attribute: DLL file name

Repeating: 1 or more elements


Assemblies containing custom .NET components

The Components ItemGroup is appropriate for any assembly that contains custom .NET components (classes).  The assembly must contain only .NET artifacts.


<ItemGroup>

 <Components Include="MyComponents.dll">

   <LocationPath>..\$(ProjectName).Components\bin\$(Configuration)</LocationPath>

 </Components>

</ItemGroup>


Include attribute: DLL file name

Repeating: 1 or more elements


Assemblies containing custom pipeline components

The PipelineComponents ItemGroup is appropriate for any assembly that contains custom pipeline components.  The assembly must contain only pipeline components.


<ItemGroup>

 <PipelineComponents Include="MyPipelineComponents.dll">

   <LocationPath>..\$(ProjectName).PipelineComponents\bin\$(Configuration)</LocationPath>

 </PipelineComponents>

</ItemGroup>


Include attribute: DLL file name

Repeating: 1 or more elements


BAM model Excel spreadsheets

The BamDefinitions ItemGroup is appropriate for any Excel spreadsheet that defines a BAM model.


<ItemGroup>

 <BamDefinitions Include="MyBAMModel.xls">

   <LocationPath>..\BRE</LocationPath>

 </BamDefinitions>

</ItemGroup>


Include attribute: Excel file name (xls/xlsx)

Repeating: 1 or more elements


BAM tracking profile definition files

The BamTrackingProfiles ItemGroup is appropriate for any BAM tracking profile definition file.


<ItemGroup>

 <BamTrackingProfiles Include="MyTrackingProfile.btt">

   <LocationPath>..\BRE</LocationPath>

 </BamTrackingProfiles>

</ItemGroup>


Include attribute: Tracking profile file name (btt)

Repeating: 1 or more elements


Assembly containing NUnit test(s)

The DeploymentTest ItemGroup is appropriate for any .NET assembly that contains one or more NUnit test methods.


<ItemGroup>

 <DeploymentTest Include="MyDeploymentTests.dll">

   <LocationPath>..\$(ProjectName).Tests\bin\$(Configuration)</LocationPath>

 </DeploymentTest>

</ItemGroup>


Include attribute: DLL file name

Repeating: Exactly 1 element


XML files requiring preprocessing

The FilesToXmlPreprocess ItemGroup is appropriate for any XML files that require preprocessing with XMLPreprocess.exe.


<ItemGroup>

 <FilesToXmlPreprocess Include="MyFileForPreprocessing.xml">

   <LocationPath>..\SupportingFiles</LocationPath>

   <OutputFilename>MyOutputFile.xml</OutputFilename>

 </FilesToXmlPreprocess>

</ItemGroup>


Include attribute: XML file name

OutputFilename element (optional): specifies the output filename of the processed file, written to the same directory (LocationPath) as the input file

Repeating: 1 or more elements


Assemblies requiring GAC installation

The ExternalAssemblies ItemGroup is appropriate for any .NET assemblies that need to be installed in the GAC.


<ItemGroup>

 <ExternalAssemblies Include="MyDLLForTheGAC.dll">

   <LocationPath>..\ExternalAssemblies</LocationPath>

 </ExternalAssemblies>

</ItemGroup>


Include attribute: DLL file name

Repeating: 1 or more elements


Miscellaneous files required on the BizTalk server

The AdditionalFiles ItemGroup is appropriate for any files that do not fall into a more specific ItemGroup that need to be packaged in the MSI and installed on the server along with your application.


<ItemGroup>

 <AdditionalFiles Include="MyAdditionalFile.reg">

   <LocationPath>..\SupportingFiles</LocationPath>

 </AdditionalFiles>

</ItemGroup>


Include attribute: File name (any extension)

Repeating: 1 or more elements


BRE rule vocabulary XML files

The RuleVocabularies ItemGroup is appropriate for any BRE rule vocabulary XML files.


<ItemGroup>

 <RuleVocabularies Include="MyBREVocabulary.xml">

   <LocationPath>..\BRE\Vocabularies</LocationPath>

 </BamTrackingProfiles>

</ItemGroup>


Include attribute: Vocabulary file name (xml)

Repeating: 1 or more elements


BRE rule policy XML files

The RulePolicies ItemGroup is appropriate for any BRE rule policy XML files.


<ItemGroup>

 <RulePolicies Include="MyBREPolicy.xml">

   <LocationPath>..\BRE\Policies</LocationPath>

 </RulePolicies>

</ItemGroup>


Include attribute: Policy file name (xml)

Repeating: 1 or more elements


ESB Toolkit itinerary XML files

The EsbItineraries ItemGroup is appropriate for any ESB Toolkit itinerary XML files (exported from the Itinerary Designer to XML).


<ItemGroup>

 <EsbItineraries Include="MyItinerary.xml">

   <LocationPath>..\$(ProjectName).Itineraries\bin\$(Configuration)</LocationPath>

 </EsbItineraries>

</ItemGroup>


Include attribute: Exported itinerary XML file name (xml)

Repeating: 1 or more elements


IIS Virtual Directory definitions

The VDirList ItemGroup defines one or more IIS virtual directories.  It's unusual in that it doesn't point to a particular file, but instead defines metadata and folder paths that make up a virtual directory.


<ItemGroup>

 <VDirList Include="*">

   <Vdir>MyWebService</Vdir>

   <Physdir>..\MyWebService</Physdir>

   <AppPool>MyAppPool</AppPool>

   <AppPoolNetVersion>v4.0</AppPoolNetVersion>

 </VDirList>

</ItemGroup>


Include attribute: Always * (a single asterisk)

Repeating: 1 or more elements


BizTalk Host names to restart

The BizTalkHosts ItemGroup is appropriate for the names of one or more BizTalk hosts that should be restarted during the deployment and undeployment processes.


<ItemGroup>

 <BizTalkHosts Include="MyHostName" />

</ItemGroup>


Include attribute: BizTalk host name

Repeating: 1 or more elements


BizTalk application names to reference

The AppsToReference ItemGroup is appropriate for the names of one or more BizTalk applications that should be referenced by the current application.


<ItemGroup>

 <AppsToReference Include="AnotherBizTalkAppName" />

</ItemGroup>


Include attribute: Name of BizTalk application to reference

Repeating: 1 or more elements


MSBuild properties to create from Excel settings spreadsheet

The PropsFromEnvSettings ItemGroup is appropriate for the names of one or more settings listed in the SettingsFileGenerator.xml Excel spreadsheet that should be converted to MSBuild properties.  This allows you to reference any of the setting values in the spreadsheet within the deployment project file.


<ItemGroup>

 <PropsFromEnvSettings Include="MySettingName" />

</ItemGroup>


Include attribute: Name of a setting in the SettingsFileGenerator.xml Excel spreadsheet

Repeating: 1 or more elements


IIS Application Pool names to restart

The IisAppPools ItemGroup is appropriate for the names of one or more IIS application pools that should be restarted during the deployment and undeployment processes.  This applies to IIS 6.0 and newer.  When this ItemGroup is present, the specified application pools are restarted during deployment instead of a full IIS reset.


<ItemGroup>

 <IisAppPools Include="MyAppPoolName" />

</ItemGroup>


Include attribute: IIS application pool name

Repeating: 1 or more elements


Created with the Personal Edition of HelpNDoc: Free PDF documentation generator