Streaming a vCard on the Fly in ASP.NET with a Custom httpHandler
To continue with my series on httpHandlers I want to cover how to stream a vCard to the user based on a parameter. First let me say that I grabbed the code for the .NET vCard class from a CodeProject.com article. There is also a corresponding vCalendar class. The idea behind a vCard is it is a standard format for sharing information about a person that can be imported directly to applications like Outlook.
The first thing to do in building the vCard httpHandler is to add a Generic Handler to the Web site. This can be done just like adding a page to the Web site, instead of selection a WebForm you would select Generic Handler from the Add New File Dialog. This will add a new file to the site with the .ashx extension. The 'h' indicates it is a handler, just like the 'p' in aspx indicates a page.
The file itself is a code page, that is either a VB.NET or a C# class file. There are two members in the httpHandler class, ProcessRequest and IsReusable property. By default the IsResuable property is set to False, which will suit our needs.
The ProcessRequest method is the workhorse for the handler and it is actually called by the ASP.NET engine to let the handler produce the output to be sent to the client. The ProcessRequest method has one parameter, the current httpContext of the request. This gives us access to everything we need to output a customized stream of formatted text, binary content or just about anything else we can possible send to a client across the wire.
Public Sub ProcessRequest(ByVal context As HttpContext) Implements IHttpHandler.ProcessRequest
'Place Code to Stream vCard here
Public ReadOnly Property IsReusable() As Boolean Implements IHttpHandler.IsReusable
The first thing we need to do to stream a vCard to the client is to set the ContentType of the response. In this case a 'text/directory' value, which indicates we are sending text and some sort of directory type information. If this were a normal HTML Web page it would be 'text/HTML' and a PDF would be 'application/PDF'. There are numerous possible values that can be passed at this point, and this deserves another entry for the Blog so I will leave it at this for today.
context.Response.ContentType = 'text/directory'
Now we can build our vCard class. For demonstration purposes I am just going to show how to build one in a hard coded manor, but you can substitute however you are going to retrieve user information. This could be from a database, Active Directory or where ever you store your personal data. Again for details on how this vcard class works refer to the CodeProject.com article.
Dim vc As New
vc.FirstName = 'Chris'
vc.LastName = 'Love'
Dim _address = New vCard.vAddress()
_address.AddressName = 'Home Office'
_address.City = 'Willow Spring'
_address.State = 'NC'
_address.Zip = '27592'
For more practical uses you would typically get a parameter either through the Form or QueryString. Because the ProcessRequest method receives the current context these parameters are accessible. Typically you will need to process the QueryString, which would be context.Request.QueryString('UserName') for example.
We are almost done with the code. To actually place the vCard content in the output stream you pass the Response.Write method the vCard string. The vCard class I am using has a ToString method that outputs the vCard according to the vCard RFC. The Response.Write method writes the string to the output stream, so this is the actual content that will be rendered in the browser. Because we set the ContentType, typically this means it will try to open an associated application for the content type.
Finally you just need to call the Response.Flush and Response.End methods. The Flush method sends the content to the browser and the End method ends the request. You can actually push data to the browser as it is being built in an httpHandler and continue processing more output by using the Flush method. You can continue doing this until the End method is called. The End method stops all execution for the current request.
One more thing is left, registering our custom handler with the vCard extension, .vcf. To do this we need to do two things, set the Mime Type in IIS to process .vcf through the ASP.NET engine and in the web.config file. As far as how to set the extension mapping in IIS I covered the fundamentals of this in a recent Blog entry on handling wildcard extensions in IIS.
In the web.config file we must associate the .vcf extension to the custom httpHandler. This is done in the httpHandlers section of the config file. You simply add the handler by defining the verbs, such as Get and Post, the extension and the actual handler class we have built.
<add verb='GET,HEAD' path='*.vcf' type='vCardHandler' validate='false'/>
Now that we have built our custom vCard httpHandler class, registered the vCard file extension with IIS and the custom handler with the extension we can start retrieving vCards from our Web site. if we have done everything correctly you will be prompted to either open or save the vCard. If you have an application, such as Outlook, associated with the .vcf extension an you select Open it will open open the vCard in the application. From there you can typically store it in the address book. Of course saving it will place the file on your hard drive.