tpc-main
Developer Network

Upgrade Sitefinity

  • 1. Prepare for Upgrade
  • 2. Create an Upgrade Branch
  • 3. Install Sitefinity CLI
  • 4. Perform the CLI Upgrade

Prepare for Upgrade

This guide outlines the steps required to upgrade your existing Sitefinity CMS project to the latest supported version. The process includes upgrading NuGet packages, applying Sitefinity’s database upgrade scripts, and validating that your application runs correctly after the upgrade. These steps must be completed before upgrading Portal Connector.

  1. A full database backup of the current Sitefinity instance.
  2. A full backup of the project source code, or the work is performed in a dedicated Git branch (e.g., feature/sitefinity-upgrade-{version-number}).
  3. Visual Studio installed and updated to a version compatible with the target Sitefinity release.
  4. The current project builds and runs successfully on the existing Sitefinity version.
  5. All custom modules, widgets, and integrations compile with no unresolved dependencies.
  6. Administrative access to the Sitefinity backend for post-upgrade validation.

Create an Upgrade Branch

  1. Open the project repository.
  2. Create a new Git branch for the upgrade (e.g., feature/sitefinity-upgrade-{version-number}).
  3. Ensure the branch is up to date with the latest changes from the main development branch.
  4. Update the connection string to point to your local database backup and confirm that the project runs successfully before beginning the upgrade.

Install Sitefinity CLI

  1. Download the CLI. Download the latest Sitefinity CLI version from: https://github.com/Sitefinity/Sitefinity-CLI
    Sitefinity CLI Zip

    Figure 1 Download latest Sitefinity CLI

  2. Extract the ZIP. Unzip the files into your desired directory (e.g., C:\SitefinityCLI).
  3. Add to System PATH.
    1. Open System Properties → Environment Variables.
    2. Click New under the Path variable and add: C:\SitefinityCLI
  4. Verify Installation.
    1. Open a new terminal and run:
    sf version

    If installed correctly, the CLI will display the current version.

Perform the CLI Upgrade

  1. Close Visual Studio. Ensure all Visual Studio instances are fully closed before running the upgrade command. Keep Visual Studio closed during all reference edits to avoid file locking or automatic reloads.
  2. Delete the bin and obj folders. Navigate to each project folder in the solution and delete its bin and obj directories.
    Delete bin and obj folders

    Figure 2 Delete bin and obj folders

  3. Delete the packages folder. In the root solution directory, locate and delete the packages folder.
    Delete packages folder

    Figure 3 Delete packages folder

  4. Execute the upgrade via Sitefinity CLI. Open Developer PowerShell for VS in the solution directory and run: 
    sf upgrade "YourWebAppSolutionName.sln" "TargetVersion"
    Replace the placeholders with the correct solution name and target version. When prompted, enter Y to confirm.
  5. Allow Visual Studio to open and close automatically. The CLI may open and close Visual Studio during the upgrade. This is expected — do not interrupt it. After completion, the CLI will display any detected errors.
  6. Resolve project reference errors. If the upgrade fails due to invalid or outdated references:
    1. Open the affected .csproj files in an external editor (Notepad++, VS Code, etc.).
    2. Remove the invalid reference entries shown in the CLI error output.
    3. Save the changes and keep Visual Studio closed.
    4. Run the upgrade command again.
  7. Repeat until the upgrade succeeds. Continue removing incorrect references and rerunning the command until the CLI reports a successful upgrade.
    Sitefinity CLI Upgrade Successful

    Figure 4 Sitefinity upgrade successful

  8. Commit the successful Sitefinity upgrade to source control. After the CLI upgrade completes with no errors, check in the updated solution. This ensures you have a clean, validated Sitefinity baseline before proceeding to upgrade Portal Connector.