With the final release now out the door, I want to take a little time to walk you through the process of upgrading your version of BlogEngine.NET.
As you’d expect, the upgrade process is fairly easy, however, I try to go into lots of details to cover as many different scenarios as I can. While the following guide is long, I fully expect, most of you will be able to skip a section or two along the way and be upgraded quickly and painlessly.
This guide was written from the perspective of upgrading from 1.4.5 to 1.5. If you were one of the people who tried out the 1.5 release candidate, this will work fine for you too. If you are using an older version, it would be best to read this over, but also to look at some of the past upgrade guides to learn about some other important changes.
1. Backup
This is my favorite step in the process. If you do this, there should be no fear of upgrading and in the horrific case of a problem, you can just revert back to your backup.
If you can’t bring yourself to backup the whole blog, be sure to at least get your App_Data folder, your themes and extensions, and your web.config file.
2. Download BlogEngine.NET 1.5 (web)
I’m sure you have already done this step, but if you haven’t, this is the time. You can download it here.
Once you have it downloaded, go ahead and unzip it and then remove the read only check in the properties. (apply to all subfolders and files).
3. Update your data and configuration
If you use the default XML data storage, you can move along to the next step. If you are not sure, you are likely using the default option, so you should move on too.
Welcome database person. It is time to update your database. It is a small change, but required.
In the newly downloaded BlogEngine folder, you will see a Setup folder. In this folder is a folder for each of the supported databases, MySQL, SQLite, SQL Server, and VistaDB. Find the one for the database you use and open the folder.
There is a readme.txt in the folder with instructions on upgrading. There should also be an upgrade script for your database and a new web.config file that you will need to put in place.
The web.config has changed since 1.4.5 and it is easiest to just use the new version that is included in the download and add your connection string info to it. If you made other changes, than you are on your own.
If you are using the SQLMembershipProvider and SQLRoleProvider, you’ll want to make sure you make this change in your web.config. We are defaulting to the DbMembershipProvider and DbRoleProvider to keep things simple.
4. Update your web server
We should be ready to start copying files to our web server. If you skipped step #1, this is your last chance to do that.
I find it smoothest to remove all the blog files and folders I don’t plan to keep first. Since I have a backup, I keep my App_Data folder and remove the rest. (I will put back my themes, extensions, and widgets later.)
Uploading to a remote web server can take a while. Be patient.
5. Security
This is not something to be concerned about unless you are upgrading from an older version, but I wanted to mention it for those coming from 1.3.1 or older. Please read the old guide to get the scoop. If you are a more current user, you can hold your head up high and move on to step #6.
6. Themes and Extensions
If you are using a custom theme, you will need to upload it right away. Any special widgets or controls you might be using will need to be there too for the theme to start up properly.
Make a note of what files you are putting out to your web server in case you have issues. If trouble arises, I’d start by switching themes to the Standard theme to make sure the default setup is working for you.
7. Open your site in your browser
It will take a few moments the first time around, so don’t panic if it does not come up right away. In a moment or two, if everything is well, you will see your blog.
If you have an error or display issue, take a look at the troubleshooting section below.
8. Clean up
If you didn’t copy all any themes, widgets, or extensions out, now is the time to do so. Refresh your browser once they are copied to have them take effect.
9. Theme updates
If you are not using one of the default themes, you’ll want to take a look at the comment form. A few tags were changed here and you may want to change the css for the comment section. Also, if you plan on enabling Nested Comments (see the Settings page), you will want to make some adjustments to your theme to handle it. See the comment view documentation page on our wiki.
Enjoy the goodness that is BlogEngine.NET 1.5!
Troubleshooting
Don’t fret. Any problems you’ve had have likely been seen before. Below are a few common things to check. If these don’t help, please head on out to the BlogEngine forums. If you can’t find the answer searching there, make a new post and ask for help.
Compile Errors:
- Are you running MySQL, SQLite, or VistaDB? Are you sure you are using the version of the DLL listed in the web.config?
- If you are using MySQL or SQL Server, do you have the correct connection string in your web.config?
- Did you clean out all the old BlogEngine files or did you just overwrite them? Did an old file get left in place?
- Did your FTP program miss a few files? It would be a good idea to make sure everything is uploaded.
- Did you have a customized web.config before? Did you merge the changes in? Or are you using your old web.config?
BlogEngine Issues:
- Can’t login? Were you using the SQLMembership Provider before and forget to configure it? If you are a DbMembership or XMLMembership user, you can clear out the password and log in with “admin”.
- An application restart might help if you are locked up.
If you are still having an issue, please head on over to the forums. Search first as someone has likely already had the same issue, but if not, please ask.
Good luck and Happy Blogging!
With a new release now available, I wanted to write up another guide for those looking to upgrade their blog. The basic upgrade process is as always fairly simple, but I’m going to branch out and cover more special circumstances. The guide might seem a bit long, but you aren’t likely to be concerned with all the steps.
1. Backup
If you’ve read my guides before, you know I’m a big fan of the backup. If you back it all up and something goes horribly wrong for you, you can just pop in back in place and start again.
I should note that I when I upgraded my blog to 1.4.5, I skipped most of this step. I backed up my data and my themes and extensions. Then, I just went for it and I felt bad knowing that I was going to tell everyone to back it all up. So I’m confessing now as part of my guide that I skipped this. I do however wish that I had a full backup. (Not that I lost anything, but it would make for a great screencast to show you exactly how I upgraded my live blog.)
2. Download BlogEngine 1.4.5 (web)
If you haven’t already, now is the time to download the BlogEngine.NET software. I recommend the web version as it is all ready to go. Get it here if you don’t already have it.
Now that you have it, unzip it and remove the ready only check in the properties (apply to all subfolders and files).
3. Update your data and configuration
If you use the default XML data storage, you have nothing to do here as usual. If you are unsure, you likely fall in this category. Take a moment of silence for your database brethren and move on.
If you are using a database, then you have a little work to do. In the Setup folder, there are 4 folders, MySQL, SQLite, SQLServer, and VistaDB. If you are using on of these databases, open the folder, read the readme.txt file and follow the instructions. There is an upgrade script and a sample web.config.
The web.config has changed since 1.4 and I would recommend you use the version included in the setup folder. If you are using MySQL or SQLServer, you’ll need to move your connection string over as well.
If you were using SQLMembershipProvider and SQLRoleProvider, you’ll need to configure these in your web.config. To make things easier, we have made the dbMembershipProvider and dbRoleProvider, the default database options in our sample web.config. I personally think the SQL versions are better options, but this is the easiest option for people to get setup and since the other database configs use them, it keeps things simple.
4. Update your web server
Now, we are ready start moving files to your web server. You do have a backup you can be proud of from step #1 don’t you? If so, you can begin to copy your new files out to your web server. It is always safest to remove all the folders and files you don’t want to keep before the copy. For me, these means that I keep my app_data folder and remove everything else before I start my copy. (I put my theme and extensions back at the end from my backup.) This way you are sure you have removed all of the previous version.
Anyway, uploading your site will be the longest step of the process. Be patient.
5. Security Thoughts.
If you are upgrading from BlogEngine.NET 1.4 and have converted to hashed passwords, you can skip this section, you’ve already dealt with it. If you are using BlogEngine.NET 1.3.1 or earlier, pay attention. We’ve upgrading the XMLMembership provider security to used hashed passwords by default. This means if you are using the default security model, you’ll need to need to make some changes. If you were using the SQLMembership provider, you can skip this as well.
If you fall into the category of people who need to make some changes you have 2 choices. The recommended choice is to convert to hashed passwords. To do this, you simply open your users.xml file (found in your app_data folder) and remove the passwords for each users. (Don’t delete the whole password line, just the password, so that the it shows no password.) Clearing out the password will allow you to use the password “admin” when logging in. You should then use the Change Password option to change the password to a better password. The new password will be hashed.
Your other option is simply to continue to use clear text for your passwords. To do this, open your web.config and find the Membership provider section. You can change the passwordFormat from Hashed to Clear. This option is not as secure and will require you to make this change with each upgrade of BlogEngine.NET in the future.
6. Themes and extensions
If you are using a custom theme by default, you will need to put this back in place before you try to browse out to your site. If you are using special widgets or controls in that theme that depend on widgets, they will need to be back in place too. The downside of putting them all in place before trying out the upgrade is they potentially could cause you issues.
Make a note of what files you are putting out on the web server in case you have issues. If issues arise, you can simply remove these files and manually change your theme to “Standard” to test the BlogEngine setup.
7. Open your site in the browser
It will take a few moments for your site to come up the first time around. If everything went well, you should see your blog as you remember it. If you have an error or display issue, see the troubleshooting section below.
If you just did the security upgrade in step #5, log in right away and get those passwords changed from “admin” to something else.
8. Clean up
If you didn’t copy all your extensions out in step #6, now is the time to do so. Copy them out, and refresh your browser. It will recompile so don’t be shocked by the delay.
Now is a good time to check over your settings and make sure everything is coming up as you expect.
Congratulations. You are upgraded.
Troubleshooting
Don’t panic.
There are plenty of things that could be causing you minor issues that can quickly be corrected. Here is a bullet list of things of things to check first.
Compile errors
- If you are using a custom theme, widgets, or extensions, remove them, set your default theme to Standard, and try again. You can change the theme in your settings.xml file or be_Settings table depending on your setup, xml or database.
- If you are using MySQL, be sure to add the system.data section to your web.config. (You can get this from your original web.config or from this post on the forums.)
- Did you really clean out all the files (except app_data) or did you just overwrite them? Did something get left over that is causing a problem? Or did your FTP program miss some files?
- Did you customize your web.config? Try the one included in the download. Using your old web.config will get you a nasty looking error.
- If you are using MySQL or SQL Server, please check your connection string.
Security errors
- Can’t login? Try clearing out your password as described in step #5. If that doesn’t help, try using the downloaded users.xml file and logging in as admin.
- An application restart might help out if you are really locked up.
- If you are using a database and the default dbMembershipProvider, you can clear your password in the be_Users table and try logging in as admin.
- Were you using the SQLMembershipProvider and did you configure it properly? It is not a default setup.
Display errors
- It has been reported that there have been some minor styling changes from 1.3.1 to 1.4.x. Custom themes may require some minor css updates to get them working. (I’m not sure what tags have changed as I didn’t have any issues with my custom theme in 1.4 or 1.4.5.)
- If you have an empty widget bar, you will need to re-add you widgets.
- If you just added the Administration widget and it shows up blank, refresh your browser and the options should show up.
Beyond these basics, I’d strongly recommend looking on the BlogEngine.NET forums and asking a question if you don’t see your answer after searching. Please provide as much detail as possible in your forum post. The forums are the best way to get help if you are having trouble.
This was fairly popular last time around, so I wanted to write this up and make sure it was available right away with the new 1.4 release. The upgrade process is fairly easy but there are a few things to be aware of. Hopefully, I’ll cover everything you could possible want to know on your journey from BlogEngine.NET 1.3.x to BlogEngine.NET 1.4.
1. Backup your stuff
If you read this last time, you realize that there is no warranty with my guide and you are strongly encouraged to backup your blog and blog data.
At a minimum, please backup your App_Data folder, any custom themes or extensions you may have, and your web.config especially if you are a database user.
2. Download BlogEngine.NET 1.4 (website)
This is likely the step you have already done. (If not, get it here.) Once you have it located on your PC, unzip it. Right click the folder, go to Properties and remove the Read Only check. (This step has helped some and has never hurt anyone.)
3. Update your database
If you are using the the MSSQL Provider and have your blog data stored in SQL Server, we have an upgrade script for you to run. It adds a few more tables and some basic data for them. The script is found in the Setup folder of the blog and it is labeled MSSQLUpgrade1.4.0.0.sql. Run this against your BlogEngine database.
4. Configuration… as in Web.Config
If you are a database user, you are going to have to make some updates to the web.config that you are about to upload.
First thing, you will want to add your connection string to the new web.config in the connectionStrings section.
Second, you will notice that the MSSQLBlogProvider is gone. (Its ok. It has gone to a better place.) It has been replaced with the DbBlogProvider. This is your new friend. Make sure you have your connection string name marked here and set the DbBlogProvider as your default BlogProvider. Save your changes.
5. Upload your files
This is a little bit tricker this time around so pay attention.
First, make sure you have a good backup from step #1. This is really your last chance to do that.
Now, you can upload everything except the App_Data folder. It is important to note that a few things have moved around and if you just choose to overwrite files, you’ll have some left overs. These leftovers should not cause problems for you (except noted in the troubleshooting section) but they just take up space, most notably the tiny_mce folder under the admin folder has been moved and can be deleted.
Once you have most files moved up, it is time to go into your app_data folder. In the downloaded project, you will see two new folders, datastore and profiles. Upload these to your site as well. (If you use a database for file storage, it isn’t require, but it is consistent.)
6. Security Update
If you use the default XMLMembership provider to store your passwords, this has been updated in in 1.4. We had been storing the password in clear text and this is no longer the default. If you wish to continue with clear text, you can set your XMLMembershipProvider passwordFormat to Clear in the web.config, but this is not recommended.
Since BlogEngine.NET 1.4 is looking for hashed passwords by default, you’ll be unable to log in unless we make a change to your user data. You’ll need to retrieve your users.xml file from your app_data folder. You should be able to see your users and passwords listed in the file. Remove the password from each entry user so it has an blank or empty password and save the file. Upload your newly edited file to your site when you are done.
This will cause BlogEngine to allow you to log in with each user using the password “admin” so that you can then change the password to whatever you’d like. The new password will be hashed.
7. Fire it up
Ok, now that we have everything out there, let’s run it. Point your browser back to your blog and after a few moment wait as your site compiles, you should see your blog back as you’d expect it. (If your blog doesn’t come up, see the troubleshooting section below.)
Now that you are up, first log in and use the change password option on your admin menu to change your password to something secure.
8. Check your settings
Everything is done, but it is always a good idea to Check your settings and make sure everything is configured properly. This would also be a great time to fill in your profile for FOAF support.
Troubleshooting
Hopefully, you are just reading this because you want to see what other poor souls are struggling with. The typical things that are going to cause trouble are custom themes and extension that were made prior to 1.4. If you have any installed remove them and try again. If you are still having trouble, try going into your settings.xml or be_Settings table and changing the default theme to be Standard.
If you are having trouble logging in to your blog, try an application restart.
If you have more tips or additions, please make them in the comments and I’ll update this post.
As we all know, installing BlogEngine.NET from scratch is a piece of cake. Upgrading, however, can cause people a bit of concern and it is easy to overlook something. Here is a guide for your journey to BlogEngine.NET 1.3 from 1.2.
1. Back it up
This is the standard first step to doing most anything. While I don't always do this step myself, I should and you'd be wise to as well.
At a minimum, backup your App_Data folder and any custom themes or extensions you might have done. SQL users should add the sql.config file as well as the database to that.
2. Download BlogEngine.NET 1.3 (website)
This is an easy and painless step. If you are reading this, you likely already have done this step. If not, get it here. Unzip this file to a place you can work with it. Go into properties and remove the Read Only check. (This step has helped some and has never hurt anyone.)
3. Update the Database
If you are an XML user, please take a moment of silence for your SQL lovin' brethren, as they actually have something to do in this step. Then move on to step #4.
Ok, SQL provider people, there are two things you need to take care of to get ready for 1.3.
First, you need to download the upgrade script and run it. This does a bunch of magic including adding a field to a table, adds some entries to your settings table, and some other stuff like indexes, relations, etc.
Second, you are going to need to update your web.config file. Release 1.3 has moved away from using the sql.config as it was not supported in mono. So you are going to need to move your connection string to the new web.config file. (Yes, I'm really sorry about that.) Also, don't forget to make the MSSQLProvider the default provider (as XML is the default setting in the new web.config.)
4. Update your web site
Now, we are copy the new stuff to your website. You'll want to copy everything up except the App_Data folder.
Once it is copied, you should be able to browse to your blog and see the 1.3 version number at the bottom of the page.
5. Update your Settings
_thumb.jpg)
Login and go to your settings page. There are a few new things to look at.
Under the Basic Settings area, you'll see a Mobile Theme and Show post navigation links options. Be sure to select Mobile for your Mobile theme (unless you've already made a new one.)
Under the Advanced Settings, Enable Trackbacks and Enable Pingbacks now appear with Send and Receive options. Turn them on or off as you'd like.
Be sure to click Save Settings when you are done.
Troubleshooting
If you are having trouble getting your web site up after copying the files up, please remove any custom themes and extensions and try again. (You may need to manually change the selected theme to Standard in your settings.xml file or be_settings table if you remove a theme that you were using.
If you still have trouble after that, please have a look on the BlogEngine.NET forums and wiki. Someone else likely had a similar problem so searching is the best option. If not however, ask a question.
Good luck and enjoy the latest version.