Login
Home CMS Documentation Home CMS 10 Development Special Topics for Developers Upgrading DSS Manually

Upgrading DSS Manually

Prerequisites:

Ensure you have the following before starting the file merge process:

  • Permissions: System administrator permissions for both servers:
    1. DSS server
    2. CMS server
  • Customized DSS source code: Most recent version of your customized DSS solution.
  • Target DSS version: CMS platform version containing the DSS code for upgrade. This is the CMS platform version you will upgrade your customized DSS solution to and use for file comparison and merging.
    1. Download the installer package from Product Downloads.
    2. See Installing the Ingeniux CMS 10.5–10.6 Software Platform to install.
  • Comparison tool: WinMerge or similar file comparison software.
  • Development environment: Microsoft Visual Studio with NuGet Package Manager.
  • Backup: Complete backup of your customized DSS project.
    Warning
    Always work with a backup copy. Never perform merge operations directly on production code without proper version control and testing procedures.

Manual DSS upgrades preserve custom modifications while incorporating new features and bug fixes. Merge file changes between your customized DSS project and the updated target DSS version from the Ingeniux CMS product installer.

Plan carefully, compare systematically, and test thoroughly to maintain custom functionality while gaining the latest features and improvements. Always work with backups and document all changes.

Review CMS 10.5–10.6 Upgrade Considerations for additional DSS upgrade considerations. Contact Ingeniux Support for assistance with complex merges.

Steps include:

  1. Prepare for DSS Upgrade
  2. Identify Customizations
  3. Merge Upgrade Changes
  4. Verify Package Dependencies
  5. Build Solution
  6. Verify DSS Web.config
  7. Verify DSS Preview Web.config
  8. Test DSS Functionality

Prepare for DSS Upgrade

Extract the target DSS version and locate your customized DSS project to prepare for the upgrade process.

To prepare for DSS upgrade:
  1. Extract the target DSS version source code from the CMS platform installer:
    1. Navigate to the DSS folder in your CMS platform installation directory (e.g., [Drive:]\Ingeniux\CMS10.6\Installers\Dss).
    2. Extract dt.zip from this location to a working directory in your development environment.

      This .zip file contains the reference DSS project code for the target version you will upgrade to and will be used to compare and merge required changes to your customized DSS project.

  2. Locate the most recent version of your customized DSS project on the DSS server.

Identify Customizations

Compare your customized DSS project directory against the extracted target DSS (dt.zip) to identify changes for merging.

To identify custom DSS modifications:
  1. Open Winmerge or your preferred comparison tool and set up a directory comparison between your customized DSS and the target DSS project.
  2. Compare directories to identify version and customization differences.

    Focus on folders and files that commonly change between versions:

    • App_Code/
    • App_Start/
    • Controllers/
    • bootstrap3/css/
    • Models/
    • AssemblyInfo.cs
    • packages.config
    • Web.config

    See Modified DSS Files for additional files that may require attention.

  3. Document all custom modifications:
    1. List modified files.
    2. Document the purpose of each modification.
    3. Note custom code annotations and comments.

    Note
    Custom code annotations depend on your change tracking practices. Some modifications may not be clearly marked, making thorough code comparison essential to avoid losing custom functionality.

Merge Upgrade Changes

Prerequisites:
  • Commit all current changes to the customized DSS before starting the merge process.
  • Complete backup of your customized DSS solution.
    Warning
    Always work with a backup copy. Never perform merge operations directly on production code without proper version control and testing procedures.

Integrate new features and fixes from the target DSS upgrade version while preserving custom modifications.

Follow these merging practices:

  • Commit changes in logical groups when possible.
  • Maintain a detailed log of merge changes.
  • Update documentation for custom code modifications.
  • Document deployment considerations for the target DSS version.
To merge target DSS version changes into your customized DSS:
  1. Use the comparison tool to copy, merge, or delete code in your customized DSS solution based on your modification analysis.
  2. Copy new files from the target DSS version that don't exist in your customized project.
    Note
    Major version upgrades typically require more new files than minor upgrades. Common files for major version upgrades (such as CMS 9 to CMS 10) include:
    • AnalyticSource.config
    • Controllers/PreviewAssetController.cs
    • App_Code/PageBuilder.cs (CMS 9 upgrades to CMS 10 only)
  3. Merge changes carefully, preserving custom modifications while incorporating target improvements.
  4. Save all file changes.
  5. Verify whether files deleted in the target DSS version require removal from your customized DSS version.

Your customized DSS project dependencies and code changes now reflect the target DSS version with preserved customizations.

Verify Package Dependencies

Re-verify that NuGet packages were properly updated during your customized DSS merge upgrade process to ensure they meet target DSS version requirements. The code merge process applies changes and updates to NuGet package dependencies, including core DSS code changes.

To verify DSS NuGet package updates:
  1. Open packages.config from both your customized DSS and target DSS using the comparison tool.

    The packages.config file is located in each DSS root folder.

    Review Microsoft Learn: packages.config reference for file definition and structure details.

  2. Compare your customized DSS packages.config to the target DSS version to verify your customized DSS project's RTAPI NuGet package reflects the target DSS upgrade version.
    Important
    The RTAPI NuGet package version must match the target DSS upgrade version.

