Story Details for tools
MvcInstaller - NuGet Package for MVC 3 applications
There are a few pre-requisites to know about before deciding whether to use it.
- ASP.NET MVC - MvcInstaller is built on the ASP.NET MVC framework so it can only be used to install MVC applications, not WinForms, or WebForms, etc.
- SQL Server - at this moment, it only installs your database schema on the SQL Server RDBMS.
- Database - you need to have the database created PRIOR to running MvcInstaller. MvcInstaller works very easily with MVC sites that are installed on shared hosting systems. Your application's database tables do NOT need to be created prior to installing or running MvcInstaller. They can be done with this process. Read on.
Procedures to use MvcInstallerThere are a few steps that are taken to use MvcInstaller. These are not rigid steps, but general guidelines.
Step 1Create your ASP.NET MVC application. The first step is to obviously create your ASP.NET MVC application. When you have completed the application, install MvcInstaller to prepare for deployment. NOTE: MvcInstaller can be installed into your application via NuGet at any point in your development cycle. It does not have to be installed when you first start your project.
Step 2Configure MvcInstaller. There are some minor settings to configure in the MvcInstaller installer.config file. These settings are what MvcInstaller will execute to install your database schema and the ASP.NET Membership with Roles and Users.
Step 3Publish ASP.NET MVC application. Publish (FTP) your compiled ASP.NET MVC application to you production server.
Step 4Install your database schema and ASP.NET Membership system using MvcInstaller via a browser.
I'll go over everything that is necessary for this in the information below.
InstallationInstallation of the MvcInstaller into your MVC application couldn't be easier. You have to different methods to use:
Visual Studio Reference Dialog - you would right-click on the References folder of your application and select "Manage NuGet Packages".
Once you click this menu item you will see the dialog to choose the NuGet packages.
In the Search box in the upper-right corner of the dialog, enter the name of the package you want, or something like it. In this case I've entered: "mvcinstaller" and it shows me my three NuGet packages.
NOTE: the third package "MvcInstaller", should NOT be chosen because I don't maintain it any longer. I do maintain the other two, "MvcInstaller.MVC2" and "MvcInstaller.MVC3". If you hover your mouse over a package, you'll see an "Install" button appear. Click the button to install the package.
Package Manager Console - this is the way to install and manage packages via a command-line like process. You can display the console by clicking the Tools menu and then choosing "Library Package Manager", and then "Package Manager Console". The console will appear at the bottom of the Visual Studio instance.
To install the package simply type: install-package MvcInstaller.MVC3
If you enter, install-package MvcInstaller and then click the Tab key, you'll get the Intellisense for the available versions as shown above.
Once you hit the Enter key, it will install the package.
NOTE: either one of these methods are fine for installing MvcInstaller, but some NuGet packages require that you use the console because the NuGet package needs to run PowerShell scripts, and they can't be executed via the dialog.
ConfigurationAfter MvcInstaller has been installed you'll see a number of different files that have been included in the MVC application. First is the MvcInstaller assembly.
Next are some files that have been added to the project.
In order to prepare the application to use MvcInstaller we need to configure the installer.config file. Here's a look at the installer.config file.
I'll go over each section here.
- ApplicationName - (line 3) - this is what is used in your web.config membership sections for the ApplicationName. It will update the web.config membership sections as well as in the database.
- Path - (lines 4 - 6) - the App_Data name is the folder where your SQL scripts should be placed to generate the tables for your database schema on the production database. You should be very careful and number your SQL scripts in the order that they should be executed. MvcInstaller will add them to a sorted collection and then execute them in that order, so it's up to you to make sure they are ordered correctly.
- Membership - (line 7) - this line does two things, it tells MvcInstaller whether or not it's going to create the ASP.NET Membership system for you, and what the provider name is. The default ASP.NET membership provider is automatically included for you, but if you have created a custom provider, you can add it here. NOTE: very important, the Create attribute is an all-or-nothing action, meaning if this is set to True, then all three of the providers will be created, Membership, Profiles, and Roles. If it's False, then none will be created.
- Profile - (line 8) - this sets the name of the Profile provider.
- RoleManager - (lines 9 - 23) - this is where you will enter the names and roles of the administrators for your application and the Roles provider name. NOTE: it's important to understand that MvcInstaller is primarily built for Administrators, meaning it's supposed to be used by Administrators so they can quickly get their database schema installed with the Membership system in order to have instant access to the application. It is not necessary or advised to try and include users and roles for non-administrative access. That should be done by Administrators after the application has been installed.
You have the capability to configure MvcInstaller to install any number of roles and users-to-roles by including as many Role nodes as needed. Then you just need to include the users for those roles and you are all set.
- Database - (lines 24 - 30) - these lines cover all the settings necessary to connect to your production database. The UseTrustedConnection attribute tells the application whether the connection is trusted. If it is then it will generally use Windows Authentication and a username and password are not needed, and the username and password config settings will be ignored. Otherwise, if it's set to False, then the username and password values are required.
The EntityFrameworkEntitiesName attribute tells MvcInstaller whether it will create a connection string for the Entity Framework. If it's blank, then it will not, if the value is not blank, then it should be the EntityFramework Context name.
- ConnectionStringName - (line 25) - this of course is the name of the connection string as it will be created for you in the web.config.
- DataSource - (line 26) - this is the name of the SQL Server instance that you will be connecting to.
- InitialCatalog - (line 27) - this is the name of the database.
- UserName and Password - (lines 28 and 29) - these are the credentials for the database if the UseTrustedConnection value is set to False.
Update - January 3, 2012
Version 126.96.36.199 - changed the way the EntityFramework connection string is built to be more reliable for different configurations. The proper way to make this work now is the following:
- EntityFramework metadata - open the App.config for your EntityFramework context (if you've built it using the visual designer) and copy the metadata information
- Installer.config - paste this into the EntityFrameworkEntitiesName value
Open the App.config file for the EntityFramework and copy the metadata name:
... and paste it in the installer.config file.
MvcInstaller works on conventions, so this will name the EntityFramework connection string as this name and also build the connection string with this name, which we know works since it's in the App.config file.
In this instance, the ConnectionStringName value is irrelevant when the EntityFrameworkEntitiesName has a value. Again, when the EntityFramework is being used, another connection string will be created for the ASP.NET Membership system, and this will be called "MembershipConnection".
New as of October 28, 2011The Membership providers, Membership, Profile and RoleManager elements, all can accept a "type" attribute so you can enter your custom provider if necessary. If you do not add a "type" attribute to any of the membership elements, then the default Microsoft providers will be used when modifying your web.config.
The install.config file will look like this with the optional "type" attribute for a custom provider.
Your Database SchemaIn order to install your application's database schema, you should prepare SQL scripts for the tables, stored procedures, views and any seed data and place them into the "App_Data" folder.
Important! As I mentioned earlier, you should number these sql scripts in the order you want them to execute. Something like this...
The installer will grab all sql scripts in the "App_Data" folder and install them in their numbered order.
Another import point for this to work properly is to include in your table schema scripts, DROP and CREATE statements.
The easiest way to create these scripts with SQL Server 2008 is:
- right-click on the database name in the SQL Server Management Studio
- in the flyout menu, select "Tasks" --> "Generate Scripts"
- This will take you through a wizard to generate scripts for any or all objects in your database.
Here's what your schema script should look like, this is very simple:
By adding the DROP statements, it helps MvcInstaller run properly in the case that an exception occurs before it has completed. This way it can simply re-run the sql scripts, drop the tables and re-create them without problems.
So if you experience an exception for some reason and then cannot simply click the "Install" button to re-run the process, check your sql script and make sure it contains the DROP statement with the IF (NOT) EXISTS checks.
Now you are ready to continue.
This might seem like a lot, but it's really not. Once these settings are done, then you are ready to deploy your application to your production server, and then install it via a web browser.
Run MvcInstallerOnce your MVC application is deployed to your production server, you are now ready to install the database and membership system via MvcInstaller. Simply enter "Install" in the browser after the domain name and hit Enter. The page will look like this.
Before you click the "Install" button let me just go over a few things about this page.
It shows all the information as you have set in the installer.config file, but WITHOUT PASSWORDS! This is important and a very nice feature. This means that you can be safe in knowing that you can install your application in front of someone without the fear that they might see your passwords.
The other thing to note is that you'll need to ENABLE WRITE PERMISSIONS, during installation since MvcInstaller makes changes to you web.config file. After it has been successfully installed, then you can remove the write permissions if you need.
So now we're ready to click "Install" and if this is the first time clicking the button and it's a brand new application, you will see this error message.
This is just telling you that the default ASP.NET MVC web.config configuration for the roleManager section has the enabled attribute set to False. This means that you intend to create the ASP.NET Membership system, but you need to have the roleManager enabled for MvcInstaller to work properly, so MvcInstaller updates the setting for you and updates all the other provider configuration information. It also updates the connection string settings.
Now you can simply click the "Install" button again. This time as long as the installer.config settings aren't violating the web.config Membership attribute settings, you will see a Processing message.
Then depending on whether you are also installing your database schema via SQL scripts, it could be instantaneous or a few seconds. If there aren't any errors, you will see this.
Now you can successfully log onto the application.
You can see I logged on here as joemanager.
Taking a look at SQL Server we can see that there are no tables.
If I refresh it, it shows that all the tables for the ASP.NET Membership system have been created as well as the database schema for my application.
If I look at the rows for the MyBlogTable table, I'll see all the data was inserted into the table successfully!
I can also open the Users table and see all the users.
That's it! My entire database schema and membership are installed with very little effort.
ConclusionThat's MvcInstaller. The quick and easy way to install your database schema and ASP.NET Membership system for your ASP.NET MVC application on any server.
I hope this NuGet package is helpful to you.