I am building my own blog engine for fun (I just want to learn how this all works) and figured I should start with support for Windows Live Writer since I wanted to make sure my database supported whatever structure Writer supported. This turned out to be a fairly challenging project so I decided I would write an article that walks through the steps of creating a basic provider to hopefully help other developers (and maybe future me ) get something up and running quickly.
First off, you should know that Writer uses a combination of MetaWeblog, Movable Type, and WordPress. These are all XML-RPC based APIs. In fact Writer can actually use subsets of these APIs so you can decide what you want to support. You can learn more about this on Microsoft’s site: Windows Live Writer Provider Customization API.
To make your life easier, you should download the Xml-Rpc.Net library created by Charles Cook. This library provides everything you need so you don’t need to worry about the Xml-Rpc protocol. You will just need to create a service with the right methods and the Xml-Rpc.Net library will handle the xml for you.
If you are building your service in .Net 4 you will want to make a change to the library before using it in your project or you might end up with a server error (I reported this to Charles so it might be fixed by the time you download the library). Basically you will want to apply SecurityCriticalAttribute to CookComputing.XmlRpc.XmlRpcFaultException.GetObjectData (src\XmlRpcFaultException.cs, line 76).
public override void GetObjectData
Once you’ve gotten the Xml-Rpc.Net library compiled and ready to go, you can now start creating your project. I’ve created an example project that you can use as reference for your project. The project was created from an empty web project in Visual Studio 2010 and was largely borrowed from Keyvan Nayyeri’s excellent article on this subject.
Download Example Project (look for the Download button)
If you prefer, you can just look at the code in the CodePlex repository, but you won’t be able to run it from there. The code does include a modified version of the Xml-Rpc.Net dll that works with this project.
The first file to look at in the project is the MetaWeblog.ashx file. This file is the common extension used to define a web handler. This one defines the backing class as LiveWriterExample.MetaWeblog.
The next file to look at is MetaWeblog.cs. This file contains the service contract interface IMetaWeblog and the class MetaWeblog (this is the class pointed at in MetaWeblog.ashx). All the methods on the interface have an XmlRpcMethodAttribute applied to them. The name provided is the name of the method as defined in the MetaWeblog API (this is the best reference for what Windows Live Writer supports).
The MetaWeblog class implements the IMetaWeblog interface. This is the critical code for you to modify if you want to create your own provider. Just look for the TODOs and change out the logic with your own.
The MetaWeblogStructures.cs file contains the code for the structures used as parameters and return values. Xml-Rpc.net automatically creates and populates the parameters from the xml being sent in and converts the return values into the correct Xml-Rpc response.
If you are wondering how Writer knows how to call into your provider, the answer starts in the Default.aspx file. The header of this file includes a link tag that defines the location of the RSD file. RSD stands for Really Simple Discovery which is an xml document that identifies what services are exposed by a website. The MetaWeblog node includes the url to the ashx file. The node also includes the id for the blog so if your blog engine supports multiple blogs, you will need to make this dynamic so that it returns the correct blogid.
The last file that we are going to look at is the wlwmanifest.xml file. This file contains Windows Live Writer specific configuration. It allows you to customize Writer to include features that your blog supports and exclude features it doesn’t. You can even include custom tools! Writer can find this file by either convention (eg, http://myblog.com/wlwmanifest.xml) or using a link tag in the blog page. Read Discovering and Downloading Manifest Files for more information. To keep things simple, the sample project removes almost all the options.
Running and Debugging the Project
To test the provider, simply run the project, copy the url, and use it to add an account to Windows Live Writer.
A few notes about debugging:
- The sample project will accept any username and password, so no need to set one up.
- Do not download the blog theme. This isn’t a blog engine, it is just the provider so there is no blog theme available.
- The account doesn’t show up in Writer (at least not the version I have) until you restart Writer.
- The sample project stores all the information in memory. Any posts that were created will be lost once you stop debugging the project.
- If you are interested in seeing the raw xml, you can put a break point in the MetaWeblog.Invoke method. I modified the XmlRpcRequest object in the Xml-Rpc.Net library so that it contains the XmlDocument that is sent for the xml-rpc request.
- Fiddler is a great way to see what requests Writer is making to your provider. However, if you are testing with localhost, you will need to slightly modify the url to your provider when adding the account. Instead of localhost:12345 (or whatever your port is), try localhost.:12345 (notice the dot after localhost). If you don’t include the dot, fiddler will not capture the traffic.
- If the service is running but Writer cannot create an account, try adding a break on Exception for all exceptions.
- I cannot figure out how to populate the Service Name in the account details. I verified that the node name in wlwmanifest.xml is correct.
This article is littered with resources that I have found invaluable for learning how to create my own blog engine. To make it easier to find them, I figured I should provide a nice ordered list.
Have fun writing the next greatest blog engine!