Overview
The code and project-related materials for Umbraco, including version 5, is available on CodePlex at http://umbraco.codeplex.com. The repository for the sourcecode itself is at https://hg01.codeplex.com/umbraco/ and you must use a Mercurial client in order to download the code from this location. If you got Mercurial and/or just want to gain access to the sourcecode in an unversioned fashion, CodePlex offers a zip download version from the
SourceCode tab.
We've given Umbraco 5 the codename of Jupiter, so in this Wiki and guide you may see that term.
In order to get up and running in the Jupiter codebase you will be required to install some components on your machine. The codebase is shipped with assemblies that we're allowed to distribute, but some you must download for yourself. In the root of the sourcecode repository there is a file called
pre-requisites.txt which outlines these, and it's also listed below.
Required tools & components
Mercurial
- Mercurial (Hg) is required for you to access the sourcecode repository. If you prefer a GUI option, TortoiseHg 1.x is a recommended install. At the point of writing, version 2.x has been released for a few weeks after a major rewrite, so your mileage with that version may vary until they iron out some quirks.
- Links: A Mercurial client and the Umbraco 5 Source Code
Visual Studio 2010 with SP1
- Umbraco 5 makes extensive usage of the Razor view-engine, and it’s really recommended to have service pack 1 installed to Visual Studio 2010 in order to get the best experience.
- The easiest way to get this is via the Web Platform Installer available at Microsoft.com/web
.NET 4.0 & MVC3
- Umbraco 5 targets .NET 4.0 and MVC3. There will not be a version released targeting .NET 3.5.
- Download MVC3 from: ASP.Net MVC3 RTM
Extras
For Xmldoc comment documentation, the following are recommended but not required to get you stuck into the codebase:
Files, folders and solutions¶
Layout of files
/Resources - central place for tools and components used by libraries/Resources/Build/ - build scripts (TBC)/Resources/References/ - library assemblies that are used by Umbraco code. Note: at this time we don't use NuGet but may switch to this during a "tidy-up" phase/Resources/Tools/ - any tools that we use that we're allowed to distribute (TBC)/Sandboxes/ - a free area to do experiments that you want to share with others, in case any ideas need proving. For larger items, please use your own repo though./Source/ - the main place where the sourcecode guts are stored. This contains our Visual Studio solutions on the root./Source/Consoles - console app projects/Source/Documentation Projects - any Sandcastle / LiveDocumenter projects (TBC)/Source/Libraries - non-executable class libraries excluding unit tests/Source/Modelling - any UML modelling projects (TBC)/Source/Testing - unit test library projects/Source/Web Apps - website applications such as the backoffice project
Visual Studio Solutions
- /Source/CMS.Development.sln
- This solution contains the libraries involved in the back-office CMS/UI project, the default persistence providers, and the default set of Framework libs
- /Source/Domain.Development.sln
- This solution is focussed on the set of libraries needed for developing persistence providers and the domain models they exposee
- /Source/Framework.Development.sln
- This solution is focussed on the set of libraries just for the foundation of Umbraco's framework
Running: Permissions & Trust
Development
- To ensure we always remember about Medium Trust, this should always be set in the web.config file.
- To develop, you should have Read/Write permissions to the file system running Umbraco
Virtual Directories & IIS Express
- We have configured the project to use IIS Express running in a Virtual Directory as to guarantee Virtual Directory support
- In rare cases you may need to do some manual IIS Express configuration if you experience the YSOD: "The configSource file '.....' is also used in a parent, this is not allowed. " This is because IIS Express is pointed both the root directory and the Virtual Directory at the same location so you'll need to modify your local IIS Express config:
- In your Windows taskbar app-tray you will see an IIS Express icon:
- right click, choose "Show all applications"
- Click the site that has the virtual folder appended to the URL (TestVDir)
- Click the 'Config' link at the bottom
- This will open the applicationHost.config file, search for: 'TestVDir'
- This should bring you to an xml site node similar to: < site name="Umbraco.Cms.Web.UI" id="123456789"
- From here, you have 2 options: Remove this site entirely, or update the root path.
- Removing the site entirely is easy, then you need to close IIS Express and restart the web application (ctrl + F5)
- Otherwise, if you want to update the root path...
- There will be 2 'application' nodes listed, the first one with a 'path' equal to '/' will show a 'physicalPath' value similar to: "C:\(Path to your project files)\Source\Web Apps\Umbraco.CMS.Web.UI"
- You need to change this value to: "C:\(Path to your project files)\Source\Web Apps" so that the root path '/' is not pointing to the same folder as the /TestVDir virtual directory
- right click the IIS Express taskbar app-tray icon and click "Exit" to stop IIS Express
- re-start the web application (ctrl + F5 or just F5), this should now work
Running/testing
- To run, the target minimum permission set for Umbraco 5 is Medium Trust or higher, with the following file permissions:
- Root of site: Read/List
- Debug Logging folder (default path: ~/App_Data/Logs/*) - Read/List/Write
- Plugins folder (default path: ~/Plugins/Core/* and ~/Plugins/Packages/* and ~/Plugins/bin*) - Read/List/Write
- For deployment it's possible to set read-only access to these folders, but in regular circumstances Umbraco will attempt to shadow-copy assemblies from the subfolders to ~/Plugins/bin on app startup