ESB Guidance Setup Steps – Simplified

Microsoft has done an excellent job of documenting the steps required to Install and Setup the ESB Guidance Framework.  The install however is not a straight run of setup.exe and requires several pieces of software to be properly installed and configured.  In addition to this, there are different options you can choose on the software pieces you decide to install and also how you decide to install them.  This, at the end of the day can get pretty confusing if all you are trying to do is get the Framework up and running to understand how it’s been put together.

 

Below I aim to simplify the steps for those of us who may find it difficult or may just want to quickly get the ESB Guidance Framework up and running and are more interested on the code rather than how to become experts at installing it.

 

Note that the below instructions exclude the installation and setup of the MQ Series Adpater.  This can be done later by following the instructions set out on the Microsoft ESB Installation instructions.  Also, I am using VMWare 6.0 to create my virtual machines and the “Team” feature within VMWare to simulate a private LAN where this environment will run.  Alternatively you can, off-course, use Virtual PC, Hyper-V or another Virtual Machine software you like.

 

The instructions below are aimed at listing a simplified approach to setup a Virtual Environment for running the ESB Guidance Framework from Microsoft.  Note that I have taken the approach below of setting up two virtual machines as follows :

          1. Domain Controller

          2. ESB Server ( BizTalk, ESB Guidance Framework, IIS etc… )

 

Alternatively, if you like to get the whole environment running on a single VM, you will need to make your single VM a domain controller, unless off course you like to use an existing domain controller that you have.

 

If you attempt it, let me know.  I will be interested to know who else if playing around with this J

 

Setting up the Domain Controller :

 

1. Install Win 2003 Server Standard R2 (Includes Service Pack 1 )

2. Install Service Pack 2

3. RUN “dcpromo” and follow steps described at http://www.visualwin.com/AD-Controller/

 

 

Setting up the ESB Server

 

1.    Install Win 2003 Server Standard R2 (Includes Service Pack 1 )

 

2. Install Service Pack 2

 

