Scott Hanselman

Installing, Configuring and Using Windows Server AppFabric and the "Velocity" Memory Cache in 10 minutes

July 1, '10 Comments [39] Posted in AppFabric | ASP.NET
Sponsored By

A few weeks back I blogged about the Windows Server AppFabric launch (AppFabric is Microsoft's "Application Server") and a number of folks had questions about how to install and configure the "Velocity" memory cache. It used to be kind of confusing during the betas but it's really easy now that it's released.

Here's the comment:

Have you tried to setup a appfabric (velocity) instance ? I suggest you try & even do a blog post, maybe under the scenario of using it like a memcache for dasblog. I would love to know how to setup it up, it's crazy hard for what it is.

No problem, happy to help. I won't do it for dasblog, but I'll give you easy examples that'll take about 10 minutes.

Get and Install AppFabric

You can go to and download it directly or just do it with the Web Platform Installer.

Run the installer and select AppFabric Cache. If you're on Windows 7, you'll want to install the IIS 7 Manager for Remote Administration which is a little plugin that lets you manage remote IIS servers from your Windows 7 machine.

NOTE: You can also an automated/unattended installation as well via SETUP /i CACHINGSERVICE to just get caching.

The configuration tool will pop up, and walk you through a small wizard. You can setup AppFabric Hosting Services for Monitoring and Workflow Persistence, but since I'm just doing Caching, I'll skip it.Windows Server AppFabric Setup Wizard

The Velocity Caching Service needs to know where to get its configuration and it can get it from one of two places - either a database or an XML file on a share. If you use the XML file on a share, you'll need to make sure the service account has access to the share, etc. I'll use a database. The config wizard can make it for you as well. Click Next then Finish up the configuration.

Windows Server AppFabric Caching Service configuration Store

Configuring the Configuration Database...

Windows Server AppFabric Configuration Wizard

Ok, let's start it up and poke around.

Start and Administer your Memory Cluster from PowerShell

Now what? Go to the Start Menu and type in Caching. You'll have an item called "Caching Administration Windows PowerShell." This is where you can connect to the cache, check out what's going on, make new caches, etc. Run it as Administrator.

Caching Administration Windows PowerShell

If you type "get-command *cache*" you'll see all the different commands available for cache management. I typed start-cachecluster.

C:\> Start-CacheCluster

HostName : CachePort      Service Name            Service Status Version Info
--------------------      ------------            -------------- ------------
HANSELMAN-W500:22233      AppFabricCachingService UP             1 [1,1][1,1]

Cool, it's up and running. If you look in the config database (or the XML file if you chose that) you'll see that I have one machine in my memory cluster. I could have lots and lots, and if I had Windows Server Enterprise I would also have high-availability if one of the nodes went down.

I download the AppFabric Caching Samples and opened the CacheSampleWebApp in Visual Studio. Immediately we notice the two new references we don't usually see in a web application, Microsoft.ApplicationServer.Caching.Core and .Client.


Remember that for security everything is locked down by default, so you'll need to grant access to the cache for whatever user you'll be using to access it. I'm running as "ScottHa" so I'll run

Grant-CacheAllowedClientAccount scottha

...and you should do the same for whatever account your IIS is running as.

Use Your Memory Cache from ASP.NET

Remember that you can chop up your memory caches into logical buckets (partitions) and a memory cluster can serve more than one application, if you wanted.

Your cache can be hooked up in the web.config or from code (however you like). Here's a code example helper method where the sample does this manually. This data could come from wherever you like, you just need to tell it a machine to talk to and the portnumber. It'll automatically connect to the

Caches can also be partitioned. For example, I'm using a named cache called "default" but I could have multiple logically segmented areas like "shoppingcart" and "productcatalog" if I wanted.

using Microsoft.ApplicationServer.Caching;
using System.Collections.Generic;

public class CacheUtil
private static DataCacheFactory _factory = null;
private static DataCache _cache = null;

public static DataCache GetCache()
if (_cache != null)
return _cache;

//Define Array for 1 Cache Host
List<DataCacheServerEndpoint> servers = new List<DataCacheServerEndpoint>(1);

//Specify Cache Host Details
// Parameter 1 = host name
// Parameter 2 = cache port number
servers.Add(new DataCacheServerEndpoint("mymachine", 22233));

//Create cache configuration
DataCacheFactoryConfiguration configuration = new DataCacheFactoryConfiguration();

//Set the cache host(s)
configuration.Servers = servers;

//Set default properties for local cache (local cache disabled)
configuration.LocalCacheProperties = new DataCacheLocalCacheProperties();

//Disable tracing to avoid informational/verbose messages on the web page

//Pass configuration settings to cacheFactory constructor
_factory = new DataCacheFactory(configuration);

//Get reference to named cache called "default"
_cache = _factory.GetCache("default");

return _cache;

Once your cache is setup, it's trivial to use.

m_cache.Add(orderid, order);


Order order = (Order)m_cache.Get(orderid);

or updating an existing object:

m_cache.Put(orderid, order);

Check your Caching Statistics

So after adding a bunch of items to the cache, then requesting a bunch back I can go into PowerShell and see what's going on:

C:\> get-cache

CacheName            [Host]
---------            ---------------
default              [HANSELMAN-W500:22233]

C:\> Get-CacheStatistics default

Size         : 2493
ItemCount    : 5
RegionCount  : 5
RequestCount : 17
MissCount    : 3

You can use Performance Monitor as there is an imperial buttload of different Performance Counters Available. As I mentioned, you can make different partitions, like "default" or "poopypants" and check the stats on each of those separate, or the cache as a whole:

AppFabric Velocity Caching in PerfMon

And of course, I can recycle my webserver, start it up again and fetch an order and it's still there. You've effectively got a big, partitionable distributed (and optionally highly available) hashtable across multiple machines.

Diagram Explaining what AppFabric looks like as an architecture

Replacing ASP.NET Session State with AppFabric Caching

If you want, in ASP.NET 4 you can also swap out the default in-memory Session State Provider for AppFabric via your web.config. Here's an example web.config.

<?xml version="1.0" encoding="utf-8" ?>

<!--configSections must be the FIRST element -->
<!-- required to read the <dataCacheClient> element -->
<section name="dataCacheClient"
Microsoft.ApplicationServer.Caching.Core, Version=,
Culture=neutral, PublicKeyToken=31bf3856ad364e35"

<!-- cache client -->
<!-- cache host(s) -->

<sessionState mode="Custom" customProvider="AppFabricCacheSessionStoreProvider">
<!-- specify the named cache for session data -->

Resources and Links

Here's a recent AppFabric caching slidedeck from Ron Jacobs I found useful. More links below. Microsoft Windows Server AppFabric Slides at SlideShare.

As with all things, a little abstraction goes a long way. If you have an existing caching strategy (via EntLib, or whatever) you can almost certainly swap out your internal storage for AppFabric Caching.

Related Links

About Scott

Scott Hanselman is a former professor, former Chief Architect in finance, now speaker, consultant, father, diabetic, and Microsoft employee. He is a failed stand-up comic, a cornrower, and a book author.

facebook twitter subscribe
About   Newsletter
Sponsored By
Hosting By
Dedicated Windows Server Hosting by ORCS Web
Thursday, 01 July 2010 22:56:13 UTC
Thanks, this really looks easy.

I can't remember how many times I've mentioned 'Velocity' to clients recently (last year or so) but always with a caveat "it's still in beta/ctp". Now I can just go for it :)

