MSBuild Properties

Parent Previous Next

The Deployment Framework for BizTalk uses MSBuild properties to define and customize the deployment process.


Typical property usage

MSBuild properties are defined within a PropertyGroup element:


<PropertyGroup>

 <PropertyName>MyValue</PropertyName>

 <PropertyName2>MyValue2</PropertyName2>

 ...

</PropertyGroup>


PropertyGroup's may include an optional Condition attribute that causes the group of properties to be defined at runtime only when a certain boolean statement is true.  A common use case is to define properties differently depending on whether the script is running on a development machine vs. a server.  In this case, the Condition attribute should test against the Configuration property as follows: Condition="'$(Configuration)' == 'Debug'".  Possible values of Configuration are 'Debug', 'Release' (not a BizTalk server) and 'Server' (a BizTalk server).


Properties: Include/Exclude Artifacts

These properties control which BizTalk artifacts are included in or excluded from the deployment.


Name

Default

Description

IncludeBAM

False

Set to True to deploy one or more BAM models, specified in a BamDefinitions ItemGroup.

IncludeComponents

False

Set to True to deploy one or more assemblies containing .NET classes, specified in a Components ItemGroup.

IncludeCustomFunctoids

False

Set to True to deploy one or more assemblies containing custom functoids, specified in a CustomFunctoids ItemGroup.

IncludeDeploymentTest

False

Set to True to deploy an assembly containing NUnit tests, specified in a DeploymentTest ItemGroup.

IncludeEsbItineraries

False

Set to True to deploy one or more ESB Toolkit itinerary XML files, specified in an EsbItineraries ItemGroup.

IncludeLog4net

False

Set to True to deploy a Log4Net configuration file named $(ProjectName).log4net and located in the parent directory of the deployment project folder.

IncludeMessagingBindings

True

Set to True to deploy an XML bindings file, specified in a PortBindings property.

IncludeOrchestrations

True

Set to True to deploy one or more assemblies containing orchestrations, specified in an Orchestrations ItemGroup.

IncludePipelineComponents

False

Set to True to deploy one or more assemblies containing custom pipeline components, specified in a PipelineComponents ItemGroup.

IncludePipelines

False

Set to True to deploy one or more assemblies containing pipelines, specified in a Pipelines ItemGroup.

IncludeSchemas

True

Set to True to deploy one or more assemblies containing schemas, specified in a Schemas ItemGroup.  If an assembly contains schemas and another type of BizTalk artifact, then treat it as a schemas assembly.

IncludeSSO

False

Set to True to deploy the environment-specific settings named in $(SettingsFilePath) [usually exported from the SettingsFileGenerator.xml Excel spreadsheet] into an SSO affiliate app for dynamic access at runtime.

IncludeTransforms

True

Set to True to deploy one or more assemblies containing transforms (maps), specified in a Transforms ItemGroup.

IncludeVirtualDirectories

False

Set to True to deploy one or more IIS virtual directories, specified in a VDirList ItemGroup.

IncludeVocabAndRules

False

Set to True to deploy one or more BRE policies and/or vocabularies, specified in RulePolicies and/or RuleVocabularies ItemGroup(s).


Properties: General Settings

These properties control various aspects of the deployment process.


Name

Default

Description

ApplyXmlEscape

False

Set to True to re-encode nested XML fragments within a bindings XML file prior to deployment.  This may be used with any combination of encoded and decoded nested XML in the bindings file.  It is True by default for new projects.

AutoTerminateInstances

True (Local); False (Server)

Set to True to automatically terminate all running and suspended service instances associated with the application during undeploy, deploy or quick deploy.

BizTalkAppDescription

$(ProjectName)

Specifies the description that appears in the application properties in BizTalk Server Administration.

DeleteFileAdapterPhysicalPathsOnUndeploy

Never

Indicates whether all physical file paths in the bindings file that are associated with FILE adapters should be deleted when the application is undeployed.  Acceptable values: Never, DeleteIfEmpty, DeleteRecursive.

DeployPDBsToGac

True

Set to True to deploy PDB files to the GAC next to the actual assemblies.  Deploying PDBs to the GAC provides more meaningful stack traces.  Enabling this option implies a host stop prior to deployment/undeployment since loading PDBs causes the BizTalk host process to hold on to assemblies even after orchestration unenlistment.

DeploymentFrameworkRootDir

BTDF Install Path

