Introduction

In some of the BizTalk applications, the BizTalk schemas/orchestrations are exposed as Web/WCF services and the end point is then used to trigger the BizTalk logic. Such Web/WCF services can be deployed using the WCF Publishing Wizard on the development boxes and when the application is promoted to the next higher environment then the Web/WCF service can be exported in the MSI package from the BizTalk admin console. So when the BizTalk application is deployed on the next environment then the Web/WCF service is deployed to the IIS. But this method has some problems.

  1. The entire task is manual
  2. Administrators need to create the application pool on the higher environment
  3. Need to check if the newly deployed Web/WCF service has correct application pool set.

↑Back To Top 


Solution

In order to automate the deployment of the Web/WCF services, BTDF can be used. The information for the deployment of the Web/WCF service can be baked in the Deployment.btdfproj file and when the BTDF is deploying the BizTalk application, it will deploy the service to IIS. But BTDF keeps the service files in the location where the MSI is extracted and the path configured in the Deployment.btdfproj file (which directly resides inside the solution). But sometimes it is not the required solution as the practices in the organization demands that the services be hosted on IIS and the service artifacts be placed under the inetpub folder.

↑Back To Top


Scope

This article explains how to deploy the Web/WCF service using BTDF to the IIS and have the service artifacts under the inetpub folder.

↑Back To Top


Implementation

The implementation of this approach can be divided into the following steps.

  1. Creating Web Service
  2. Configuring BTDF project file

Creating Web Service

In order to create the web service,  the developer needs to use the BizTalk WCF Publishing Wizard where they can publish the WCF service to the IIS and attach it to any BizTalk application of their choice. Once this step is finished, the artifacts are available under the C:\inetpub\wwwroot folder under the service application folder.  These files should be added to the BizTalk solution under a folder which will be used later on.

Configuring BTDF Project File

Setting Up Initial Properties

Normally in order to deploy Virtual Directories to IIS, following property is set to True

<IncludeVirtualDirectories>True</IncludeVirtualDirectories>

This property tells the BTDF to use the DeployVirtualDirectories target which will deploy the Service to IIS but it will keep the artifacts under the extracted application folder.  In this case, since the requirement is to deploy the Service to the IIS with the artifacts to be placed under C:\inetpub\wwwroot , this property is set to False.

<IncludeVirtualDirectories>False</IncludeVirtualDirectories>

The aim is to create a custom deployment and undeployment target which will copy the files from the extracted folder to the application folder under C:\inetpub\wwwroot . In order to tell BTDF to package the service artifacts to the MSI, following property group is configured.

<PropertyGroup>
    <Vdir>BizTalkervices</Vdir>
    <Physdir>..\BizTalkApp.Services\BizTalkServices</Physdir>
    <AppPool>BizTalkAppServices</AppPool>
    <AppPoolNetVersion>v4.0</AppPoolNetVersion>
    <CustomProperty_WebRootDir>c:\inetpub\wwwroot</CustomProperty_WebRootDir>
    <CustomProperty_ServerPhysDirName>BizTalkervices</CustomProperty_ServerPhysDirName>
    <CustomProperty_IntegratedManagedPipeline>True</CustomProperty_IntegratedManagedPipeline>
  </PropertyGroup>

Above property group will tell the BTDF to pick up the service artifacts from ..\BizTalkApp.Services\BizTalkServices folder in the solution and then package them under the BizTalkApp.Services\BizTalkServices folder. This folder will be created at the path given while installing the BTDF msi. The custom property created above will serve following purpose. CustomProperty_WebRootDir tells the BTDF where to place the service artifacts. CustomProperty_ServerPhyDirName tells the BTDF under which service folder will the artifacts will be copied. CustomProperty_IntegratedManaged  governs the pipeline mode for the application pool attached to the WCF service.

So in the above sample, BTDF will copy the service artifacts from <MSIInstallationPath>\BizTalkApp.Services\BizTalkServices to C:\inetpub\wwwroot\BizTakServices 

In order to reset the IIS once the deployment is complete, following property should be set to True 

<SkipIISReset>False</SkipIISReset>


Custom Deployment Target