If only Microsoft would separate the caching story from the cloud related initiatives and update the documentation so that words 'beta' are no longer scattered all over the Velocity documentation, I think a lot of people would gladly embrace this technology.
Friday, 02 July 2010 00:11:40 UTC
I agree that 'a little abstraction goes a long way'. It's a shame then that the BCL team didn't speak with the Velocity/AppFabric team and have the System.Runtime.Caching namespace and its ObjectCache base class conform to the AppFabric caching API, or vice versa. Maybe there is an adaptor layer somewhere? If not, I may consider building one, as I have had a bit of experience subclassing ObjectCache in building my Ehcache REST client wrapper for .Net.
Friday, 02 July 2010 00:19:58 UTC
thanks for the post.

Why is enterprise needed for high availability ? is it a licensing thing or does it use windows clustering services ?
Friday, 02 July 2010 04:06:11 UTC
Has anyone done/know about how the performance compares with the session state service ?
Friday, 02 July 2010 08:04:41 UTC
Scott, a question I've asked a few times at recent Microsoft events but not managed to get any update on - when will we be able to get AppFabric Caching hosted on Azure? This would be the killer feature of Azure for me ...
Friday, 02 July 2010 09:42:13 UTC
Thanks for sharing this guide of installing and configuring the "Velocity" memory cache. It really helps me.
Friday, 02 July 2010 10:16:57 UTC
Really nice guide, thanks Scott. One other thing is starting the cache cluster automatically. I know that previously (think with Beta 1) the service was called 'Microsoft project code named "Velocity" CTP4' and was set to manual start, instead of automatic, and so that's why you need to manually start up the cache cluster.
Friday, 02 July 2010 12:21:04 UTC
Scott, for your international readers, what's the conversion ratio of "imperial buttload" to "metric buttload"? :D

