More than two years ago I wrote a blog post about deploying WCF services using a Web Setup project. Back then it wasn’t an easy task to get services deployed using it. Especially the UI customization of the installation wizard dialog gave me some headache, moreover because they were difficult to test and debug.
As also mentioned in the comments of that post, we now got Web Deploy! So I decided it was about time to rewrite the blog post using the same requirements but then with Web Deploy. Let’s see how much easier it became.
A small revisit of the requirements as formulated in the other blog post:
- support deployment of the WCF artifacts
- be able to be deployed to whatever web site is available on the server
- be able to set ASP.NET security to NTLM
- be able to gather service settings during setup
- be able to change custom AppSettings in the web.config according to the settings
Web Deploy is available for Visual Studio 2005/2008, but I’ll be focusing on Visual Studio 2010. The approaches of the Web Deploy and Web Setup are different. In Web Setup the output was an MSI which could be run by a system administrator. The Web Deploy approach is focused on IIS as the host of the web application or service. This means the output is no longer an MSI but a (ZIP) package that can be imported in IIS or IIS Express or installed using the MSDeploy command line tool.
What are the typical steps to take to deploy a web application or WCF service using Web Deploy from Visual Studio?
First, select the ‘Publish’ option on the project context menu.
A profile page will show up in which you can specify which publish method to use. The options are:
- Web Deploy
- FTP (File Transfer Protocol)
- File system
- FPSE (FrontPage Server Extensions)
Also define a profile name, the server to deploy to and the name of the web application or WCF service. Next click ‘Publish’ and the artifacts are deployed to the target IIS server and site/application.
This covers requirement 1: support deployment of the WCF artifacts
As a side step: if you want to deploy to a remote server, you might run into a few challenges. The Web Deploy is a client/server installation so you need to correctly setup your (IIS) server in order for it to receive the deployment request. If you want to know more, take a look at these posts:
Requirement 2 is: be able to be deployed to whatever web site is available on the server
In the previous step the target web site was defined in Visual Studio, but that should be dynamically changeable when a system administrator runs the package on for example a production environment.
First the package must become portable so it can be installed on a different server, and the next step is enabling the system administrator to pick the website to deploy the service to.
To create a package there are 2 options you can use:
- Visual Studio
- IIS (use the Export Application functionality, which is a topic by itself and not covered here)
In Visual Studio take from the project context menu the option ‘Package/Publish Settings’ to define how the package looks like and then ‘Build Deployment Package’ to actually build the package.
Important settings here are the location of the package, which is a ZIP file, and the target location of the WCF service on the IIS server. Next select ‘Build Deployment Package’ to create it.
Now the package has been build, it is interesting to see what’s in it. Browse to the folder specified in the ‘Package/Publish Settings’ folder to find the files below.
The package consists of:
- CMD file
- This batch file can be used to deploy the package to a server without having to access IIS via the administration console. It uses the command line tool MSDeploy to deploy the package using Web Deploy. Suitable for unattended and/or bulk installations
- Readme file
- Interesting file describing all options for the CMD file. One very interesting one is the /T option, which calls msdeploy.exe with the "-whatif" flag, which simulates deployment. This does not deploy the package. Instead, it creates a report of what will happen when you actually deploy the package. Very useful for testing purposes!
- Parameter file
- This file contains the parameters that are defined for this service and are extracted from the project file (DeployIisAppPath element) during packaging. This file contains by default only one item, see below. Here we immediately notice that this is the value we need to cover requirement 2.
- Manifest file
- This file is not used during deployment, but during generating the package. It contains provider settings and like you can see below some security related entries for the IisApp and setAcl provider.
- ZIP package
- Contains the service to deploy, including configuration, binaries and other artifacts. If you open the ZIP you’ll see all kinds of configuration files that are used during import of the application
For now let’s see how to install the package onto a different server based on the package. First open IIS and select the web site you want to import the web application or WCF service to.
It is out of scope to describe all wizard dialogs but at a certain time you’re asked to specify the application:
In here you can define the destination application and if it doesn’t exist, it will be created for you. This is out-of-the box functionality, but nothing different from the Web Setup approach. Anyhow, this is what we need to fulfill requirement 2.
Requirement 3 is: be able to set ASP.NET security to NTLM
By default the security is set to anonymous access, so we need to change that to windows authentication.
At first this didn’t seem like a big deal, because I expected it to be some parameter or manifest setting, but the more I read on the internet the more I got worried. There is a lot to find about Web Deploy and Windows Authentication, but that mostly relates to using Windows Authentication to connect to the Web Deploy server (up to adding keys to the registry), and not about changing the authentication of a deployed WCF service or web application.
So far I haven’t found an easy way to change the authentication of a deployed WCF service or web application. What I did find was a thread in the IIS Forums about specifying the authentication in the web.config, but in order for that to work the applicationHost.config must be changed to allow overrides. That config file is maintained by the system administrator and I can understand why the system administrator should know about deployment scripts that change the authentication. On the other hand, having a WCF service with Windows Authentication is not that uncommon.
Another option that was mentioned in this thread refers to running a command file which can be added to the manifest file. This command file will probably contain some VBScript to change the authentication after the package has been installed. The difficult thing here is knowing in which web site the WCF Service has been deployed…..
I really hope I overlooked something, so if somebody knows how to do this please leave a comment! Thanks in advance!
Requirement 4 and 5 will be discussed combined: “be able to gather service settings during setup” and “be able to change custom AppSettings in the web.config according to the settings”
Like we’ve seen before, there is a parameters file. This file can be customized from within Visual Studio to make it possible to change the UI the system administrator will see. For this example I’ll demonstrate what it takes to change the value of a custom AppSetting in the web.config. This will be changed from within the UI of IIS. The value to change is a key named ‘Test’ in the AppSettings section of the web.config.
First, add an XML file to your project called “Parameters.xml”, this will contain the parameters the UI will show. This is a different file from the ‘SetParameters.xml’ file we saw earlier; that one is used with the command line option and this one with the IIS import.
Next add this piece of XML. By the way, this is a good resource to learn more about parameters in Web Deploy.
This piece describes two things:
- It defines a parameter with a description to show up in the UI and a default value which will be filled in.
- It defines where the value, read from the UI, should be applied. In this case it is targeted at the web.config file and the XPath points to the AppSettings key ‘Test’.
Building a package from this and importing it in IIS results in the following UI:
As you’ll notice the name and description are displayed nicely, together with the default value. When the value is changed, it will be changed in the web.config when the wizard is finished.
You can imagine the possibilities of this approach. It is very easy to change the UI and set values for example in the web.config without having to code it.
So, did it actually became easier to deploy WCF services? Yes and no. Obviously it is much easier to customize the UI and perform all kinds of actions while deploying, but on the other hand it seems very difficult to perform some common task like changing the authentication of a web site. Like mentioned before, I hope someone will leave a comment with a clarification on the authentication issue.
Anyhow, there is much more you can do with Web Deploy then is covered in this blog post. Please find below useful spending of your spare time.
Didago IT Consultancy
Application integration is all about exchanging messages and messages can only be exchanged if both the sender and receiver know what to expect from each other.
In some branches the standardization of messages and their format is already going on for a while. Examples are:
- Financial (SWIFT)
- Automotive (EDI)
- Supply chain (RosettaNet)
- Medical (HL7)
If plain BizTalk would be used in those environments it would take quite some time to define the message types according to the existing branch standard. In case of EDI these schemas are already supplied by default when installing BizTalk. For the other standardized schemas, they’re available as a separate accelerator install.
In versions prior to BizTalk 2010 the accelerators were distributed as a separate download (from the MSDN subscriber downloads). In BizTalk 2010 it is no longer a separate download, but part of the BizTalk developer or enterprise edition. This blog post focuses on the installation of the HL7 accelerator, which contains standards used by a lot of medical companies and hospitals to exchange messages.
Want to know more about HL7?
The installation of the HL7 accelerator results in one or more of these items, depending on the selection during installation:
- Contains the XSD representation of HL7 messages which are in flat file format in version v2.x
- Converts HL7 messages in flat file format into XML on receive and XML to flat file when sending messages
- Validates the HL7 message
- Minimal Lower Layer Protocol (MLLP) adapter enables BizTalk to receive or send HL7-based messages, which BizTalk Server typically transports using the MLLP protocol. The MLLP adapter ensures that BizTalk Server and BTAHL7 are interoperable with HL7-based messaging applications.
- Generates acknowledgements for received messages
- Tools and Utilities
- Configuration Explorer
- MLLP Test Tool
- Logging framework (for auditing and logging purposes)
If you unpack the BizTalk Server install package (developer edition in this case), you’ll see the BizTalk installer and the accelerator items.
The accelerators folder contains the installer for SWIFT, RosettaNet(RN) and HL7.
Double click ‘Setup.exe’ to start the installation procedure.
The account you’re using during installation must be member of the BizTalk Server Administrators group, even if you’re using the administrator account you have to add this account to this group. Otherwise you’ll get the error message below (which is pretty clear by the way).
If that is fixed, you can move to the next screens, which show the license agreement and user information. Next the choice between typical and custom installation should be made.
In the installation guide from Microsoft, there is an overview of which features get installed for which option. The table below is copied from that document.
The custom type install shows this dialog, with only the items selected according to the table above.
For demo and development purposes, I selected all items. This is including the ‘Logging Framework’ and if selected, the next dialog will ask for an account to run the logging service under.
After specifying an account, the “logon as a service” right will be granted to the account to be able to work unattended.
The Logging Framework will install a Windows service named ‘HL7 Logging Service’ (in previous accelerator versions called ‘Auditing and Logging Service’), which runs in the end “<install folder>\Microsoft BizTalk 2010 Accelerator for HL7\Bin\AuditingLoggingService.exe”. HL7 data flowing through BizTalk is most of the time sensitive medical and/or private information. The logging framework takes care of logging errors, events and messages for auditing purposes. Logging data can be written to the Windows Event Log, WMI or a SQL Server database. After the summary dialog and install path dialog has been passed, the SQL server must be specified.
This is the last dialog of the installation procedure. The next dialog shows a button to start the installation, which will install and configure the accelerator.
After a few minutes the installation is finished and the artifacts, tools and utilities are installed.
There is one interesting button on this dialog: “Launch Tutorial'”.
This button launches a script which prepares your machine with an end-to-end tutorial, by installing schemas and orchestrations including configuring send and receive ports. Of course you won’t use this button when installing the accelerator on a production machine, but for development purposes this is quite handy to get a head start.
At the end of the installation you’ll find a set of files at the chosen installation location (by default C:\Program Files (x86)\Microsoft BizTalk 2010 Accelerator for HL7).
Have fun with HL7!
Didago IT Consultancy