Microsoft Enterprise Library 5.0 Integration Pack for Windows Azure - FINAL RELEASE
November 20111. Where to get it?2. What’s in this release?3. Getting Started4. Autoscaling Application Block
- Using application block binaries
- Using Windows PowerShell cmdlets
- Migrating from earlier versions
5. Transient Fault Handling Application Block6. Building application blocks from source7. Installing the Tailspin Surveys sample application (reference implementation)8. Systems requirements
- For the application blocks
- For the Windows PowerShell cmdlets
- For the Tailspin Surveys sample application
9. Notes and known issues10. Providing Feedback
1. Where to get it?
Via NuGetAlternatively, self-extracting zips for binaries and sources are avaialble on MSDN, but NuGet is the easiest and recommended way.
2. What’s in this release?
- Two new application blocks:
- Autoscaling Application Block ("Wasabi")
- Transient Fault Handling Application Block ("Topaz")
- Blob configuration source (available as a separate NuGet package - "Enterprise Library 5.0 - Windows Azure Configuration Extensions")
- PowerShell cmdlets for Wasabi (available as a separate self-extracting zip download)
- Protected configuration provider
- Updated database creation scripts
- On-premises sample application for hosting the Autoscaling Application Block and exploratory testing (packaged with the Integration Pack Source and located under (install location)/WindowsAzure/Autoscaling/Hosts/ConsoleAutoscaler)
- Experience guidance
You can download the Developer's Guide and Reference documentation in PDF and CHM format here
The detailed Change Log is available here
3. Getting Started
Please refer to the instructions for individual application blocks below and see the corresponding sections in the Reference documentation and the Developer's guide.
Additionally, we are shipping the Tailspin Surveys Reference Implementation (sample app) that showcases various usages of the new blocks. We’ve expanded the scope of the Tailspin Surveys Reference Implementation originally shipped with the "Developing Applications for the Cloud"
guide by making it more elastic and more resilient to transient failures.
The video walkthrough is available via Channel9
4. Autoscaling Application Block
4.1 To use the Autoscaling Application Block binaries, follow these steps:
4.1.1 Download the "Enterprise Library 5.0 - Autoscaling Application Block" NuGet package.
4.1.2 Host the Autoscaler object in some application (for an example, see ConsoleAutoscaler).
4.1.3 Set the Target framework in the application that hosts the Autoscaler object to ".NET Framework 4." The application block will not work with the ".NET Framework 4 Client Profile" framework.
4.1.4 Author the configuration file for the hosting application with the corresponding settings for the Autoscaling Application Block.
a. You can use an example from the ConsoleAutoscaler (App.Config).
b. Alternatively, download and install the Configuration tool from the Visual Studio Extension Gallery.
4.1.5 Author the rules (see sample: RulesStore.xml). You will find the schema in AutoscalingRules.xsd. See http://msdn.microsoft.com/en-us/library/ms255816.aspx for guidance on how to assign schemas to XML files in Visual Studio.
4.1.6 Provide the service model information (see sample: ServiceInformationStore.xml). You will find the schema in AutoscalingServiceModel.xsd.
4.1.7 (Optionally) If you are using a blob store for your rules or service information, you will need to upload the files defined in steps 4 and 5 to the appropriate blob container.
4.1.8 Resolve an instance of the Autoscaler through the Enterprise Library container (for a variety of ways to do this see "Creating Instances of Enterprise Library Types" section of the Enterprise Library 5.0 Developer's Guide).
4.1.9 (Optionally) The Autoscaling Application Block supports an execution lease component to ensure that only a single instance of the Autoscaler can run at any one time. It is configured under the Advanced Options in the configuration tool. If you are using the execution lease and hosting the Autoscaler in the cloud, remember to stop the Autoscaler to release the lease (in the OnStop() method).
4.1.10 (Optionally) Configure logging (by either using the provided LoggingBlockLogger or SourceLogger).
4.2 To use the PowerShell commandlets to manipulate the Autoscaling Application Block configuration, follow these steps:
4.2.1 Extract the zip into the standard PowerShell modules location:
- for Windows 7, Windows Server 2008 or Windows Server 2008 R2, it is likely to be C:\Users\<user-name>\Documents\WindowsPowershell\Modules\WasabiCmdlets
- for Windows Server 2003, it is likely to be C:\Documents and Settings\<user-name>\My Documents\WindowsPowershell\Modules\WasabiCmdlets
- Note: if you don't have the WindowsPowershell folder, feel free to create it.
4.2.2 From within a Windows PowerShell session, run:
4.2.3 To get a list of commands, run:
get-command -Module Wasabicmdlets
4.2.4 For help, use the usual PowerShell cmdlet:
4.3: To migrate from earlier interim releases to the final release, uninstall the Beta version of the NuGet package and install new packages that don’t include “Beta” or “Preview” prefix in the NuGet package title and has the version 5.0.1118.0. To locate them quickly in the NuGet Package Manager, use “elazure” as a keyword.
5. Transient Fault Handling Application Block
5.1 To use the Fault Handling Application Block binaries, follow these steps:
5.1.1 Download the "Enterprise Library 5.0 - Transient Fault Handling Application Block" NuGet package.
5.1.2 Set the Target framework in the application that uses the Transient Fault Handling Application Block to ".NET Framework 4." The application block will not work with the ".NET Framework 4 Client Profile" framework.
5.1.3 Follow the steps from the Reference Documentation or the Developer's Guide to use the application block.
Topaz Service Update - Oct 2012
Topaz support for Task-based Aynschronous Pattern (TAP) - Sep 2012
Topaz Service Update - Aug 2012
6. To build the application blocks from source, follow these steps:
6.1 Download the "Enterprise Library 5.0 - Integration Pack for Windows Azure - Source" NuGet package.
6.2 Extract the "Enterprise Library 5.0 Integration Pack for Windows Azure - Source.zip" file from the "(SolutionFolder)packages\EnterpriseLibrary.Source.WindowsAzure.5.0.1118.0\source" folder to a target folder.
6.3 To automatically download the external dependencies via NuGet:
a. Open the Autoscaling.sln solution file located in the "(TargetFolder)\WindowsAzure\Autoscaling\Source\Autoscaling" folder from Visual Studio 2010.
b. From Visual Studio, open the "Package Manager Console" from the "Tools\Library Package Manager" menu.
c. Locate the "Package Manager Console" window and type in
to install the NuGetPowerTools (more information about the NuGetPowerTools can be found at https://github.com/davidfowl/NuGetPowerTools)
d. Run the Enable-PackageRestore command to download all the external dependencies.
6.4 Compile the solution.
6.5 (Optionally) Some unit tests require the Windows Azure Storage Emulator to run.
7. To install the Tailspin Surveys sample application (reference implementation):
- follow the steps outlined in the "Tailspin Surveys Installation Guide" in the Developer's Guide
8. Systems Requirements
8.1 For the application blocks:
- Operating systems: Windows 7 Professional or higher, 32-bit and 64-bit; Windows Server 2008 R2 or Windows Server 2008
- Windows Azure Tools for Visual Studio and Windows Azure SDK v1.6 (all-in-one installer can be found at http://www.microsoft.com/windowsazure/sdk/)
- Additionally, in order to run unit tests, the following is also required:
- Moq (v4.0 or later). (This will be installed automatically if you install the Enterprise Library Integration Pack for Windows Azure Source package via NuGet.)
- In order to run all the unit tests in the Transient Fault Handling Application Block (“Topaz”) you will need to update two connection strings in the App.config file of the TransientFaultHandling.Tests project to point to an instance of SQL Azure that has the AdventureWorks sample database installed.
- Optionally, in order to use the Logging Application Block Logger, the following is also required:
- the Microsoft Enterprise Library 5.0 Logging Application Block (available via NuGet or as an MSDN download)
8.2 For the PowerShell cmdlets:
- Operating systems: Windows 7 Professional or higher, 32-bit and 64-bit; Windows Server 2008 R2 or Windows Server 2008; PowerShell cmdlets have also been tested on Windows Server 2003
8.3 For the Tailspin Surveys sample application (reference implementation):
- Run the Dependency Checker and follow the instructions from the Installation manual (Appendix B of the Developer's Guide)
The Tailspin Surveys sample application has been tested on Windows 7 Professional 32-/64-bit and on the Windows Server 2008 R2 platforms. It will likely work on other platforms if you satisfy the pre-requisites identified by the Dependency Checker, but those have not been included in the test matrix.
9.1 All XML-based blob-based configuration should be UTF8-encoded.
9.3. IntelliTrace is not supported for the Autoscaling Application Block. Due to a limitation in Visual Studio 2010 IntelliTrace, the following runtime exception is thrown when the application block is hosted on Windows Azure with IntelliTrace enabled: System.Security.VerificationException: Operation could destabilize the runtime.
Workaround: To address this issue, you will need to disable IntelliTrace on the Autoscaling Application Block assembly. To do this, add Microsoft.Practices.EnterpriseLibrary.WindowsAzure.* to the list of excluded modules. See instructions
9.4 For reactive rules to work for a configured time window, there should be at least two data points. One at the first 2/5 of the window and the second at the 4/5-5/5th of the time window.
For example, if the time window is 15 minutes, there should be a data point collected during the first 6 minutes and the last 6 minutes.
9.5 Keep in mind the application throttling is designed to only work with the default "Scale" option or the "ScaleAndNotify" option. It will not work when the scaling mode for a hosted service is set to "Notify" only.
9.6 When using the Autoscaling Application Block with a Blob configuration source, a role restart is required for any runtime configuration (app.config) changes. Runtime changes to the rules and service information stores are picked up automatically and no restart is required.
9.7 Make sure that all storage account connection strings defined in the service information store XML file point to existing account names, otherwise the Autoscaler might become unresponsive.
9.8 The Transient Fault Handling Core that includes the retry mechanisms, ships as a separate package and doesn't have any dependencies on Enterprise Library. Therefore, it doesn't have configuration support included either. If you want to use the Enterprise Library configuration support, install the Transient Fault Handling Application Block (available as a NuGet package).
9.9 Installing the application block binaries via NuGet is a recommended approach. It will ensure that all necessary dependencies are met and that the config tool can find new application blocks. If for whatever reason you cannot use NuGet (either through the public repository or through your own private repository), alternatively you can download the binaries as a standalone self-extracting archive from MSDN. In this case, you will need to add an entry to the folder where the binaries are in the “Enterprise Library binaries paths” solution property. Preferably, this folder should be in location relative to the solution, or all users should install the binaries in the same location. When adding an entry to the solution property manually, be careful not to corrupt or delete any existing entries.
9.10 If you have installed the Enterprise Library 5.0 Optional Update 1 (via .msi file) and would like the config tool to recognize newly added application blocks, they need to be placed in the same folder where all the Enterprise Library binaries reside:
9.10.1 Download the Integration Block for Windows Azure binaries from MSDN and extract them
9.10.2 Copy all Enterprise Library and Integration Pack for Windows Azure binaries to a new folder
9.10.3 Define a new configuration set for it (as described here) and set the Enterprise Library Configuration set solution property to point to this.
10. Providing Feedback
To provide feedback about this release, the reference implementation or written guidance, or to get help with any problems, please visit the Enterprise Library discussion forum
We look forward to your comments!