All joking aside, great article.

@ed gillett> That seems like it'd be pretty easy to setup using Azure worker role instances, no? Or did you mean as a separate (and ideally cheaper...) service a la Azure Tables?
Friday, 02 July 2010 14:46:05 UTC
I can't wait to play with this and see how it scales.

As a big nit-pick, a part of me dies inside when I still see non-generics like this:
Order order = (Order)m_cache.Get(orderid);

I mean, this was started after 2.0 came out, right?
Kelly Stuard
Friday, 02 July 2010 15:38:29 UTC
Thanks Scott! I've been pitching hard to use this as our new caching solution. From my understanding, the cluster size you set during installation is a one-time operation that optimizes the cluster accordingly. Do you know of any guidance around the hardware for the cluster or thresholds for scaling up?
Friday, 02 July 2010 15:52:57 UTC

For ASP.NET session state, the DataCacheSessionStoreProvider does not require ASP.NET 4. It works fine with clients running on 3.5 SP1 and will work on Windows Server 2003. Users will need to download the client libraries for Windows Server 2003, Windows Server AppFabric - Windows Server 2003 Distributed Cache Client.
Friday, 02 July 2010 16:12:27 UTC

You say
security everything is locked down by default
One area that I have yet to find solid documentation is regarding locking down the communication between clients and the servers, and between servers. We all know that AppFabric Caching (Velocity is much easier to say) just uses WCF and .NET TCP bindings. Is the communication between cache servers locked down by default? We store very sensitive patient health care information in session/cache. Having this information sync'ed between servers unencrypted goes against our security threat assessments. Links to sample configurations would be apprecicated. I will look at the Windows Server AppFabric Samples.
Saturday, 03 July 2010 00:22:48 UTC
Good post. But one things I have yet to see answered: if I don't need to distribute my cache across multiple servers, is there a benefit to using App Fabric instead of normal ASP.Net cacheing?
Saturday, 03 July 2010 01:12:03 UTC
If you do not need higher availability of multiple servers, then from my perspective, AppFabric Caching does not add any additional value over ASP.NET State Server. ASP.NET State Server and ASP.NET caching are not exactly the same. ASP.NET caching uses the ASP.NET inprocess store. When you application pool recycles, your cache is gone.
Saturday, 03 July 2010 06:16:02 UTC
With regard to using AppFabric for caching over "regular" ASP.NET caching, that's a subtle question. If you have node affinity and you are caching inproc, then "Velocity" adds little other than marshalling overhead. However, if you're using Out of Process Session State Service now, then using Velocity not only gives you the option to scale out more and get redundancy, but it also gives you a LOT more performance counters as well as the PowerShell administration. Also, the Velocity cache, of course, will persist across IIS recycles.
Sunday, 04 July 2010 17:02:03 UTC
Thanks. Great article.