Specifies the path to a folder containing the MSBuild .targets files and task DLL's and the Framework and Developer directories from the BTDF installation folder.  Allows a .btdfproj to reference the Deployment Framework files in an alternative location such as a source control folder.

DisableAutomaticPortNameVersioning

False

Set to True to disable automatic insertion of the application's $(ProjectVersion) into all port names defined in the bindings file.  Only applicable when EnableSideBySide is True.

EnableAllReceiveLocationsOnDeploy

True

Set to True to enable all receive locations during application startup.

EnableSideBySide

False

Set to True to enable side-by-side deployment assistance.  This causes the application's $(ProjectVersion) to be appended to the BizTalk app name, SSO app name and port names.

EnableXmlPreprocess

True

Set to True to enable the use of XMLPreprocess to modify XML files on the fly during deployment, most commonly to merge environment settings into a bindings file.

ExplicitlyDeployRulePoliciesOnDeploy

False

Set to True to explicitly deploy BRE policies during deployment. Regardless of this setting, the policies will always be published, but are normally deployed automatically by BizTalk when the application starts.  If you need policies to be deployed without having to start the BizTalk application, then set this to True.

IISMetabasePath

IIS://localhost/w3svc/1/Root

Specifies the IIS metabase path in WMI (IIS 5/6) format to be used to create IIS vdirs and app pools. The default path is that of the Default Web Site.

IncludeInstallUtilForComponents

False

Set to True to run the .NET Framework InstallUtil.exe tool on each assembly specified in the Components ItemGroup.

IncludeSettingsSpreadsheetInMsi

True

Set to True to include the environment settings spreadsheet (usually EnvironmentSettings\SettingsFileGenerator.xml) in generated MSI files.  Since the spreadsheet may contain sensitive information like passwords and database connection strings, you may elect to leave it under the control of your operations or security staff.

ManageFileAdapterPhysicalPaths

True

Set to True to automatically create and assign file system permissions to any folders associated with FILE adapter ports in the bindings file.

ModifyNTFSPermissionsOnVDirPaths

True

Set to True to edit the NTFS permissions of IIS virtual directory paths to grant Read rights to the AspNet/AppPool identity account.

MsiName

$(ProjectName)-$(ProductVersion)

Specifies the name of the generated MSI file.

RemoveRulePoliciesFromAppOnUndeploy

False

Set to True to remove rule policies from the BizTalk application (visible in Policies node in BizTalk Server Administration) when the application is undeployed. Regardless of this setting value, the policies will always be removed from the rule store.  This option may be useful if you are undeploying rules separately from an application undeployment.

RequireXmlPreprocessDirectives

True

Set to True to require XMLPreprocess to look for ifdef preprocessor sections and replace macros (${id}) only within those sections, or whether (when set to False) it should simply replace all macros in the file.

SettingsFilesExportPath

$(MSBuildProjectDirectory)\EnvironmentSettings

Path that will store settings files exported from the environment settings spreadsheet.  This only applies to developer deployments due to a hard-coded path in the batch files used on server deployments.

SettingsSpreadsheetPath

$(MSBuildProjectDirectory)\EnvironmentSettings\SettingsFileGenerator.xml

Path to the environment settings spreadsheet.  This only applies to developer deployments due to a hard-coded path in the batch files used on server deployments.

SkipBamUndeploy

False (Local); True (Server)

Set to True to ignore BAM models during undeployment.  Undeploying BAM models will cause data loss, so this defaults to True on server deployments.

SkipHostInstancesRestart

False

Set to True to skip restarting BizTalk host instances during deployment/undeployment.

SkipIISReset

False

Set to True to skip restarting IIS (or IIS AppPools on IIS 7.x) during deployment/undeployment.  Recommended value is true if you are not using HTTP/WCF adapters, or if you are using them but have no custom pipeline components.

StartApplicationOnDeploy

True

Set to True to start the BizTalk application at the end of the deployment process.

StartReferencedApplicationsOnDeploy

True

Set to True to start all BizTalk applications referenced by the current BizTalk app.

SuppressMSIValidation

False

Set to True to suppress WiX validation of generated MSI's.  This may be necessary when a build server is used and the build service account does not have administrative rights on the build server.  Symptom is generally a build error like "Error executing ICE action 'ICE01'".

UndeployIISArtifacts

False (Local); True (Server)

Set to True to undeploy IIS virtual directories during undeployment.

UsingMasterBindings

False

Set to True to enable use of a master (templated) bindings XML file that will be transformed at deploy time to a standard BizTalk bindings XML file.