The Custom deployment target will do the following tasks

  1. Check if the Application, Virtual Directories for the application exist in IIS. If yes delete them
  2. Delete the empty application folder from the C:\intepub\wwwroot
  3. Copy the Service artifacts from the Physical Directory specified in Property group above to C:\inetpub\wwwroot\ApplicationName derived also from above property group
  4. Create the Virtual Directories and IIS applications and amp them to the artifacts copied above.
  5. Create the application pool and attach it to the application created above.

In order to do the IIS related actions in the above steps, appcmd command is used(See References section).
In order to perform task 2, rmdir command is used(See References section).
In order to perform task 3 robocopy command will be used which will copy the artifacts(See References section).

A typical custom deployment target looks like below.
<Target Name="Custom_DeployVDirToIIS">
 
    <!--Check if the Virtual Directories and Application Exist in IIS, if yes delete them-->
    <Message Text="Attempt to delete virtual directories, applications and files in case they already exist"/>
    <Exec Command=""$(AppCmd)" DELETE app "Default Web Site/BizTalkServices"" ContinueOnError="true"  />
    <Exec Command=""$(AppCmd)" DELETE VDir "Default Web Site/BizTalkServices"" ContinueOnError="true"   />
    <!--Remove the empty folders which were mapped to above application-->
    <Exec Command="rmdir "$(CustomProperty_WebRootDir)\$(CustomProperty_ServerPhysDirName)" /S /Q"
       Condition="'$(IisMajorVersion)' == '7' and '$(AppPoolNetVersion)' != ''"  ContinueOnError="true" />
 
    <Message Text="Deploying virtual directories, applications and files"/>
    <!--Copy files for task 3-->
    <Exec Command="robocopy "$(MSBuildProjectDirectory)\$(Physdir)" "$(CustomProperty_WebRootDir)\$(CustomProperty_ServerPhysDirName)" /E /COPY:DAT /R:3 /W:5 /XF *.exe *.bat *.cmd" IgnoreExitCode="true"/>
    <!-- Update IIS Virtual Dir to use Directories copied above-->
    
   <!--Create Virtual Directory and IIS application and application Pool and attach the Application Pool to the application-->
    <Exec Command=""$(AppCmd)" ADD VDir /app.name:"Default Web Site/" /path:/BizTalkServices -physicalPath:C:\inetpub\wwwroot\BizTalkServices" />
    <Exec Command=""$(AppCmd)" ADD app /site.name:"Default Web Site" /path:/BizTalkServices -physicalPath:C:\inetpub\wwwroot\BizTalkServices" />
    <Exec Command=""$(AppCmd)" ADD  apppool /name:"BizTalkAppServices" /managedRuntimeVersion:v4.0" ContinueOnError="true" />
    <Exec Command=""$(AppCmd)" set app "Default Web Site/BizTalkServices" /applicationpool:BizTalkAppServices" />
 
    <Exec Command=""$(AppCmd)" set config /section:applicationPools /[name='BizTalkAppServices'].processModel.identityType:SpecificUser /[name='BizTalkAppServices'].processModel.userName:$(VDIR_UserName)  /[name='BizTalkAppServices'].processModel.password:$(VDIR_UserPass)"
      Condition="'$(Configuration)' == 'Server'" />
  </Target>


Custom Undeployment Target

The undeployment Target will do the following tasks.

  1. Delete the Virtual Directories and Application from IIS
  2. Remove the empty folder from C:\inetpub\wwwroot
  3. Delete the Application pool (This step should be skipped if the application pool is shared across multiple applications in IIS).

The IIS related commands are performed using appcmd command while empty folders are removed using the rmdir command(See References section for more details)

A typical custom undeployment target will be as following

  <Target Name="Custom_UndeployVirtualDirFromIIS">
 
  <!--Delete virtual directories, applications and files-->
  <Message Text="Delete virtual directories, applications and files"/>
  <Exec Command=""$(AppCmd)" DELETE app "Default Web Site/BizTalkServices"" />
  <Exec Command=""$(AppCmd)" DELETE VDir "Default Web Site/BizTalkServices""   />
 
  <Exec Command="rmdir "$(CustomProperty_WebRootDir)\$(CustomProperty_ServerPhysDirName)" /S /Q"
     Condition="'$(IisMajorVersion)' == '7' and '$(AppPoolNetVersion)' != ''" />
 
  <Exec Command=""$(AppCmd)" delete apppool /apppool.name:BizTalkAppServices"
    Condition="'$(Configuration)' == 'Server'" />
 