Checked out AppFabric this weekend, wrote a blog post about it:

and will definitely be advocating its use at work tomorrow.

Monday, 05 July 2010 05:21:21 UTC
I was able find the configuration documentation on security. As Scott stated, the default security options are secure. The default for client/server and server/server communication is to use transport security and to encrypt and sign. See the section Security Settings on page
Windows Server AppFabric Caching Configuration Settings.
Thursday, 08 July 2010 14:05:37 UTC

when configuring the place to store the Cache configs you can pick from UNC Share and Database. However, looks like the database storage is only available if the Velocity host is located inside a domain. Otherwise, in a DMZ environment, it won´t allow me to use the database. Is that correct? Is there a way to use the database to store the config when the host machine is not inside a domain?

Wednesday, 14 July 2010 17:43:25 UTC
This is memcache and it exists in open world ages. Guys I wonder what you will do when MS release something like Cassandra or Hadoop which is counterpart of GRidFS from google?.. You will do nothing because MS will not release it because of simple reason (although they already have it) : they have got no idea how to license it. Hehehe good luck in your shrinking world!
Wednesday, 14 July 2010 18:05:48 UTC
I got an error saying could not load type "Microsoft.ApplicationServer.Caching.DataCacheSessionStoreProvider" when I used the example webconfig for session state. So I used 'type="Microsoft.ApplicationServer.Caching.DataCacheSessionStoreProvider, Microsoft.ApplicationServer.Caching.Client, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35"' and it worked.

Here is the webconfig area that I changed.

<sessionState mode="Custom" customProvider="AppFabricCacheSessionStoreProvider">
<add name="AppFabricCacheSessionStoreProvider"
type=<b>"Microsoft.ApplicationServer.Caching.DataCacheSessionStoreProvider, Microsoft.ApplicationServer.Caching.Client, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35"</b>
Friday, 16 July 2010 05:57:49 UTC
Installing and Configuring is not so simple when the machine is not on a domain, only XML config is enabled and the share required full access privelleges.

One issue I have found is that the Microsoft.ApplicationServer.Caching.Client and Microsoft.ApplicationServer.Caching.Core assemblies are not visible in VS 2010 (x64) unless you browse for them in the System32/AppFabric directory, although when I check in the GAC the dll are there.

Is there a solution to that?
Friday, 16 July 2010 10:20:21 UTC
use sysnative/AppFabric instead of system32/AppFabric on x64 systems when looking for the dir.
Friday, 16 July 2010 16:33:40 UTC
Scott -

I've been trying to talk up AppFabric at work and get our Infrastructure people some information about Caching. The MSDN page however has a broken link on the "Getting Started" page. I sent a message to the feedback about the problem on July 1st and actually got a message back from the MSDN team saying they would fix the problem. The problem still exists 15 days later! For a product that has just released this is pretty sad. Hopefully you have more pull.

On the following page, click on the Getting Started link...
Windows Server AppFabric Caching Features

Friday, 16 July 2010 18:30:48 UTC
Mike - I'll call them now.
Saturday, 17 July 2010 03:15:46 UTC
Mike - the link on MSDN is fixed now.
Monday, 19 July 2010 08:27:13 UTC
Thank you very much for providing us this guide! it has helped me a lot making velocity work in my apps!
Thursday, 22 July 2010 13:27:57 UTC
Thanks Scott!
Saturday, 31 July 2010 15:42:10 UTC
While installing/setting up AppFabric I get monitoring is not configured, when I try and configure it it asks me to choose a database which one shall choose.

