BlogEngine.NET is an open source blogging platform on which I run both my blogs (this one and the other one). Whereas this blog has the benefit of being based on BlogEngine.NET 1.4.5 from conception, my other blog has been around a little longer and so got its start on version 1.3. I've been meaning to update it to the latest version for a while; this guide will document that process. If all goes smoothly, this step-by-step approach should mirror Al Nyveldt's excellent BlogEngine.NET 1.4 Upgrade Guide. If not… well, we'll see how it goes and hopefully come up with solutions for whatever problems arise.
The Steps
1.) Make a backup of your web site
It's a good idea to have a "back out" plan in case something goes wrong or you back yourself into a corner (or run off a cliff). Make a backup now. You'll be thankful you did.
I copied everything from my site to a new, local folder called "BlogEngine.NET 1.3 (backup)". This way it's there in its own separate folder, ready to get copied back to my web server if necessary.
2.) Download BlogEngine.NET 1.4.5
You can get the latest and greatest version of BlogEngine.NET here. As of this blog post (and as the title denotes), version 1.4.5 is the current release. At minimum, you'll need the web site zip. I also downloaded the latest source (core) zip; I like to keep a copy of it around in case I need to make any tweaks. It's open source, remember.
3.) Unzip the web site files into a new folder
Unzip the web site zip into a new folder. This is going to be your new 1.4.5 web site. I wouldn't recommend overlaying it on top of your existing files. Keep it separate. Save yourself some headaches. Remember, we want an easy back-out path in case things don't go so well. If you leave your old structure intact, no harm done.
4.) Remove the "read-only" attribute
Right-click on your new folder, select "Properties", and remove the "read-only" attribute from all files and sub-folders.
5.) Copy "App_Data" from your current web site to your new one
You want to use the new 1.4.5 folders and files in your site while retaining your existing data. To that end, copy the contents of your current "App_Data" folder (you can get it from the backup you made in step 1) into the App_Data folder of the 1.4.5 web site. Don't delete the contents of the new 1.4.5 App_Data folder first; there are folders and files in 1.4.5 not in 1.3 that we want to keep.
6.) Copy user controls & other "stuff"
If you're like me, you've written some of your own user controls, maybe tweaked your favorite theme, or even modified some of the BlogEngine.NET web controls. This is your opportunity to carry all that stuff forward.
Copy each of the following:
a.) User Controls
Copy any user controls you wrote yourself, borrowed from other people, or tweaked your 1.3 "User controls" folder into the new 1.4.5 site's "User controls" folder. The default 1.4.5 site only comes with two: CommentView and PostList. A quick file comparison shows that these have been updated from 1.3, so leave those alone and just copy in your own.
b.) App_Code controls
Similar to user controls, I also tweaked some of the controls found at "App_Code\controls". Copy any you made changes to into the "controls" folder under the 1.4.5 site's "App_Code" directory.
c.) Admin Pages
I also had created some admin pages of my own. These are stored in "admin\pages". If you have any beyond the defaults, copy those to your new site folder.
d.) pics & images
This is getting a little messy, but it looks like I also have some of my own additions to the "Pics" folder, which exists outside the App_Data location. In addition, I have an "images" folder. If you have your own pics, images, or anything else, copy them over. Consolidation of these folders is getting added to my "to do" list.
e.) themes
I also made quite a few changes to my theme of choice (the "standard" theme). Mostly small tweaks to get the right look and feel I was after, but enough that I also copied over my modified standard theme on top of the existing one.
7.) Open the web site project
I'm using Visual Studio 2008, but prior versions should work. You can open the web site project itself or add it to an existing solution. I took the latter approach. When faced with this dialog:
I selected "Yes". Al Nyveldt recommended selecting "No", but I use controls from the AJAX Control Toolkit 3.5 in my site, so I need .NET 3.5.
NOTE: Allowing the site to be updated to .NET 3.5 did not seem to have any adverse side-effects.
8.) Build and run it
At this point you should be able to build the web site and run it. I got lucky: no errors or warnings. Even better, the site came up and looks exactly the way I expected.
9.) Use an encrypted password
If you aren't already using a custom provider to encrypt your password, or if you just want to switch over to the default BlogEngine.NET encryption, open up your "users.xml" file in the App_Data folder. Previous versions of BlogEngine.NET saved your password as clear text. While that's been a major point of contention in the past, it's fixed now.
If you see your password in clear text in the users.xml file, Al recommends blanking it out:
Al then recommends logging in with just your username and no password. Were this that easy we could just move on to the next step. I reset my user id in users.xml to "Admin", blanked out the password, and gave it a shot. What I got was this:
Clearly trying to login with a blank password isn't going to work.
Here's what I did to get around this:
a.) Open up the users.xml file in the default web site you downloaded earlier. You'll see the default Admin login along with this:
<Password>jGl25bVBBBW96Qi9Te4V37Fnqchz/Eu4qB9vKrRIqRg=</Password>
Turns out this is the encrypted form of the word "admin".
b.) Copy the encrypted password into your own users.xml file. Save it.
c.) Login using your username (or "Admin" if you used the above screen shot as a guide) and a password of "admin".
d.) Edit individual id's and, of course, change the admin password or delete the id altogether.
Not sure how Al was able to login with a blank password. In any case, the above procedure worked for me.
10.) Deploy the new site
Once you're satisfied everything is in place, FTP to your site and deploy the new site. Al recommends wiping the slate clean: delete everything to start so as not to leave any orphaned files out there. If you created your new 1.4.5 site as I described above you can then ftp its entire contents as is. If you did not copy your most current App_Data folder into the new, local site, then don't copy your App_Data folder. You'll overwrite your existing data. Also, if you just want to be ultra-safe, just copy everything but the App_Data folder. Up to you.
Personally, I'd rather have a few orphaned files out there than take the chance of missing something crucial. I did an overlay of the new site onto the old.
Conclusion
If all went well, you should be done. Go to your site and verify it works as expected.
Some Addendums
All did not go as smoothly as I would have liked. While I tried to exclude any snafu's that might have arisen solely because of my own proprietary changes or mistakes, I wanted to at least throw some of these things out so that if others run into the same problems, either someone can enlighten me as to the cause or we can at least try to figure it out together.
1.) XML Parsing Error on login/logout
I had a lot of issues with getting my id/password back to the defaults so I could then enter a new password and have it encrypted. One such problem was this "XML Parsing Error":
I got this a number of times both when trying to login and logout. Ultimately, I had to copy over the default users.xml and roles.xml. Even that didn't do it until I restarted the ASP.NET development server and switched browsers. I can't tell you exactly what made the above screenshot go away… if anyone knows and wants to share, post a comment.