3. Add Following Windows Components:

          - Application Server

                   - ASP.Net

                   - Enabled network COM+ access

                   - Internet Information Services ( IIS )

                             - Common Files

                             - File Transfer Protocol (FTP) Services

                             - Internet Information Services Manager

                             - SMTP Service

                             - World Wide Web Services

                                      - Active Server Pages

                                      - Internet Data Connector

                                      - Server Side includes

                                      - WebDAV Publishing

                                      - World Wide Web Service

          - UDDI Service ( to use SQL 2005 – check http://support.microsoft.com/?kbid=927230  )

 

 

4. Install Latest windows Updates (reboot when required and run windows updates as many times as required until you have no more updates to apply. )

 

5. Make sure that you have setup your LAN properly on VMWare so that the ESB Server can access ( ping ) the Domain Controller.  Add ESB Server to Domain. Login to server with a domain account that has admin access to this box to continue to install what follows. 

 

6. SQL Server 2005 ( Note that this installs .Net Framework 2.0.  Also, choose to install the Database Service, Analysis Services, and Integration Services).  This will be required for BizTalk Install later on. 

 

7. Install SQL Server 2005 SP2 (checkout http://support.microsoft.com/kb/321185 to identify which version of SQL Server 2005 you have ).

 

8. Install Hot fix KB923028 (this fixes the “Unhandled Exception: System.AccessViolationException” error when you run a .NET Framework 2.0 Remoting application, see http://support.microsoft.com/kb/923028 ) 

 

9. Visual Studio 2005 (C# for most projects; C++ for the JMS pipeline component)

 

10. Install Visual Studio 2005 SP1 or later ( If you get “Internal Error 2755 1612″ during installation, just download and install a fix from here.

 

11. Install Microsoft .NET Framework 3.0

 

12. Install .Net Framework 3.0 SP1

 

13. Install InfoPath 2007 and Excel 2007 ( You can install other office products as well if you like but these two are your minimum requirements ).

 

14. Install Enterprise Library 3.1 (required for the ESB Management Portal)

 

15. Dundas Chart v6.1 for ASP.Net ( http://www.dundas.com/Downloads/index.aspx ).  You may want to run the samples for Dundas ( which will install if you pick the option ) to test that it’s working correctly.

 

16. Install BizTalk 2006 R2 ( Remember to create Security Groups for BizTalk on your newly created Domain )

 

Up to now, the installation and configuration steps you have followed have been similar to what you would do to successfully setup and install BizTalk 2006 R2.  What follows now are the steps required for a successful installation of the ESB Guidance Framework.

 

17. Run the following BizTalk HotFix :

          http://support.microsoft.com/?kbid=944532

 

          This HotFix will add four new error reporting properties for BizTalk 2006 R2

         

18. Open a command prompt and move to the following directory : c:\inetpub\AdminScripts

          Run following command from command prompt :

          cscript adsutil.vbs set w3svc/1/root/NTAuthenticationProviders “Negotiate,NTLM”

 

19. Open SQL Server Management Studio and connect to Database and run the following commands :

                  

use [BizTalkMgmtDb] GO GRANT SELECT ON [dbo].[adm_HostInstance] TO [BTS_HOST_USERS] GO GRANT SELECT ON [dbo].[adm_Server2HostMapping] TO [BTS_HOST_USERS] GO use [BizTalkMsgBoxDb] GO GRANT SELECT ON [dbo].[ProcessHeartbeats] TO [BTS_HOST_USERS] GO

         

 

This will grant permissions required by BTS_HOST_USERS to relevant tables in both BizTalkMgmtDB and BizTalkMsgBoxDb database.

 

20. Run : ESB Guidance November 2007.msi

 

21. Create the following directory : c:\Projects\Microsoft.Practices.ESB\

 

22. Unzip contents of ESBSource.zip file into : “c:\Projects\Microsoft.Practices.ESB\” directory

          CHECK : if you have unzipped it correctly, you will have two directories under the “C:\Projects\Microsoft.Practices.ESB\” folder as follows :

         

 

 

22. Install CORE from source.

NOTE : I have found that using the msi to install the core has not worked correctly.  Although it appears to run without any errors, not all artifacts are created.  Hence I have selected to install the CORE from source.  

Follow the instructions from ESB Documentation :

Installing the ESB Guidance from the Solution Project

                       

23. Update the BizTalk configuration file

The BizTalk configuration file named BTSNTSvc.exe.config (located in the folder %ProgramFiles%\Microsoft BizTalk Server 2006) must reference the Microsoft.Practices.ESB.PipelineComponents.config file. The folder \Source\Core\Config (where you installed the ESB Guidance) contains samples of post-edited configuration files.

For reference, review the guidelines in the Microsoft BizTalk 2006 R2 documentation that describes how to create a new application domain.

1. Add the following section to the BTSNTSvc.exe.config file immediately below the opening <configuration> element.

<configSections>   <section name=”xlangs”            type=”Microsoft.XLANGs.BizTalk.CrossProcess.XmlSerializationConfigurationSectionHandler,                  Microsoft.XLANGs.BizTalk.CrossProcess” /> </configSections>

1. Add the following section to the end of the BTSNTSvc.exe.config file, immediately above the closing </configuration> element. Substitute the path to the installation folder of ESB core application for the [path] placeholder in the following listing. If you are installing from the Microsoft.Practices.ESB.CORE.msi Windows Installer, the default path is C:\Program Files\Generated by BizTalk\Microsoft.Practices.ESB\Config.

<xlangs>   <Configuration>     <AppDomains AssembliesPerDomain=”10″>       <DefaultSpec SecondsIdleBeforeShutdown=”1200″                    SecondsEmptyBeforeShutdown=”1800″/>       <AppDomainSpecs>         <AppDomainSpec Name=”Microsoft.Practices.ESB”>           <BaseSetup>             <ConfigurationFile>C:\Projects\Microsoft.Practices.ESB\Source\Core\Config\Microsoft.Practices.ESB.PipelineComponents.config</ConfigurationFile>           </BaseSetup>         </AppDomainSpec>       </AppDomainSpecs>       <PatternAssignmentRules>         <PatternAssignmentRule                 AssemblyNamePattern=”Microsoft.Practices.ESB.*”                 AppDomainName=”Microsoft.Practices.ESB” />       </PatternAssignmentRules>     </AppDomains>   </Configuration> </xlangs>

IMPORTANT NOTE :  Make sure you do not have any returns after the <ConfigurationFile> or before the end tag otherwise when you fire your first itinerary message BizTalk will crash and go into a reboot cycle.

1. Save and close the BTSNTSvc.exe.config file.
2. Restart the BizTalk NT Services. This will create an isolated application domain named Microsoft.Practices.ESB, which will reference the Microsoft.Practices.ESB.PipelineComponents.config file and be available to all the Microsoft.Practices.ESB.* assemblies.

 

23. Update the Machine.config file

The .NET Framework Machine.config file (located in the folder %WinDir%\Microsoft.NET\Framework\v2.0.50727\CONFIG) must contain the contents of the Microsoft.Practices.ESB.PipelineComponents.config file. The folder \Source\Core\Config (where you installed the ESB Guidance) contains samples of post-edited configuration files.

1. Open the Machine.config file in a text editor and add the following section immediately below the opening <configSections> element.

<sectionGroup name=”ESBProcessor”>   <section name=”Resolver”            type=”System.Configuration.DictionarySectionHandler,                  System,Version=2.0.0.0,Culture=neutral,                  PublicKeyToken=b77a5c561934e089″/>   <section name=”AdapterProvider”            type=”System.Configuration.DictionarySectionHandler,                  System,Version=2.0.0.0,Culture=neutral,                  PublicKeyToken=b77a5c561934e089″/>   <section name=”ItineraryCache”             type=”System.Configuration.DictionarySectionHandler,                  System,Version=2.0.0.0,Culture=neutral,                  PublicKeyToken=b77a5c561934e089″/>   <section name=”Cache”            type=”System.Configuration.DictionarySectionHandler,                  System,Version=2.0.0.0,Culture=neutral,                  PublicKeyToken=b77a5c561934e089″/> </sectionGroup>

1. Add the following section at the end of the Machine.config file, immediately above the closing </configuration> element.

<ESBProcessor>   <Resolver>     <add key=”UDDI” value=”Microsoft.Practices.ESB.Resolver.UDDI, Version=1.0.0.0, Culture=neutral,PublicKeyToken=c2c8b2b87f54180a” />     <add key=”WSMEX” value=”Microsoft.Practices.ESB.Resolver.WSMEX,Version=1.0.0.0, Culture=neutral, PublicKeyToken=c2c8b2b87f54180a” />     <add key=”XPATH” value=”Microsoft.Practices.ESB.Resolver.XPATH, Version=1.0.0.0, Culture=neutral, PublicKeyToken=c2c8b2b87f54180a” />     <add key=”STATIC”          value=”Microsoft.Practices.ESB.Resolver.STATIC,                 Version=1.0.0.0, Culture=neutral,                 PublicKeyToken=c2c8b2b87f54180a” />     <add key=”BRE”          value=”Microsoft.Practices.ESB.Resolver.BRE,                 Version=1.0.0.0, Culture=neutral,                 PublicKeyToken=c2c8b2b87f54180a” />   </Resolver>   <AdapterProvider>     <add key=”WCF-WSHttp”          value=”Microsoft.Practices.ESB.Adapter.WcfWSHttp,                 Version=1.0.0.0, Culture=neutral,                 PublicKeyToken=c2c8b2b87f54180a” />     <add key=”WCF-BasicHttp”          value=”Microsoft.Practices.ESB.Adapter.WcfBasicHttp,                 Version=1.0.0.0, Culture=neutral,                 PublicKeyToken=c2c8b2b87f54180a” />     <add key=”FTP”          value=”Microsoft.Practices.ESB.Adapter.FTP,                 Version=1.0.0.0, Culture=neutral,                 PublicKeyToken=c2c8b2b87f54180a” />     <add key=”FILE”          value=”Microsoft.Practices.ESB.Adapter.FILE,                 Version=1.0.0.0, Culture=neutral,                 PublicKeyToken=c2c8b2b87f54180a” />     <add key=”MQSeries”          value=”Microsoft.Practices.ESB.Adapter.MQSeries,                 Version=1.0.0.0, Culture=neutral,                 PublicKeyToken=c2c8b2b87f54180a” />   </AdapterProvider>   <ItineraryCache>     <add key=”timeout” value=”120″ />   </ItineraryCache>   <Cache>     <add key=”UDDI” value=”600″ />     <add key=”WSMEX” value=”600″ />   </Cache> </ESBProcessor>

1. Save and close the Machine.config file.

24. Install ESB Management Portal

1. Copy  DundasWebChart.dll assembly from :

C:\Program Files\Dundas Software\Charting\WebControlVS2005\bin

TO

C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.Portal\bin

Open SQL Server Management Studio and connect to the SQL Server that will host the portal administration database. Open the SQL script ESB.Administration Database.sql from the \Source\Samples\Management Portal\SQL\ folder into a new Query window and execute it to create the EsbAdmin database.

IMPORTANT NOTE : If you have changed the default names of the BizTalk Security Groups ( which you may have if you created them on the Domain Controller you setup at the beginning ) you will need to change this two lines in this script as follows :

‘%BizTalk Application Users%’  change to  ‘%[your new group name]%’

‘%BizTalk Server Administrators%’  change to  ‘%[your new group name]%’

If you don’t make that change, you will get the following message when you execute the script :

 

But don’t worry, just change the script and run it again and it will all work.

1. Create a new IIS virtual directory for the portal using the following settings:
   • Alias: ESB.Portal
   • Directory: C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.Portal
   • Allow the following: Read, Run Scripts (such as ASP)
   • Allow anonymous access: No
   • Enable Integrated Windows Authentication : Yes
   • Application Pool: ESBNetworkAppPool

1. Open the Visual Studio solution named ESB.Portal.sln from the “C:\Projects\Microsoft.Practices.ESB\Source\Samples\Management Portal\ESB.Portal” folder and ensure that the <connectionStrings> section of the Web.config file contains the correct connection strings for the ESBAdmin and EsbExceptionDb databases.
2. Build the ESB.Portal.sln solution using the commands on the Build menu.
3. Check the portal for authentication, authorization, and general configuration settings as described in the  “Check Portal Configuration Settings” on the ESB Documentation.

 25. Install Alert Service

The ESB Management Portal Alert Service is a sample service that notifies users of exceptions published to the ESB Management Portal. The service polls the exception database for new exceptions and evaluates these against exception alerts that users have created in the ESB Management Portal. The service then notifies any users or groups of users that have subscribed to the alert. The service retrieves notification e-mail addresses and group memberships from Active Directory. This service has no dependency on BizTalk Server.

To install the ESB Management Portal Alert Service

 

1. Open the Visual Studio solution named ESB.AlertService.sln from the \Source\Samples\Management Portal\ESB.AlertService folder and ensure that the <connectionStrings> section of the App.config file contains the correct connection strings for the EsbExceptionDb database:

<connectionStrings>   <add name=”EsbExceptionDb”        connectionString=”Data Source=.; Initial Catalog=EsbExceptionDb;                         Integrated Security=True”        providerName=”System.Data.SqlClient”/> </connectionStrings>

1. Build the ESB.AlertService.sln solution using the commands on the Build menu.
2. Open Windows Explorer, navigate to the folder Source \Samples\Management Portal\ESB.AlertService.Install\Release\, and then run the Setup.exe file for the service.
3. Leave all settings at their default values and click Next until the installer displays the user name and password values to configure the service account for the Alert Service. Select an account that is a member of the BizTalk Application Users group with access to both the EsbExceptionDb database and the server hosting the alert service. Enter the account name in the form: <DomainName>\<UserName>
4. Use the Fault Settings page in the portal to configure the following settings in the Configuration table of the EsbExceptionDb database:
   • XsltPath. Point this setting to the folder containing the ESB Portal Alert Service (located by default within the \%Program Files%\Microsoft ESB Guidance Exception Notification Service 1.0 – November 2007 folder).
   • Enable Alert Queue Service. This setting indicates if the alert service should run and check for new exceptions occurring that match existing alerts.
   • Alert Queue Polling Interval. This setting is the number of milliseconds for the alert service to wait between processing batches of alerts.
   • Alert Queue Batch Size. This setting is the number of exceptions that the alert service should process as one operation and match against existing exceptions.
   • Alert Queue Active Directory Cache Interval. This setting is the interval at which the alert service should refresh its cache of Active Directory information, including e-mail addresses and group memberships.
   • LdapRoot. This setting is the LDAP connection string for your domain controller; for example, LDAP://servername.domain.com/DC=domain, DC=com.
   • Enable Alert Email Service. This setting indicates if the alert service should send alert e-mail messages. If you disable this option, the service will still process exceptions and store alerts in an outgoing e-mail queue table. You may prefer to use this scenario if you implement an alternative e-mail delivery service.
   • Email Server. This setting is the name of your e-mail server; for example, mail.domain.com.
   • Sender. This setting is the “From” e-mail address to use in alert e-mail messages.
   • Email Service Polling Interval. This setting is the number of milliseconds the e-mail service waits between sending each batch of e-mail messages.
   • Email Service Batch Size. This setting is the number of e-mail messages the e-mail service should process in a batch.
5. Open the Services applet from the Administrative Tools section of your Start menu and locate the BizTalk ESB Exception Notification Service. Ensure that the start-up type is set to Automatic, and then start the service.

 

26. Install UDDI Publishing Service

The ESB Management Portal UDDI Publishing Service is a sample service that queries the EndPoints table of the ESBAdmin database to retrieve the BizTalk send ports and receive locations to publish to the UDDI server. If the Auto Publish feature is enabled, the service automatically calls the ESB UDDI Web service to publish the endpoint to UDDI. If the Auto Publish feature is not enabled, the service sends a notification e-mail message to the UDDI administrator advising them to log into the ESB Management Portal and publish the endpoint.

Additionally, the UDDI Publishing Service will monitor changes made in the Description field of BizTalk receive locations and send ports. For example, when creating or modifying a receive location or a send port, a developer can indicate that the URL configured for it must be registered with UDDI. The developer can enter the moniker uddi:// into the Description property of the receive location or a send port. The UDDI Publishing Service will detect the entry, retrieve the necessary endpoint information from the BizTalk receive location or send port, and publish it according to the UDDI registry settings configured in the ESB Management Portal.

The UDDI Publishing Service has no dependency on BizTalk Server, and it can be installed on a computer that does not have BizTalk Server installed.

To install the ESB Management Portal UDDI Publisher Service

1. Open the Visual Studio solution named ESB.UDDI.PublisherService.sln from the \Samples\Management Portal\ESB.UDDI.PublisherService folder. Ensure that the <connectionStrings> section of the App.config file contains the correct connection strings for the ESBAdmin and EsbExceptionDb databases. The following are the default settings.

<connectionStrings>   <add name=”AdminDatabaseServer”        connectionString=”Data Source=.;                          Integrated Security=True;                          Initial Catalog=ESBAdmin”        providerName=”System.Data.SqlClient” />   <add name=”EsbExceptionDb”        connectionString=”Data Source=.;                          Initial Catalog=EsbExceptionDb;                          Integrated Security=True”        providerName=”System.Data.SqlClient”/> </connectionStrings>

1. Ensure that the <applicationSettings> section of the App.config file contains the correct addresses for the UDDIService and BizTalkOperationsService Web services. The following are the default settings.

<applicationSettings>   <Microsoft.Practices.ESB.UDDI.PublisherService.Properties.Settings>     <setting name=”ESB_UDDI_PublisherService_UDDIService_UDDIService” serializeAs=”String”>       <value>http://localhost/ESB.UDDIService/UDDIService.asmx</value>     </setting>     <setting name=”Microsoft_Practices_ESB_UDDI_PublisherService_BTQueryService_BizTalkQueryService” serializeAs=”String”>          <value>http://localhost/ESB.BizTalkOperationsService/Operations.asmx</value>     </setting>   </Microsoft.Practices.ESB.UDDI.PublisherService.Properties.Settings>  </applicationSettings>

NOTE : The UDDIService is a custom ESB Web service, not to be confused with the actual UDDI server.

1. Build the ESB.UDDI.PublisherService.sln solution using the commands on the Build menu.
2. Open Windows Explorer, navigate to the folder \Samples\Management Portal\ESB.UDDI.PublisherService.Install\Release, and then execute the Windows Installer file named Setup.exe.
3. Leave all settings at their default values, and then click Next until the installer displays the username and password values to configure the service account for the UDDI Publishing Service. Select an account that is a member of the BizTalk Server Administrators group and that has access to the server hosting the UDDI Publisher Service. Enter the account name in the following form: <DomainName>\<UserName>
4. Use the Registry Settings page in the portal to configure the following settings in the UDDI Admin table of the ESBAdmin database:
   • UDDI Server. This setting is the URL of the UDDI server; for example, http://servername/uddi.
   • Auto Publish. This setting indicates whether the service will automatically publish endpoints to the UDDI server or if administrative approval is required.
   • Anonymous. This setting indicates whether to use anonymous access to connect to the UDDI server or to use the UDDI Publisher Service account.
   • Notification Enabled. This setting indicates whether to send endpoint update notification e-mail messages.
   • SMTP Server. This setting is the address of the SMTP server that will send notification e-mail messages.
   • Notification E-Mail. This setting is the e-mail address to which to send endpoint update notification e-mail messages.
   • E-Mail From Address. This setting is the From address for notification e-mail messages.
   • E-Mail Subject. This setting is the text to display in the subject line of notification e-mail messages.
   • E-Mail Body. This setting is the text for the body of notification e-mail messages.
   • Contact Name. This setting is name of the UDDI administrator to notify of endpoint update requests.
   • Contact E-Mail. This setting is the e-mail address of the UDDI administrator to notify of endpoint update requests.
5. Open the Services applet from the Administrative Tools section of your Start menu and locate the BizTalk ESB UDDI Publishing Service. Ensure that the start-up type is set to Automatic, and then start the service.

25. Configure Exception Management InfoPath Form Template Shares

You must share the folders that contain the InfoPath templates that the ESB Exception Management components and samples use for rendering exception information. You must create a share named Publish for the InfoPath Exception Handling templates and a share named PublishResubmit for the InfoPath Publish and Resubmit template.

To configure InfoPath Form Template shares

1. In Windows Explorer, navigate to the folder \Source\Exception Handling\Source\ESB.ExceptionHandling.InfoPath.Reporting\Publish within the source folder where you installed the ESB Guidance. This folder contains the InfoPath template used to render exception information serialized by the ESB Exception Management Framework.
2. Share this Publish folder using the name Publish, with Read permission for all users. In Windows Server 2003, you can do the following:
   • Right-click the Publish folder in Windows Explorer, click Properties, and then click the Sharing tab.
   • Click Share this folder and accept the default value Publish (the folder name).
   • Click the Permissions button and confirm that the Read check box contains a check mark for the Everyone account group.
   • Click OK in each of the two dialog boxes.
3. In Windows Explorer, navigate to the folder \Source\Samples\Exception Handling\Source\ESB.ExceptionHandling.InfoPath.Resubmit\Publish within the source folder where you installed the ESB Guidance. This folder contains the InfoPath template used to demonstrate the Repair and Resubmit use case within the sample application.
4. Share this Publish folder using the name PublishResubmit, with Read permission for all users, as described in step 2.

 

25. Open BizTalk Administration Console and start the application : Microsoft.Practices.ESB

 

 

CORE INSTALLATION COMPLETE J