Creating a
Sitefinity Project
Introduction
Once I had used the Sitefinity CLI tool to upgrade a project I was hooked. This was way simpler than the manual process. Not only does it update your packages but it's smart enough to sort out and correct some misconfigurations. But there was something missing for me. There was no option to create a new project. The good news is that the Sitefinity team have this code as open-source meaning I could download and look to add that functionality myself. So, that is what I have done.
I had a look through the code and at how to create my own command and then thought about what I wanted to achieve. Skipping to end this is what I have ended up with.
- Take a simple pre 'canned' project and restore it to a directory
- Be able to select different SF versions
- Have the ability to create and specify custom 'canned' projects
- The ability to rename the project and solution files
- Restore a ready built database.
How it works
After running the command you should end up with a project which you can open, run and have a Sitefinity website instance in front of you. The command line takes one argument for the location of a configuration file which holds all the parameters for running the create process.
sf create "C:\MyLoction\my-config.json"
After checking the parameters passed in it will:
- Display the configuration details and wait for you to confirm
- Clear the target directory of any files
- Pull your selected project template and unzip it to the target location
- Rename the solution and project as specified
- Restore the database and set the connection string
- Pull down and add all the required NuGet packages
Nothing too huge and excluding the package restore, it takes about 30 seconds.
Let's go into a bot more detail.
When running the command I sugget you start a console session by 'Run as Administrator'.
Pre Canned Projects
Within the CLI is a 'Projects' folder that holds the starting Sitefinity projects along with a zip file of that project. The zip file is what is used by the command while the project files are there for reference and development.
The starter project is a copy of the 'Empty Project' created by the Sitefinity project download exe. I have made some minor changes such as adding a global.asax file. Changing some project file references. Fixing a warning on the build that has been there
for years and has always annoyed me. I also made it into a better-structured solution and included a .gitignore file. Overall pretty minor but with changes, I think everyone does.
This simple starter project may be good for some but others will have a lot of other improvements that they use in all their projects. Error Handling, Owin plugins, perhaps a starting theme. You can take the starting project, upgrade it to your starting
project standard, then zip it up with the right naming convention and place it in a location where you can tell the command to look for it. This way you can manage your own 'Sitefinity' standards.
The idea is to create starting projects just for major releases. 14.0, 14.1, 14.x. Though possible, I avoided the idea of adding minor release versions as an option. If you want 14.0.7623 then you can run the upgrade command straight afterwards. This will avoid having to mainatin lots of project templates.
You can check out the structire and changes in my github repo.
Name Changes
By default, the solution, project and database are named, 'SitefinityWebapp'. To change this you have three corresponding parameters.
The SolutionName will rename the sln file.
The ProjectName will rename the csproj file as well as its parent folder to match and update the sln files reference to the new name. It will also be used to rename all the namespaces in the code files and update the assembly file.
The DatabaseName will of course just update the database connection string.
The way that the command does this is by using {{HandleBars}} which is a straightforward find and replace tool. Any file that needs to be altered is given a .template extension. (This avoids wasting time parsing every file.) Handlebars uses the double squiggly bracket syntax, {{...}}, to replace variables. After that, I then remove the '.template' extention leaving you with the updated file.
As an enhancement I am thinking about the ability to add your own list of token and values so that you can add in a list of your own replacement variables to the process.
Database Restore
The solution already comes with a created database so you don't need to go through the database creation process. Nothing has been added to it except an admin account so you can log on.
site.admin@sitefinitywebapp.com with a password of 'Password01!
'.
Be aware that if you don't have a valid license file added then you will be asked for one when you try and run the project.
The database is backed up as a .bacpac file and uses SqlPackage.exe to extract and restore it. For this to happen you must have the Microsoft DacFramework installed. If you don't then you have the SkipDbRestore switch and you can sort the database restore out yourself.
If you don't supply a database user name and password the process will try and restore the database using the credentials you are currently logged in as. This is usually fine for developers with local instances of SQL installed.
Other Options
There are a couple of other options for you.
SkipDbRestore will of course not try and restore the database and will just extract the project. You will find the database .bacpac file in the extracted project files for you to organise the restore.
LicenseFilePath allows you to provide the location of a license file to add to the project.
PackageSources allows you to specify your own NuGet packages directory rather than the default Sitefinity and Nuget public sites.
SkipConfigurationConfirm will not ask you to confirm the details and will start creating straight away.
Configuration file
When I started this work I originally had all the parameters being entered onto the command line like the other commands. As these grew in number I then decided to provide a JSON configuration file option to supply all the answers. This, I thought, would
also be really helpful for people where there is a separation of duties in their organisations where some people (server techs) may take care of creating new projects, commissioning servers and databases. This way the developer can create the configuration
file and pass this onto the tech people to process.
After doing this I then felt this configuration file was also way easier than typing in all the command line switches and so I now just support the configuration file option. I felt it was much cleaner and less mistake-prone.
I also like the idea that the file can be extended to add in your own configuration sections. For example, you may need to supply your server tech folk details about what source control location the project should go to and what the CI setup should look like. You could specify this in this config file and your server tech team could run the Sitefinity CLI followed by a series of their own PowerShell scripts that reference the same config file for answers.
Here is a sample configuration file that can be found at the root of the project.
{
"targetFolder": "D:\MyNewSfProject",
"version": "14.0",
"sqlServer": "localhost",
"solutionName": "My Sitefinity App",
"projectName": "SitefinityWebApp",
"databaseName": "SitefinityWebApp",
"databaseRestoreUserName": "",
"databaseRestorePassword": "",
"projectTemplatePath": "",
"licenseFilePath": "",
"packageSources": [],
"skipDbRestore": false,
"skipConfirmation": false,
"YourCustomStuff": {
"keyA": "value A"
}
}
So to run this you would browse to the directory of your Sitefinity CLI deploy and type:
sf create D:\myconfigfile.json
According to the config above that will pull the default 14.0 project from the CLI files and copy it to your target directory. The solution will be renamed but the project will stay as SitefinityWebApp. The database will be restored using your credentials to the local server and named SitefinityWebApp with the connection string set as such. Then, finally, it will reach out to the default NuGet sources and download all the NuGet packages.
After all that, you should be able to open the solution and straight away and start it. (Though do a build first just to be sure).
Keep in mind that I have only tested this on my PC so there are sure to be scenarios when the code will run into problems. I still need to look at creating some Test cases as well as reviewing and refactoring the code. But in the meantime, anyone is welcome to download it and test it out and of course, send me back any feedback.
You can get a copy from a fork I made from the Sitefinity CLI source at DarrinRobertson/Sitefinity-CLI.
Thanks for reading and feel free to comment - Darrin Robertson
If I was really helpful and you would buy me a coffee if you could, yay! You can.
Leave a comment Load more commentsMake a Comment