XmlEscapeXPathsFile

$(DeployTools)\adapterXPaths.txt

Filename of and optional relative path to a text file containing XPath statements, one per line, to be processed by ElementTunnel.exe during bindings file preprocessing.  Only applies when ApplyXmlEscape is True.  The Deployment Framework for BizTalk includes a default file under the Framework\DeployTools folder.


Properties: BizTalk Host Control (Host Config Files)

These properties cause modifications to the BizTalk host config file(s) [BTSNTSvc.exe.config/BTSNTSvc64.exe.config]. Please see the BizTalk product documentation for more information.


Name

Default

Description

ConfigureBizTalkDebuggingFeatures

False

Set to True to enable configuration of the BizTalk debugging settings in BTSNTSvc[64].exe.config.

EnableBizTalkAssemblyValidation

False

Set to True to cause the BizTalk engine to load all assemblies referenced by immediate dependent assemblies of an orchestration, and upon failure throw an AssemblyValidationException.

EnableBizTalkCorrelationValidation

False

Set to True to cause the BizTalk engine to verify that in a parallel convoy all messages that match one of the convoy receives have the same correlation property values, and upon failure throw a CorrelationValidationException.

EnableBizTalkExtendedLogging

False

Set to True to cause the BizTalk engine to display the promoted properties in the information for PublishMessageException for the message that failed to publish.

EnableBizTalkSchemaValidation

False

Set to True to cause the BizTalk engine to use XmlValidatingReader to validate every schema representing a message part type, and upon failure throw an XmlException.

UseIsolatedAppDomain

False

Set to True to cause BizTalk to load this application's assemblies into a separate .NET AppDomain.


Properties: MSI Generation

These properties control generation of your application's MSI.


Name

Default

Description

CreateStartMenuShortcuts

True

Set to True to create shortcuts in the Start menu for deploy, undeploy, etc. upon installation of the MSI. If this property is set to False, the only way to deploy or undeploy the application is via custom scripted commands.

DefaultInstallDir

ProgramFilesFolder\[ProductName]\[ProjectVersion]

If present, this path will be written into a batch file generated next to the MSI.  The batch file simply passes this path into the msiexec command-line to override the default property value.

Manufacturer

Deployment Framework User

Manufacturer name shown in the installer properties

PackageComments

[ProjectName]

Comments shown in the installer properties

PackageDescription

[ProjectName]

Description shown in the installer properties

ProductId

GUID

GUID that changes for each new version of the application.  This is used to determine whether the same application is already installed.

ProductName

[ProjectName] for BizTalk

Product name shown in the title of the installer

ProductUpgradeCode

GUID

GUID that remains the same across versions of the application. This is used to determine when to upgrade an existing installed app.  If you want to have two versions of the app installed side-by-side, then you need to change this GUID.  Otherwise, keep it the same but update the ProductId and ProductVersion.

ProductVersion

1.0.0

Version number used only by the installer, displays in Add/Remove Programs

WiXCandleArguments

(Too long to reproduce here)

Command line arguments for the WiX Candle (compiler) tool.

WiXDir

WiX 3.7 installation path, otherwise $(DeploymentFrameworkDeveloperDir)\WiX

Path to the WiX binaries (light.exe, heat.exe, candle.exe and extension DLL's)

WiXHeatArguments

(Too long to reproduce here)

Command line arguments for the WiX Heat tool.  Heat is used to dynamically generate a WXS file from the obj\$(Configuration)\redist folder.

WixHeatTransformFile

$(DeploymentFrameworkDeveloperDir)\RedistComponentGroup.xslt

Path to an XSLT that transforms/modifies the Heat-generated WXS file representing the redist folder, relative to the deployment project folder.  The default transform adds Start menu shortcuts, steps to clean up generated files, etc.

WiXLightArguments

(Too long to reproduce here)

Command line arguments for the WiX Light (linker) tool.

WixProjectFile

$(DeploymentFrameworkDeveloperDir)\GenericBizTalkMSI.wxs

Path to the main WXS file that defines the MSI, relative to the deployment project folder.  The MSI is created by combining this file with the Heat-generated WXS.

WiXRegistryKey

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows Installer XML\3.7

Registry key used to detect the installation path for WiX.  This is relevant only on development machines and build servers where a server MSI is generated.  BizTalk servers do not use nor do they require WiX.



Created with the Personal Edition of HelpNDoc: Generate EPub eBooks with ease