Task Troubleshooting: If your customized DSS project's NuGet package dependencies do not match the target DSS upgrade version, update the packages:

  1. Navigate to your customized DSS project root folder, then open your custom DSS solution (e.g., Dynamic_Site_Server_Instance.sln) in Microsoft Visual Studio.
  2. Click Tools > NuGet Package Manager > Manage NuGet Packages for Solution.
  3. Upgrade or install packages in your customized DSS that do not match the target DSS version.

    Review Microsoft Learn: Install and manage packages in Visual Studio using the NuGet Package Manager for installation and update procedures.

    Important
    Upgrade packages only. Do not downgrade unless specifically required.
  4. Close NuGet Package Manager and keep the DSS solution open in Visual Studio for next steps.

Build Solution

Build your DSS solution to test updates and resolve dependencies conflicts.

To build the customized DSS solution:
  1. Navigate to your customized DSS project root folder, then open your custom DSS solution (e.g., Dynamic_Site_Server_Instance.sln) in Microsoft Visual Studio.
  2. Open Solution Explorer.
  3. Right-click the solution in the Solution Explorer and select Build.
  4. Keep the DSS solution open in Visual Studio for next steps.

Task Troubleshooting: Resolve all build errors before proceeding to next set steps. Ensure you can successfully build the solution without errors or warnings. The merge process updates the Nuget packages.config file. Verify updates using the NuGet Package Manager.

Common build error resolutions:
  1. Missing dependencies: Use NuGet Package Manager to restore missing packages.
  2. Version conflicts: Identify and manually resolve conflicting package versions.
  3. Custom code issues: Review custom modifications for target DSS version compatibility.

Verify DSS Web.config

Verify your customized DSS Web.config file configurations.

To verify DSS Web.config settings:
  1. Open Solution Explorer in Visual Studio.
  2. Expand the solution and open Web.config.
  3. Verify the <appSettings>PageFilesLocation setting references your published content folder path.

    Replace placeholder text with your actual values.

    Customized DSS Web.config PageFilesLocation example
    <add key="PageFilesLocation" value="[Drive:]\[path-to-dss-instance]\[published-content-folder]" />
    Troubleshooting
    Update PageFilesLocation if the setting does not reference the absolute published content folder path, then save Web.config.
  4. Close Web.config.

Verify DSS Preview Web.config

Verify DSS Preview Web.config file configurations for your CMS site deployment.

To verify DSS Preview Web.config settings:
  1. Navigate to your DSS Preview directory [Drive:]\[path-to-cms-site-instance]\DSS_Preview\ on the CMS server.
  2. Open your customized DSS Preview solution (e.g., Dynamic_Site_Server_Instance.sln) in Visual Studio.
  3. Open Solution Explorer.
  4. Expand the solution and open Web.config.
  5. Verify the <appSettings>PageFilesLocation setting references your CMS App_Data\xml folder path.

    Replace placeholder text with your actual values.

    DSS Preview Web.config PageFilesLocation example
    <add key="PageFilesLocation" value="[Drive:]\[path-to-cms-site-instance]\App_Data\xml" />
    Troubleshooting
    Update PageFilesLocation if the setting does not reference the absolute XML folder path, then save Web.config.
  6. Note the @connectionstring attribute for the <connectionStrings>PreviewContentStore setting

    Replace placeholder text with your actual values.

    DSS Preview Web.config PreviewContentStore example
    <add name="PreviewContentStore" connectionString="Url = https://[cms-name]:[port-number]; Database = IGXContentStore; Certificate = [Drive:]\[path-to-cms-site-instance]\..\db\..\site\IngeniuxCMS.pfx;" />
  7. Navigate to [Drive:]\[path-to-cms-site-instance]\ on the CMS server, then open local-connection-strings.config in a text editor.
  8. Verify the <connectionStrings>IGXDBConnectionString setting matches the DSS Preview web.config@connectionstring attribute for PreviewContentStore.

    Replace placeholder text with your actual values.

    CMS site instance local-connection-strings.config IGXDBConnectionString example
    <add name="IGXDBConnectionString" connectionString="Url = https://[cms-name]:[port-number]; Database = IGXContentStore; Certificate = [Drive:]\[path-to-cms-site-instance]\..\db\..\site\IngeniuxCMS.pfx;" />
    Troubleshooting
    Update the DSS Preview Web.config@connectionstring attribute for PreviewContentStore if the value doesn't match the local-connection-strings.configIGXDBConnectionString value, then save Web.config.
  9. Close Web.config and local-connection-strings.config.

Test DSS Functionality

Test customized DSS functionality to verify successful merges and confirm custom features work correctly.

Include these tasks in your testing strategy:

  • Run the solution locally using Visual Studio or deploy to a staging DSS or DSS Preview site.
  • Confirm pages load correctly.
  • Test all custom functionality thoroughly.

Review Ingeniux CMS 10.5–10.6 DSS Upgrade Checklist for standard DSS upgrade verification tests.

Task Troubleshooting: If the DSS fails to run after upgrade:

  1. Check Configuration: Verify all configuration settings.
  2. Review Logs: Analyze application logs for error messages.
  3. Test Incrementally: Temporarily disable custom functionality to isolate issues.