</Target>


Setting Credentials For Application Pool

The credentials for the app pool are accessed through the variables $(VDIR_UserName) and  $(VDIR_UserPass). The variables are set in the InstallWizard.xml(gets generated while creating a BTDF project).

A sample InstallWizard.xml file is shown below.
<?xml version="1.0" encoding="utf-8" ?>
<!--
    Deployment Framework for BizTalk
    Copyright (C) 2008-14 Thomas F. Abraham, 2004-08 Scott Colestock
-->
<!-- Each SetEnvUIConfigItem element defines a single page in the wizard that appears during a server deployment. -->
<!-- The EnvironmentVarName element specifies the name of an environment variable that will contain the value of the -->
<!-- user's selection. Each environment variable automatically becomes an MSBuild property that you may reference in -->
<!-- your .btdfproj file. -->
   <DialogCaption>BizTalkSampleApp</DialogCaption>
    
  <SetEnvUIConfigItem>
    <PromptText>Select the XML file that contains configuration information specific to this environment:</PromptText>
    <PromptValue></PromptValue>
    <ValueType>FileSelect</ValueType>
    <EnvironmentVarName>ENV_SETTINGS</EnvironmentVarName>
  </SetEnvUIConfigItem>
  <SetEnvUIConfigItem>
    <PromptText>Enter the Domain Qualified UserName under which the Isolated Host Is Running</PromptText>
    <PromptValue></PromptValue>
    <ValueType>Text</ValueType>
    <EnvironmentVarName>VDIR_UserName</EnvironmentVarName>
  </SetEnvUIConfigItem>
  <SetEnvUIConfigItem>
    <PromptText>Enter the Password for the UserName under which the Isolated Host Is Running</PromptText>
    <PromptValue></PromptValue>
    <ValueType>Password</ValueType>
    <EnvironmentVarName>VDIR_UserPass</EnvironmentVarName>
  </SetEnvUIConfigItem>
  <SetEnvUIConfigItem>
      <PromptText>Is this the LAST server in the BizTalk Group you are deploying to?
      
If so, BizTalk assemblies will be deployed to the BizTalk Management Database.</PromptText>
      <Caption>This is the LAST server in the BizTalk Group</Caption>
      <PromptValue>true</PromptValue>
      <ValueType>Checkbox</ValueType>
      <EnvironmentVarName>BT_DEPLOY_MGMT_DB</EnvironmentVarName>
   </SetEnvUIConfigItem>
</SetEnvUIConfig>

So when the BizTalk application is deployed, the MSI will prompt the Administrator to enter the UserId and the Password which will be used to configure the application pool.


Calling Custom Deployment and Undeployment Targets

In order to call the custom targets created above, they should be called from the CustomPostDeployment and CustomPostUndeployTarget as shown below.

<Target Name="CustomPostDeployTarget">
     <CallTarget Targets="Custom_DeployVDirToIIS"/>
</Target>

<Target Name="CustomPostUndeployTarget">
  <CallTarget Targets="Custom_UndeployVirtualDirFromIIS"/>
</Target>

This completes the set up of the Deployment.btdfproj file to deploy the WCF service to the IIS.

↑Back To Top


Conclusion

As evident from above set up it is easy to set up a BTDF project to deploy the WCF services to IIS with service artifacts hosted in C:\inetpub\wwwroot\application folder.

↑Back To Top


See Also

Following wiki articles can be used to learn more about BTDF.
  1. Deploying web services with BizTalk Deployment Framework 
  2. BizTalk Server: Creating and Deploying BizTalk Web HTTP GET End Point Using BTDF Framework 
  3. BizTalk: Setting Authentication on BizTalk Service Endpoints Using BTDF 
  4. BizTalk Server: Creating and Deploying BizTalk HTTP Receive Locations using BTDF framework
  5. BizTalk 2016 Step by Step Guide: Installation and Configuration of BTDF and Visual Studio 2015 

↑Back To Top


References

Following documentation was referred while writing this article.
  1. Deployment Framework for BizTalk Server V5.0 
  2. Robocopy Command 
  3. rmdir Command 
  4. Getting Started with AppCmd.exe 

↑Back To Top