Update WebReports to the Latest Version

WebReports updates on Windows/IIS are performed by replacing the application's program files with a newer build while retaining the installation's configuration, application database, and stored files. The new build supplies the updated application code and static resources; your existing environment settings identify the database, licensed company, authentication, and integrations.

This procedure is for an existing Windows/IIS installation. For Docker, use Update an Existing WebReports Docker Deployment. Prepare and validate the package before stopping the live application.

What Is Updated and What Must Be Preserved

Before You Begin

• Review WebReports Deployment Requirements and Network Architecture and the notes for the release you will deploy. Use WebReports Version History Archive to find the published release guidance; ask BridgeWorks Support if instructions for your selected build are unclear.
• Test the update in a non-production environment and plan a maintenance window. Stop or coordinate publishing, scheduled processing, and other writers that share the application database or stored files.
• Confirm administrative access to the server, IIS Manager, application folders, and appropriate database-backup tools. Identify the WebReports site's actual Physical path and assigned Application pool in IIS Manager → Sites → WebReports → Basic Settings. Record the pool identity, bindings, authentication and relevant custom settings.
• Confirm the runtime required by the target release is installed. Current guidance requires the supported ASP.NET Core 10 Hosting Bundle; complete its installation/repair and required restart before the update window. See Download and Install the ASP.NET Hosting Bundle.
• Inventory every location containing configuration or persistent data, including storage outside the IIS physical path, custom report/data folders, uploaded branding, integration files, and certificates where applicable. Have a backup and rollback plan covering the application, its database, IIS settings, and all those locations.

Demo context: Examples use server WR-DEMO-SRV, site/pool WebReports, live folder C:\inetpub\WebReportsDemo, working update folder C:\Demo\WebReportsUpdate\Working\WebReportsInstall, and backups under C:\Demo\Backups\WebReports. Use the real deployment's paths. Images are labeled edited references using demo information; they do not show an update performed on a live server.

Preserve the live configuration: Never copy a default appsettings.json over the existing installation. A backup of that file alone is not a complete application or database backup.

Step 1: Download the Update Before Changing the Live Folder

Use Download the Latest WebReports Version or the official WebReportsInstall.zip download. Save the complete ZIP to a staging location outside the live website. Keep the downloaded package and record the intended build so the same files can be used for testing and deployment.

The ZIP contains application files, not an automatic update wizard. Do not begin deleting live files while waiting for the download.

Step 2: Unblock the Trusted ZIP

1. Right-click the officially downloaded WebReportsInstall.zip and select Properties.
2. On General, select Unblock if it appears, then Apply → OK.
3. If Unblock is absent, there is no unblock action to take in that dialog. Continue with extraction.

Do this before extraction so the internet-origin mark is not carried into extracted files. Follow Unblock WebReports Files for the full instructions.

Edited Windows 11 demo reference reused from Unblock WebReports Files. It uses a harmless sample ZIP; the pictured size and dates are examples, not the actual WebReports download. Select Unblock before Apply. Select the image to view it at full size.

Step 3: Extract and Prepare a Working Update Copy

1. Extract the prepared ZIP outside the live directory. Locate the application folder containing appsettings.json, web.config, BridgeWorks.Reports.Web.dll, the executable and supporting files, and wwwroot.
2. Keep an untouched extracted reference copy. Make a separate working update copy for deployment, such as C:\Demo\WebReportsUpdate\Working\WebReportsInstall.
3. Save the new appsettings.json template outside the working copy for comparison. Then remove only that default template from the working update copy so it is excluded from the later copy operation. Do not remove the live file.
4. Compare the new template with the existing settings. Note any release-required changes without replacing existing connection strings, license/company values, WRXValue, authentication, encryption settings, or unrelated configuration.
5. Review web.config and other package files that overlap custom configuration or branding. Prepare reviewed merged versions or explicit copy exclusions before deployment. Preserve the release's required ASP.NET Core process/hosting settings; do not overwrite custom authentication or routing inadvertently.

Edited demo reference: locate appsettings.json in the working update copy. Retain the new template separately, then exclude it from the deployment copy. This is not the live configuration, and the illustration does not show a deletion being performed. Select the image to view it at full size.

Record the staged application version. This PowerShell command reads file metadata and does not start WebReports:

(Get-Item -LiteralPath 'C:\Demo\WebReportsUpdate\Working\WebReportsInstall\BridgeWorks.Reports.Web.dll').VersionInfo |
    Select-Object FileVersion, ProductVersion

