Visual Studio templates

You can streamline your application development and follow best practices by using Relativity templates for Visual Studio 2017 or 2019. Available templates include agents, custom pages, event handler types, and Integration Points. They contain required attributes, inherit from base classes as necessary, and include any methods that you need to override.

The templates are available in the relativitydev GitHub repository as an open source project: https://github.com/relativitydev/relativity-templates.

Simply modify the text in any placeholders that the template includes and then add your custom code to the file.

Available Relativity templates

The following templates appear under the Visual C# > Relativity subcategory after you install them in Visual Studio. See Use the Relativity project templates and Use the Relativity item templates.

Project or item template Use this template for developing...
Agent Background processes that don't interfere with user activities performed through the Relativity UI. For conceptual information, see Agent.
Console event handler An event handler that executes when the user navigates to the view page of an object. For conceptual information, see Console event handler.
Custom page form Custom pages using ASP.NET Web Forms. For conceptual information, see Custom page form.
Custom page MVC 5 Custom pages using ASP.NET MVC 5. For conceptual information, see Custom page MVC 5.
Kepler service

A custom service for REST exposed through a .NET interface. For conceptual information, see Kepler service.
Page Interaction event handler An event handler that you can use to inject JavaScript code or load your own Cascading Style Sheets (CSS) file on the view or edit page of an object. For conceptual information, see Page Interaction event handler.
Post Install event handler An event handler that executes immediately after the user installs an application. For conceptual information, see Post Install event handler.
Post Save event handler An event handler that executes after the property values on an object are written to the database. For conceptual information, see Post Save event handler.
Pre Cascade Delete event handler An event handler that executes when a user attempts to delete an object, which has dependent objects. For conceptual information, see Pre Cascade Delete event handler.
Pre Delete event handler An event handler that executes after a user clicks the Delete button or performs a Mass Delete in Relativity UI. For conceptual information, see Pre Delete event handler.
Pre Install event handler An event handler that executes during the installation of an application. For conceptual information, see Pre Install event handler.
Pre Load event handler An event handler that executes before Relativity loads a New, Edit, or View page. For conceptual information, see Pre Load event handler.
Pre Mass Delete event handler An event handler that performs a one-time operation on a group of objects before Relativity deletes those objects. For conceptual information, see Pre Mass Delete event handler.
Pre Save event handler An event handler that executes when the user clicks the Save or Save & Next button on a Relativity layout after changing a value for at least one field. For conceptual information, see Pre Save event handler.
Pre Uninstall event handler An event handler that executes cleanup tasks associated with removing an application from workspaces or from your Relativity environment. For conceptual information, see Pre Uninstall event handler.
Manager-Worker Agent template A manager - worker agent solution. It includes manager and worker agents, custom pages for managing the queues, and a post-install event handler. For conceptual information, see Manager-Worker Agent template.

Install the Relativity templates

You can obtain Relativity templates by downloading them from the Visual Studio Marketplace or adding them as extensions through Visual Studio. Before you install the Relativity templates, install the Relativity SDK and Visual Studio 2017 or 2019 on your machine.

Note: Use of the Relativity templates isn't supported in Visual Studio Express.

Download templates from Visual Studio Marketplace

Use these steps to download and install Relativity templates:

  1. Open the Relativity Templates page in the Microsoft Visual Studio Marketplace portal.
  2. Click Download to save the templates to your local machine.

    Note: If you have an older version of the Relativity templates installed, uninstall them.

  3. Close Visual Studio. You need to restart Visual Studio to populate the templates if it was open when you installed them.
  4. Double-click the Relativity Templates.vsix file.
  5. In the VSIX Installer dialog, click Install.

Add templates through Visual Studio

Use these steps to install the Relativity templates through Visual Studio:

Note: Relativity templates are only supported in VS2017 or VS2019.

  1. Open Visual Studio 2017 or 2019.

  1. Click Extensions > Manage Extensions in the menu bar.

    (Click to expand)

    Extensions menu

  2. In the Manage Extensions dialog, complete these steps:
    1. Click Online in the left pane, if it isn't selected.
    2. Enter Relativity Templates in the search bar on the right pane.
    3. Click Download on the matching extension.

      (Click to expand)

      Manage Extensions dialog

  3. Close Visual Studio. The VSIX installer automatically opens.
  4. Complete the steps in the VSIX installer to install the templates.

Use the Relativity project templates

You can use project templates when you want to create a new solution. To avoid errors, ensure that you installed the Relativity SDK correctly.

Use these steps to develop with a project template:

  1. Open Visual Studio.
  2. In the File menu, click New Project.
  3. In the New Project dialog, expand Visual C# Items, and then Relativity.
  4. Select a template for an agent, custom page, or event handler. See Available Relativity templates.
  5. Enter the solution name and other information.
  6. Click OK.

Use the Relativity item templates

You can use the item templates when you want to add an agent, custom page, or event handler to an existing solution. Ensure that you add the required references to the project to avoid error messages. Visual Studio displays an error indicating that you are missing assemblies.

Use these steps to add item templates:

  1. In Visual Studio, open your solution.
  2. In the Solution Explorer, right-click on a solution to display a menu.
  3. Click Add > New Item.
  4. In the Add New Item dialog, select Visual C# Items > Relativity.
  5. Select a template for an agent, custom page, or event handler. See Available Relativity templates.
  6. Enter the solution name and other information.

    Note: Add the references to the libraries for the type of item that you are adding to your project, such as kCura.EventHandler.dll and Relativity.API.dll. Otherwise, Visual Studio displays an error message when you build the project.

  7. Click OK.

Relativity Manager-Worker Agent template

The Manager-Worker Agent project template demonstrates an architectural pattern where a long-running agent task can be split into single or multiple manager/worker agents that execute the task in parallel. This template also contains the recommended best practices for coding and features like resource-pool aware agents, configure agents to run in off hours, a custom page to view manager/worker agents progress, unit tests projects etc.

The template creates a solution with the following projects:

Agents

This project includes a manager agent and a worker agent. Single or Multiple Manager/Worker agents can be installed in the environment. The only thing you should change is the ProcessRecordsAsync method of the Job class. This is where all of the agent work should happen.

Agents.NUnit

Add any unit tests for the agent project to this project.

CustomPages

This project includes custom pages to manage both the worker and the manager queue. Once you create an application which includes the custom pages, you can create a tab to view each queue using the following URLs:

Copy 
%ApplicationPath%/CustomPages/<AppGuid>/ManagerAgent/Index/?StandardsCompliance=true&%AppID% 
%ApplicationPath%/CustomPages/<AppGuid>/WorkerAgent/Index/?StandardsCompliance=true&%AppID%

CustomPages.NUnit

Add any unit tests for the custom pages to this project.

EventHandlers

This project includes a post-install event handler to create the underlying queue tables and error log table. It also includes a console event handler which can be used to manage jobs in the manager queue using a custom object if you do not wish to use the custom pages to manage the jobs.

EventHandlers.NUnit

Add any unit tests for the event handlers to this project.

Helpers

This project includes the shared code between the projects in the solution. The only thing you should change are these three constants in the Constant class:

  • ApplicationGuid - the GUID of the application.
  • ManagerQueueTab - the GUID of the tab which displays the manager queue custom page.
  • WorkerQueueTab - the GUID of the tab which displays the worker queue custom page.

Helpers.NUnit

Add any unit tests for the helpers project to this project.