Getting Started

This guide walks you through installing RAP Builder and building a Relativity Application Package (RAP).

Prerequisites

Before you begin, ensure you have the following:

• .NET SDK - required for dotnet restore and tool installation
• Visual Studio 2022 or later (or Build Tools for Visual Studio) - required to compile your solution; includes MSBuild. MSBuild must be added to the PATH environment variable.
• Node.js and npm - required if your RAP includes a custom page with front-end dependencies
• A Relativity Server application project with any compiled assemblies, resource files, or custom pages; all assemblies included in the RAP must be compiled against Relativity Server SDKs
  • For more information see Relativity Server SDK and API Packages Changes and our Server SDK Support Policy
• An application.xml file describing your application schema (exported from Relativity or created manually)
• A build.xml file that tells RAP Builder where all your application components are located (assemblies, resource files, custom pages)

Installing RAP Builder

RAP Builder is distributed as a .NET tool in a NuGet package (.nupkg), available on the GitHub releases page. You can install it globally or locally.

Global Installation (Recommended)

Global installation makes the relsvr-rap command available anywhere on your machine. This is the best option for most developers who work across multiple projects and want to run RAP Builder from any directory without extra setup.

dotnet tool install --global Relativity.Server.RAPTool

If the .nupkg file was downloaded locally instead of from a NuGet feed:

dotnet tool install --global Relativity.Server.RAPTool --add-source C:\path\to\nupkg-folder

After installation, verify it works:

relsvr-rap --help

Local Installation

Local installation scopes the tool to a specific directory and records the version in a dotnet-tools.json manifest that can be checked into source control. This is useful for CI/CD pipelines or team environments where you need to pin and reproduce an exact tool version per repository.

# Create a tool manifest (one-time setup, if not already present)
dotnet new tool-manifest

# Install the tool locally
dotnet tool install Relativity.Server.RAPTool

When installed locally, run the tool using:

dotnet tool run relsvr-rap build ...

Updating RAP Builder

To update to a newer version:

# Global
dotnet tool update --global Relativity.Server.RAPTool

# Local
dotnet tool update Relativity.Server.RAPTool

Uninstalling RAP Builder

# Global
dotnet tool uninstall --global Relativity.Server.RAPTool

# Local
dotnet tool uninstall Relativity.Server.RAPTool

Project Structure

A typical RAP project has the following layout. This matches the structure used in the server-sample-rap reference project:

MyRelativityApp/
─ ApplicationsXML/
│   └── application.xml              # Application schema
─ DevelopmentScripts/
│   └── build.xml                    # RAP Builder input file
─ Source/
│   ─ Directory.packages.props     # Central NuGet package version management
│   ─ MyApp.sln                    # Visual Studio solution
│   ─ MyApp/
│   │   ─ MyApp.csproj
│   │   ─ Agents/                  # Agent implementations
│   │   ─ EventHandlers/           # Event handler implementations
│   │   ─ Services/                # Kepler service implementations
│   │   └── bin/
│   │       └── MyApp.dll            # Compiled assembly
│   └── MyApp.CustomPage/
│       ─ MyApp.CustomPage.csproj  # ASP.NET MVC project
│       ─ Controllers/
│       ─ Views/
│       ─ package.json             # npm dependencies
│       └── MyApp.CustomPage/        # Published custom page files
─ Artifacts/                        # Output directory (created by build)
│   ─ Logs/
│   │   ─ buildsummary.log
│   │   ─ builderrors.log
│   │   └── rapbuild.log
│   └── MyApp.rap                     # The output RAP file
─ Directory.Build.props
─ Directory.Build.targets
─ nuget.config
└── build.ps1                         # Build script

Sample Project

The server-sample-rap repository is a complete, working example you can clone and build. It demonstrates:

• A .NET assembly project (SampleRap) with an agent, event handler, and Kepler service
• An ASP.NET MVC custom page project (SampleRap.CustomPage) with npm dependencies
• Central NuGet package version management via Directory.packages.props
• A nuget.config pointing to Relativity's Artifactory NuGet feed for SDK packages
• A build.xml and application.xml pair configured for RAP Builder
• A build.ps1 script that restores, compiles, and packages everything end-to-end

To build the sample:

git clone https://github.com/relativitydev/server-sample-rap.git
cd server-sample-rap
.\build.ps1

The output RAP file is written to Artifacts\SampleRap.rap.

Next Steps

• CLI: build Command - Full details on the build command and its arguments.
• Configuration Reference - Complete build.xml and application.xml schema documentation.
• Validation and Errors - Understanding error messages and SDK validation.