Compare the returned version with the intended build. Use this same staged build for the update; a ProductVersion may include build metadata after the version number.

Step 4: Stop the WebReports Site and Application Pool

1. In IIS Manager → Sites, select the actual WebReports site and select Stop under Manage Website.
2. Open Application Pools, select the pool assigned to that site, and select Stop. Confirm the selected pool is Stopped before replacing files.
3. If this pool serves other applications, coordinate the interruption with their owner before continuing. Stopping a shared pool affects all applications in it.

Stop the specific site and pool used by WebReports. Restarting or stopping the entire IIS service affects other hosted sites and is not the default update step. Stopping the site blocks new requests; stopping the pool ends its worker processing and releases application-file locks. If files remain locked, resolve the owning process before continuing.

Edited demo reference before stopping: select the pool assigned to the WebReports site and choose Stop, then confirm its state becomes Stopped. Other displayed pool properties are examples, not additional update settings. Select the image to view it at full size.

Step 5: Complete and Verify the Backups

1. With WebReports stopped and other writers coordinated, copy the entire current application directory to a new, secured backup location outside the web-served folder. For example: C:\Demo\Backups\WebReports\2026-10-27-before-update\Application. Use a new location for each update.
2. Back up the WebReports application database using the SQL Server or MySQL backup procedure appropriate to the database. A File Explorer copy of the application folder does not back up a running database.
3. Back up the external report/data-storage locations and custom files identified earlier, plus the IIS configuration and certificate material required by your recovery plan.
4. Verify that the backups completed and can be restored. Record the old application version and keep the corresponding application, database, configuration and file backups together.

Keep credentials, configuration backups and private-key material restricted to authorized administrators. Do not leave backup copies inside a public website directory.

Step 6: Prepare the Live Application Directory

Proceed only after the staged package is ready, the site/pool are stopped, and backups are verified.

1. Open the actual IIS physical directory recorded earlier.
2. Retain the live appsettings.json, the existing wwwroot folder, and every identified custom configuration/data item. This preservation list must include deployment-specific files and folders; it is not limited to two familiar names.
3. Remove the old program binaries and supporting components identified in the update plan as replaceable application files. Do not delete an unknown folder or a custom extension simply because it is absent from the example package.
4. Within wwwroot, remove the replaceable css and js folders so the update supplies a complete current set. If those folders contain approved local customizations, preserve and reconcile them first.
5. Retain custom branding, uploaded files and stored data in their actual locations. Review incoming files under wwwroot\assets or other shared names so the copy does not overwrite a custom logo or image unintentionally.

If you cannot distinguish application files from deployment data, stop and confirm the file list with BridgeWorks Support before deleting anything. The site remains stopped while the directory is prepared and the new files are copied.

Step 7: Copy the Prepared Update Files

1. Confirm the working update copy excludes its default appsettings.json and incorporates the configuration/custom-file decisions from Step 3.
2. Copy the contents of the prepared working application folder into the live physical directory. Do not create an extra nested WebReportsInstall folder inside it.
3. Approve replacement only for the application files and reviewed merged configuration in the update plan. If an unexpected prompt includes the live appsettings.json or a protected custom file, cancel and correct the working copy or exclusion list.
4. Wait for the full copy to finish. Resolve locked-file, skipped-file or permission errors before starting WebReports.

Confirm the live appsettings.json still contains the existing installation's values, the current DLL/executable and supporting files are present, and the package's wwwroot\css/wwwroot\js were deployed. Preserve the existing site bindings, pool assignment and permissions.

Step 8: Check Release-Specific Configuration and Dependencies

Apply the release-required changes identified before the update, using the retained template as a reference. Preserve valid JSON quoting, commas, value types and existing settings. Do not replace the complete configuration with a partial example.

• Confirm the required Hosting Bundle is installed and its restart instructions have been completed. A pending dependency restart must be resolved before validation.
• Confirm the preserved/merged web.config retains the new build's required module, process path and hosting model as well as your approved site-specific settings. File replacement can change settings stored in this file.
• Verify access for the existing IIS worker identity to the actual application and writable-data locations. See Configure IIS Folder Permissions for WebReports; do not change identities or permissions just because you are updating binaries.