Tuesday, 03 August 2010 16:36:15 UTC
Can we install it to a standalone windows server 2003?
Friday, 06 August 2010 14:08:18 UTC
When I googled, use appfabric as state server and saw your name in the first result, I knew it was the place to go. You even provided the exact text to use in the web.config. Thanks as always.
Jeff Kyker
Saturday, 14 August 2010 00:07:56 UTC
IT also works on windows 7 for testing and development
Friday, 20 August 2010 14:22:22 UTC
Hi Scott,

I was previously using Beta1 I believe. I've now upgraded to the release, and changed my config to use the updated namespaces. But now I get the below error message, with the type of the session state provider being highlighted in red:

ErrorCode<ERRCMC0003>:SubStatus<ES0001>:Error in client configuration file.

Below is my relevant configuration pieces (with the types being split on multiple lines, in reality they're on one line):

Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />

<dataCacheClient deployment="routing">
<localCache isEnabled="false"/>
<host name="myhost" cachePort="22233"/>

Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35"

Any ideas as to what this means, I can't find any information.


Friday, 20 August 2010 14:27:51 UTC
Oh, and also - the server is running Windows Server 2008 R2, and my dev box is Windows 7... do I just have to include the two libraries into my web app for it to work, I think I had appfabric stuff installed onto my dev box, but I'm not sure if that should make a difference
Friday, 20 August 2010 14:43:10 UTC
Seems it was my configuration was incorrect. I was sure the snippet I posted above wasn't working, but seems it is :) See my StackOverflow post for the actual listing. It was the
attribute on the host that was causing the issue I believe.
Monday, 30 August 2010 10:29:44 UTC
... and the
Thursday, 09 September 2010 10:17:47 UTC
I get an error on the line of code:
_cacheCatalog.Get (strKey, CATALOG_CACHE_REGION);

The error is : An item with the same key has already been added.

I can not understand why I have this error on a Get method "?

Thank you very much for your help

Soulaymane Bouyardane
Friday, 08 October 2010 03:05:16 UTC

I'm confused as to why there is a SQL Server config databas yet you have to pass in a list of all the cache hosts/servers when creating the DataCachFactoryConfiguration object in order to get the factory?

Wouldn't you just provide the details of the SQLServer config DB where all these hosts would be registered?

What am I missing?

Monday, 10 January 2011 16:04:40 UTC

Installing this on IIS7 Server 2008 R2 now. Not in a domain (staging server) Neither is our webfarm. Man this is a bitch to install..

Some hints,
1) As earlier written, only XML, no SQL.
2) Not service accounts, you will have to create a user to run the Caching service, make sure this user has Access this computer from the network right. Otherwise it will just popup an error saying user does not have requested logon right.
3) The installer package downloaded (3 times) gave a this package is not for this machine (running 64bit sql2008 r2), the web platform installer suggested to install the 32bit version, so thats what i did and that worked.. (64bit frameworks of dotnet are installed, so not sure whats the problem here. I already installed this version on dev servers and laptops).
4) webplatform installer insists on installing the sql 2008 express service., I dont want that on my webserver since it will not use it (no domain).
5)Now I'm stuck on the network share it needs. Gave my created service user user full controll and access permission. But the installer says, access denied.. You will have to add your own account running the installer access permission to the share. I'm hoping to remove this after finishing the installer.

This feels so half finished... It does not give me the confidence to push it as our webfarm solution..
Monday, 10 January 2011 18:03:59 UTC
another thing hard to get working in workgroup mode is security.

For now I had to disable security on client (web.config) and server:

Server, appfab powershell cmd: Set-CacheClusterSecurity -SecurityMode None -ProtectionLevel None
Client, web.config:
<!--appfabric cache client -->
<!-- cache host(s) -->
<host name="localhost" cachePort="22233"/>
<securityProperties mode="None" protectionLevel="None" /><!-- this is stopping sending security credentials to the caching service-->
Comments are closed.

Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my employer's view in any way.