Walkthrough: Using the Getting Started template

Version: 22.x
Important

If you integrated your ASP.NET Core app before September 2024, it's using the legacy ASP.NET Core Rendering SDK, version 22 or earlier. This SDK is no longer receiving updates, so we recommend that you upgrade to the latest version of the new ASP.NET Core SDK.

Sitecore provides a Getting Started template for Sitecore developers that want to try out Sitecore Headless Development with ASP.NET and Sitecore containers. You can use it to get started quickly or to kick-start new customer projects.

The template doesn't implement Sitecore Helix conventions for solution architecture. As you begin building your Sitecore solution, we recommend reviewing Sitecore Helix and the Sitecore Helix Examples for guidance on implementing a modular solution architecture.

The template includes:

  • A Docker environment with a Sitecore topology (by default XP0). The template also includes configuration for the XM1 and XP1 topologies.

    Note

    The template includes docker-compose files for every supported topology. You can find them in the run\sitecore-<topology> folder. For example, run\sitecore-xm1\docker-compose.yml. The included docker-compose.yml file is a standard environment from the Sitecore Container Support Package. The docker-compose.override.yml file for each topology contains customizations made for this solution.

  • An ASP.NET rendering host.

  • Serialized items for a one-page sample site. See the src\Items.module.config file for details.

  • An MSBuild project named Platform for deploying configuration and code into the Sitecore Content Management role. See the src\platform folder for details.

  • An MSBuild project named RenderingHost for an ASP.NET rendering host. See the src\rendering folder for details.

Before you can create a solution from the Getting Started template, you must install some software components and install the template.

This walkthrough describes how to:

  • Install the prerequisites

  • Install the template

  • Create the MyProject solution

  • Test the MyProject solution

  • Deploy the application

Install the prerequisites

Before you can install the template and create a solution, install the following software components on your workstation:

See the Sitecore Containers documentation for more information on system requirements.

Install the template

You download and install the template in your file system. Afterward, you can create solutions based on the template.

To install the template:

  1. Open PowerShell with administrator privileges.

  2. Run the following command:

    RequestResponse
    dotnet new --install Sitecore.DevEx.Templates --nuget-source https://nuget.sitecore.com/resources/v3/index.json

The dotnet tool does not provide obvious feedback that the installation was successful. However, the install command ends by listing all of the installed templates. If the install is successful, the list includes sitecore.aspnet.gettingstarted.

Create the MyProject solution

You can name your solution anything you like but, in this example, we name the solution MyProject.

To create the MyProject solution:

  1. Open PowerShell with administrator privileges.

  2. Check if you have Internet Information Server running on port 443:

    RequestResponse
    Get-Process -Id (Get-NetTCPConnection -LocalPort 443).OwningProcess

    • If you do, you must stop it:

      RequestResponse
      iisreset /stop

  3. Check if you have Apache Solr or any other service running on port 8984:

    RequestResponse
    Get-Process -Id (Get-NetTCPConnection -LocalPort 8984).OwningProcess

    • If you do, you must stop it:

      RequestResponse
      Stop-Service -Name "<NAME_OF_YOUR_SERVICE>"

    • Or, if you have started it with Non-Sucking Service Manager, stop it with this command:

      RequestResponse
      nssm stop "<NAME_OF_YOUR_SERVICE>"

  4. Go to your solutions folder and create the MyProject solution and project:

    RequestResponse
    dotnet new sitecore.aspnet.gettingstarted -n MyProject
    Important

    You must use Latin characters in the project/folder name. Using non-Latin characters can give unexpected results because of character limitations in Docker registry names and URLs.

  5. Go to the MyProject/ folder.

  6. Run the following script to prepare the Sitecore container environment:

    RequestResponse
    .\init.ps1 -InitEnv -LicenseXmlPath "<PATH_TO_YOUR_license.xml_FILE>" -AdminPassword "<YOUR_DESIRED_SITECORE_PASSWORD>" -Topology <topology>

    Provide an absolute path for the license file. Example: C:\license.xml

    You'll use the password you specify here in a next step to log in to the Sitecore Identity Server.

    The -Topology parameter is optional. Supported values for the -Topology parameter are xp0 (default), xm1, and xp1.

    The script prepares the following items:

    • A valid/trusted wildcard certificate for *.myproject.localhost.

    • The hosts file entries for myproject.localhost.

    • The required environment variable values in the .env file for the Sitecore instance.

  7. Download the Sitecore Docker images and install the containers:

    RequestResponse
    .\up.ps1

    The template creates the following entries in the Windows hosts file. Each of them points to a Sitecore container:

  8. Wait for the script to open a browser tab for the Sitecore Identity Server. Then log in and accept the device authorization.

  9. Wait for the script to open browser tabs for Content Management and the rendering host.

The application does not include a reference to the .env file in the .gitignore file so that developers can share initialized environment variables. If you check your .env file into source control, other developers can prepare a certificate and hosts file entries by simply running the init.ps1 script.

If your Sitecore solution or its data are sensitive, we recommend excluding the .env file from source control and providing other means of centrally configuring the variables.

Test the MyProject solution

After creating your solution, you can modify and publish it using the Content Editor and use Visual Studio to modify and publish your code.

To test the solution:

Tip

Deploy the application

You deploy a Sitecore ASP.NET application like any other ASP.NET application.

To deploy the application:

Do you have some feedback for us?

If you have suggestions for improving this article,