SQL Server TLS: Encrypt=Yes enables connection encryption. With a trusted server certificate and matching server name, use certificate validation, for example TrustServerCertificate=False. The following is a partial demo fragment; preserve the existing database and login instead of entering these example values:

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=sql.demo.example.com,1433;Database=WebReportsDemo;User Id=webreports_demo;Password=<REPLACE_WITH_DATABASE_PASSWORD>;Connect Timeout=60;Encrypt=Yes;TrustServerCertificate=False"
  }
}

TrustServerCertificate=Yes encrypts the connection while bypassing server-certificate validation. It may be an approved self-signed/test-environment choice, but it is not a universal update requirement or a general fix for a connection failure. Review certificate trust, server name, driver behavior and your DBA's policy before changing the existing connection. See Microsoft's TrustServerCertificate documentation.

For MySQL installations, preserve the existing MySQL provider, database type and approved connection/TLS settings; do not apply SQL Server connection-string keywords to MySQL. Settings that encrypt stored WebReports connections are separate from database transport encryption.

Step 9: Start the WebReports Pool and Site

1. In IIS Manager → Application Pools, select the correct WebReports pool and select Start. Confirm its state becomes Started.
2. In Sites, select the WebReports site and select Start under Manage Website.
3. Open the configured HTTPS URL to initialize the application. Confirm the site/pool remain running and review any startup errors.

Edited demo reference before starting: choose Start for the updated WebReports pool, then confirm Started and start the site. The pictured Stopped state shows the selection before the action. Select the image to view it at full size.

Step 10: Verify the Version and Application Behavior

Read the version from the DLL in the live IIS physical directory and compare it with the staged version recorded in Step 3:

(Get-Item -LiteralPath 'C:\inetpub\WebReportsDemo\BridgeWorks.Reports.Web.dll').VersionInfo |
    Select-Object FileVersion, ProductVersion

Alternatively, right-click BridgeWorks.Reports.Web.dll in File Explorer, select Properties → Details, and review its file/product version. Checking a staging directory or an old backup does not verify the live installation. A sign-in-page screenshot alone does not prove the deployed version.

Then verify the running application:

1. Open the deployment's HTTPS URL, confirm certificate trust, and sign in using an authorized account.
2. Confirm database connectivity and run a representative report using the normal report data source.
3. Check existing settings, registration, sign-in integrations, stored reports, uploaded files and custom branding used by this installation.
4. Check required file-writing operations and review application/Windows logs for new errors.
5. If scheduling or unattended processing is used, verify it resumes and produces the expected result after startup.
6. For multiple application servers, repeat version and behavior checks on each node included in the update.

Retain the previous installation and corresponding backups until verification is complete and the rollback-retention period approved by your organization has passed.

Troubleshooting

WebReports Does Not Start After the Update

• Confirm the correct site/pool are started, the physical path points to the updated directory, and the copy completed without missing or locked files.
• Confirm the required Hosting Bundle/runtime and the deployment's web.config hosting settings. Review WebReports startup/application logs and Windows Event Viewer for the specific error.
• Confirm the live configuration was preserved and required folders remain accessible. Avoid repeatedly restarting all of IIS to diagnose one application.

WebReports Cannot Connect to SQL Server

Check the actual server/instance or TCP endpoint, database, login, password, network reachability, and the error message. For certificate errors, review the SQL certificate's trusted chain and name with your DBA. Do not add TrustServerCertificate=Yes automatically. For MySQL, review its provider-specific connection details.

Configuration Settings Are Missing

Compare the live configuration with the pre-update backup. Check whether the new default template or package web.config replaced a customized file. With WebReports stopped, restore or merge the appropriate settings for the deployed version, then verify the result.

The Updated Version Does Not Work Correctly

If rollback is required, coordinate it with BridgeWorks Support and the deployment/database administrator:

1. Stop the WebReports site and application pool and retain the failed deployment/logs for diagnosis.
2. Determine whether the new build changed the shared application database, configuration or stored files. Restoring program files does not reverse those changes.
3. Restore the compatible pre-update application and configuration. Restore the corresponding database and file backups where required, coordinating any changes made since the backup.
4. Verify the restored IIS settings, permissions and dependencies, then start the correct pool/site and confirm the previous version and representative operations.

Related Articles

• WebReports Deployment Requirements and Network Architecture
• Download the Latest WebReports Version
• Unblock WebReports Files
• Configure IIS and Deploy WebReports
• Configure IIS Folder Permissions for WebReports