Building the codebase
Last updated
Was this helpful?
Last updated
Was this helpful?
In order to use Umbraco as a CMS and build your website with it, you should not build it yourself. If you're reading this then you're trying to contribute to Umbraco or you're debugging a complex issue.
Are you about to ?
Are you trying to get to the bottom of a problem in your existing Umbraco installation?
If the answer is yes, please read on. Otherwise, make sure to head on over and start using Umbraco CMS as intended.
↖️ You can jump to any section by using the "table of contents" button ( ) above.
To run umbraco, we first need to initialize the client git submodule:
Execute git submodule update --init to get the files into \src\Umbraco.Web.UI.Client folder.
This can be executed in the root folder of your cloned repository.
If you are going to run Umbraco for testing, execute dotnet run inside the \src\Umbraco.Web.UI folder.
If you are going to work on the Backoffice, you can either go to the \src\Umbraco.Web.UI.Client folder and check out a new branch or set it up in your IDE, which will allow you to commit to each repository simultaneously:
Rider: Preferences -> Version Control -> Directory Mappings -> Click the '+' sign
If you get a white page, delete \src\Umbraco.Cms.StaticAssets\wwwroot\umbraco folder and run npm ci && npm run build:for:cms inside the src\Umbraco.Web.UI.Client folder to clear out any leftover files from older versions.
If you want to get the latest changes from the client repository, run git submodule update again which will pull the latest main branch.
In order to build the Umbraco source code locally with Visual Studio Code, first make sure you have the following installed.
npm v7+ (installed with Node.js)
Open the root folder of the repository in Visual Studio Code.
To build the front end you'll need to open the command pallet (Ctrl + Shift + P) and run >Tasks: Run Task followed by Client Watch and then run the Client Build task in the same way.
You can also run the tasks manually on the command line:
If you just want to build the UI Client to Umbraco.Web.UI then instead of running dev, you can do: npm run build.
The login screen is a different frontend build, for that one you can run it as follows:
If you just want to build the Login screen to Umbraco.Web.UI then instead of running dev, you can do: npm run build.
The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.
To run the C# portion of the project, either hit F5 to begin debugging, or manually using the command line:
The initial C# build might take a _really_** long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
In order to build the Umbraco source code locally with Visual Studio, first make sure you have the following installed.
npm v7+ (installed with Node.js)
The easiest way to get started is to open umbraco.sln in Visual Studio.
To build the front end, you'll first need to run cd src\Umbraco.Web.UI.Client && npm install in the command line (or cd src\Umbraco.Web.UI.Client; npm install in PowerShell). Then find the Task Runner Explorer (View → Other Windows → Task Runner Explorer) and run the build task under Gulpfile.js. You may need to refresh the Task Runner Explorer before the tasks load.
If you're working on the backoffice, you may wish to run the dev command instead while you're working with it, so changes are copied over to the appropriate directories and you can refresh your browser to view the results of your changes.
The initial Gulp build might take a long time - don't worry, this will be faster on subsequent runs.
"The rest" is a C# based codebase, which is mostly ASP.NET Core MVC based. You can make changes, build them in Visual Studio, and hit F5 to see the result.
The initial C# build might take a _really_** long time (seriously, go and make a cup of coffee!) - but don't worry, this will be faster on subsequent runs.**
Do note that this is only required if you want to test out your custom changes in a separate site (not the one in the Umbraco.Web.UI), if you just want to test your changes you can run the included test site using: dotnet run from src/Umbraco.Web.UI/
You may want to build a set of NuGet packages with your changes, this can be done using the dotnet pack command.
First enter the root of the project in a command line environment, and then use the following command to build the NuGet packages:
dotnet pack -c Release -o Build.Out
This will restore and build the project using the release configuration, and put all the outputted files in a folder called Build.Out
You can then add these as a local NuGet feed using the following command:
dotnet nuget add source <Path to Build.Out folder> -n MyLocalFeed
This will add a local nuget feed with the name "MyLocalFeed" and you'll now be able to use your custom built NuGet packages.
Once the solution has been used to run a site, one may want to "reset" the solution in order to run a fresh new site again.
The easiest way to do this by deleting the following files and folders:
src/Umbraco.Web.UI/appsettings.json
src/Umbraco.Web.UI/umbraco/Data
You only have to remove the connection strings from the appsettings, but removing the data folder ensures that the sqlite database gets deleted too.
Next time you run a build the appsettings.json file will be re-created in its default state.
This will leave media files and views around, but in most cases, it will be enough.
To perform a more complete clear, you will want to also delete the content of the media, views, scripts... directories.
The following command will force remove all untracked files and directories, whether they are ignored by Git or not. Combined with git reset it can recreate a pristine working directory.
For git documentation see:
The produced artifacts are published in a container that can be downloaded from DevOps called "nupkg" which contains all the NuGet packages that got built.
You may need to run the following commands to set up gulp properly:
Did you read ?
If you want to run a build without debugging, see below. This runs the build in the same way it is run on our build servers.
You might run into .
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to to help you to see the changes you're making.
When the page eventually loads in your web browser, you can follow the installer to set up a database for debugging. You may also wish to install a to ease your debugging.
( for you to use to contribute to Open Source projects)
You might run into .
The caching for the back office has been described as 'aggressive' so we often find it's best when making back office changes to to help you to see the changes you're making.
When the page eventually loads in your web browser, you can follow the installer to set up a database for debugging. You may also wish to install a to ease your debugging.
Did you read ?
git
git
Umbraco uses Azure DevOps for continuous integration, nightly builds and release builds. The Umbraco CMS project on DevOps ..
Git might have issues dealing with long file paths during build. You may want/need to enable core.longpaths support (see for details).
