You can use the following information to identify causes of deployment errors and to remotely debug custom pages. For information about configuring your environment for troubleshooting, see Development environment settings.
This page contains the following information:
- Remotely debug custom pages
- Custom page installation errors
- Custom pages not deployed
- ApplicationServer table out-of-date
- Mismatched versions of .dll files
- Can't access custom page
- Can't upload custom pages published through Visual Studio 2015
Remotely debug custom pages
Use these instructions to debug custom pages on a Relativity web server from your workstation:
- Configure remote debugging on the Relativity web server. See Remote Debugging on MSDN.
- On the web server, right-click on the Remote Debugging Monitor (msvmon) icon and select Run as administrator. The msvmon icon was added to your desktop when you completed the remote debugging setup in step 1.
The Remote Debugging Monitor displays a message containing the name of the server and the port that you use for the connection. It uses the format: <servername>:<port>.. In step 10, enter this information in the Qualifier box.
- Log in to Relativity and open the workspace containing your application.
- Click the Relativity Applications tab, and then click the name of your application to display the details view.
- Click the Unlock Application button to unlock your application, if necessary.
- Add your custom pages and their .pdb files to a zipped file.
- On the Custom Pages tab, load the zipped file into Relativity. This action overwrites your original zipped file containing the custom pages.
- Navigate to the details view of your application, and click the Push To Library button.
- On your workstation, open your custom page project.
- Attach the debugger to the w3wp.exe processes:
- Click Debug and then click Attach to Process.
- Enter <servername>:<port> in the Qualifier box. By default, the port is 4016.
- Select the w3wp.exe processes in the Available Processes box.
- Click Attach.
- On the Relativity server, check the status of the Remote Debugging Monitor in Visual Studio. It should indicate that you are connected.
- After you finish debugging, repeat steps 3 through 8, but don't add the .pdb files to the zipped file for your custom page.
Custom page installation errors
During custom page deployment, the Windows Service responsible for deploying custom pages to web servers may encounter errors. Examples of potential errors include the following:
- Web server out of memory and can't deploy the files.
- RAP package is corrupt.
- IIS configuration fails.
You can view error messages by clicking Alerts at the top of the Relativity window. One error message appears in the list of alerts for each application that fails to install on a server.
Click the Error Details link to view the Error Details page. The Error Details page displays the full contents of the error related to the application install failure.
Click the Try Installing Again link to prompt the service to re-install the application.
Custom pages not deployed
Your custom pages won't be deployed when the following service and agent aren't running:
- Web Processing Windows Service – If custom pages fail to deploy on a particular server, this Windows Service may be stopped on that server. The following message appears under the ALERT menu in Relativity:
Restart the kCura Relativity Web Processing Windows Service on the servers listed in the message.
- Custom Page Deployment Manager agent – If custom pages aren't deployed, confirm that this agent has been added and that it is running in your Relativity installation. For more information about this agent, see Basic concepts for custom pages.
ApplicationServer table out-of-date
If you delete the CustomPages subfolder from the EDDS folder on a web server, the ApplicationServer table becomes out-of-date if custom pages are deployed. If you attempt to reinstall the web component of Relativity, the Custom Page Deployment Manager agent runs but won't deploy any custom pages due to discrepancies in the ApplicationServer table.
To resolve this issue, clear the entries from the ApplicationServer table for the web server.
Mismatched versions of .dll files
When a custom assembly is loaded for an event handler, agent, or custom page, common .dll files (such as kCura.Relativity.Client.dll) are automatically copied into the domain from the lib folder. If you set the Specific Version option in Visual Studio, it may not match the version of the .dll files installed on the environment. This mismatch may prevent your application from executing properly, if at all.
Can't access custom page
When using applications with custom pages, you should keep a Relativity window open in the background throughout your session. This will maintain a connection to let the system know that your session is active. If you don't leave a Relativity window open in the background and another user views the User Status list, you can't access the custom page after closing your main Relativity window.
Can't upload custom pages published through Visual Studio 2015 and higher
If you implement a custom page through Visual Studio 2015 and higher, you may receive error messages when uploading it to Relativity. Visual Studio automatically adds a folder called roslyn in the bin directory when Roslyn compilation is enabled in an ASP.NET application. The roslyn folder contains executables that you can’t upload to Relativity through the ADS.
To resolve this issue, remove the following NuGet packages from your Visual Studio project:
- Microsoft.CodeDom.Providers.DotNetCompilerPlatform
- Microsoft.Net.Compilers
Recompile and publish your custom page. You can now upload your custom page to Relativity.
