Upgrade Portal Connector

Preparing for Upgrade

• Newer versions of Sitefinity (including Sitefinity 15.x) require Bootstrap 5–based page templates for MVC widgets. Before upgrading, ensure your site has Bootstrap 5 templates available and plan to migrate any pages still using legacy Bootstrap 3 or 4 layouts. Portal Connector must also be configured to use Bootstrap 5 resources after the upgrade (see Step 5 – Configuration).
• Although we provide support for Portal Connector versions as far back as 6.0, active patch updates are currently available for versions starting from 6.1. Therefore, we strongly encourage users to upgrade to the most recent Portal Connector version and build.
• If you are upgrading from a pre‑NuGet version, you may have build events that reference DLLs from an older TPC assemblies folder. Remove this directory and the build event from your Web App project (Project Properties → Build Events).
• Always review the patch notes for the Portal Connector build you are upgrading to, including any intermediate builds. Patch notes may include breaking changes such as updated encryption algorithms, configuration changes, or dependency updates that require manual intervention. Therefore, reviewing patch notes before upgrading helps prevent issues such as invalid connection strings or incompatible configuration values.
• Review the Breaking Changes section for every Portal Connector release from your current version up to the version you are upgrading to. This includes the target version and all intermediate versions. You can do this by visiting the release notes section, selecting each relevant version, and scrolling down to the Breaking Changes section. Breaking change information is available for all versions back to Portal Connector 5.3. For version 5.2, refer to the breaking changes documentation .

Perform NuGet Upgrade

1. Open NuGet Package Manager. In Visual Studio, right‑click the solution or the specific project and select Manage NuGet Packages. Select Portal Connector as your package source. For steps on how to add Portal Connector as a package source, see the installation guide.
2. Search for the Portal Connector package. In the search bar, type portalconnector.all under the Installed or Updates tab to locate the package you want to upgrade.
3. Select the version compatible with your Sitefinity installation. From the version dropdown, choose the Portal Connector version that matches your Sitefinity version. Select the project(s) that require the update, then click Install or Update to begin the process.

   Pay close attention to the version you select—Portal Connector versions are tightly coupled to specific Sitefinity versions. Installing an incompatible version will require reverting your changes and restarting the upgrade process. For more details on version compatibility, refer to the installation guide.

4. Accept the license agreements. When prompted, review and accept all license agreements. Visual Studio will then download the package, update references, and add any required dependencies.

Run the Web App

1. Verify the database connection string. Before running the web application, ensure your connection string points to your local development database. You can typically find the connection string in DataConfig.config or Web.config.
2. Update the Sitefinity license file. Navigate to App_Data/Sitefinity and replace the existing Sitefinity.lic file with the license that matches your newly upgraded Sitefinity version.
3. Rebuild the solution. Perform a full solution rebuild to ensure all projects compile successfully after the NuGet upgrade.
4. Fix any remaining build errors. If the build fails, resolve missing references, package conflicts, or compilation errors. Rebuild again until the solution compiles without errors.
5. Review and update custom page templates.

   If your site uses custom MVC page templates, it is important to compare them against the updated Bootstrap 5 templates before running the application. Starting with Portal Connector 6.1.0.151, new resource‑placement features were introduced that rely on additional section definitions inside the default layout templates.

   These updated Bootstrap 5 templates include new required helper tags such as:

   @Html.Section("jquery")
   @Html.Section("frameworks")
   @Html.Section("plugins")
   @Html.Section("bottom")

   Custom templates created prior to 6.1 will not contain these sections, which can lead to runtime errors such as: “A section with name 'plugins' could not be found.”

   To ensure compatibility, compare your custom templates against the latest Bootstrap 5 template located at:

   ResourcePackages/Bootstrap5/Mvc/Views/Layouts/Default.cshtml

   We strongly recommend using a file comparison tool such as WinMerge or Beyond Compare to merge the latest required helper tags and structural updates from the default template into your custom templates.

   This step is only necessary for projects that use custom templates. Default Bootstrap 5 templates are already updated during the upgrade process.

6. Run the application. Start the web application. When the site loads, Sitefinity will automatically detect that a database upgrade is required and will display the upgrade screen in the browser.

Startup encryption error (known scenario)

If the application fails to start after the upgrade and you see an error such as “Padding is invalid and cannot be removed”, this may be caused by previously encrypted Portal Connector credentials that are no longer compatible with the current encryption format. To resolve this issue, refer to the following knowledge base article:
Fixing startup error: “Padding is invalid and cannot be removed”

7. Complete the database upgrade. Allow the upgrade process to finish. When the upgrade succeeds, Sitefinity will display a button to continue to the site.
8. Verify that the site loads successfully. Click the Go to site button. The main page should load normally, confirming that both the build and the database upgrade were successful.

Deploy and Test

1. Confirm the develop database backup. Verify that the latest development database copy is available and up to date. Before deploying, ensure that a fresh backup exists and that no additional changes were made after the backup was created. This prevents data loss during the upgrade and ensures consistency between the code and database state.
2. Push upgrade changes to the designated branch. Commit and push the upgraded code to the branch used for deployments to the develop environment.
3. Trigger the deployment pipeline. When changes are pushed, the automated deployment pipeline will begin. Monitor the pipeline to ensure all steps complete successfully.
4. Verify the development environment. After deployment finishes, open the development site and confirm that the application loads without errors and that the upgrade is reflected correctly.
5. Perform a basic functionality check. Validate core pages, backend access, dynamic modules, and widgets to ensure the environment is functioning properly after the upgrade.

Configuration

After upgrading Sitefinity and Portal Connector, review your CRM and secure configuration settings to ensure the integration with Dataverse continues to function correctly. The following checks help prevent issues caused by breaking changes, updated encryption algorithms, or regenerated configuration values.

Verify Presentation Configuration

1. In Sitefinity, navigate to:
   /Sitefinity/Administration/ThePortalConnectorConfiguration#presentation
2. Open the Presentation section.
3. Set Resource Package Base to Bootstrap5.
4. Click Save.

Ensure that the pages where Portal Connector widgets are used also rely on Bootstrap 5 page templates. Existing pages created prior to the upgrade may continue to use older templates and should be reviewed and updated as needed.

Review CRM Configuration

• Refer to the configuration documentation for connecting your Portal Connector instance to your Dataverse environment:
  • Connect to CRM
  • Installing the CRM Solution
• If your connection string is no longer valid after the upgrade (for example, due to a breaking change), update it using the steps in the configuration documentation.
• In the Portal Connector configuration page, click the Install CRM Solution button. If an update is available, this will upgrade the Portal Connector solution inside Dataverse.

Verify CRM Connection Settings

• In Sitefinity, navigate to:
  /Sitefinity/Administration/Settings/Advanced
  Then open Portal Connector → CRM Connections → Default Connection.
• Confirm that the CRM Portal Id contains a valid GUID that matches the corresponding portal record in Dataverse. Ensure a new portal record was not created unintentionally during the upgrade.

Validate Secure Configuration

• Generating the secure configuration is automated, but quirks can occur during upgrades. A simple way to confirm that plugins and secure configuration are functioning is to attempt to invite or register a new contact on the portal.
• If you encounter security padding or encryption-related errors, your secure configuration may be out of sync. You can restore it by following this knowledge base article:
  Reconfiguring Secure Configuration for Dataverse CRM Solution