Migration Guide

This guide helps you migrate to RAP Builder from other RAP packaging approaches, including manual packaging and the legacy Publish to Relativity tool.

Why Migrate to RAP Builder?

RAP Builder provides several advantages over manual packaging or older tooling:

  • Automated validation - Catches mismatches between your code and application schema before deployment.
  • SDK version checking - Verifies that your assemblies reference the correct Relativity SDK versions.
  • Reproducible builds - The same inputs always produce the same RAP, eliminating inconsistencies from manual steps.
  • CI/CD integration - Runs as a command-line tool or MSBuild target, fitting naturally into automated pipelines.
  • Hash generation - Automatically computes and embeds SHA1 hashes for all assemblies and custom pages.

Migrating from Manual RAP Packaging or from Publish to Relativity Tool

The Publish to Relativity Tool is a legacy tool for only uploading resource files and custom pages to RAPs. RAP Builder replaces it with a standalone CLI tool to create a complete .rap file.

If you've been manually assembling RAP files (creating ZIP archives with application.xml and your artifacts), here's how to migrate.

Migration Steps

  1. Keep your existing application.xml. RAP Builder uses the same schema format. No changes are required to this file.

  2. Create a build.xml file. This is the new file RAP Builder needs. It tells the tool where to find your compiled artifacts:

    Copy 
    <BuildTools>
      <RAPBuilder>
        <Applications>
          <Application name="YourAppName" generatenuspec="true">
            <Destination>Artifacts\YourApp.rap</Destination>
            <ApplicationSchema>ApplicationsXML/application.xml</ApplicationSchema>
            <Assemblies>
              <Assembly>Source\YourApp\bin\YourApp.dll</Assembly>
              <!-- Add all assemblies that were in your manual RAP -->
            </Assemblies>
            <ResourceFiles>
              <!-- Add any resource files that were in your manual RAP -->
            </ResourceFiles>
            <CustomPages>
              <!-- Add custom pages with their GUIDs -->
              <CustomPage guid="your-custom-page-guid">Source\YourApp.CustomPage\PageDirectory</CustomPage>
            </CustomPages>
          </Application>
        </Applications>
      </RAPBuilder>
    </BuildTools>

  3. Verify consistency. Ensure that every assembly, resource file, and custom page filename matches its <Name> in application.xml (case-sensitive).

  4. Install RAP Builder. Install globally from the public feed:

    Copy 
    dotnet tool install --global Relativity.Server.RAPTool

    If you have the .nupkg downloaded to a local folder, install from that local source:

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

  5. Run your first build:

    Copy 
    relsvr-rap build --source . --input build.xml --version 1.0.0.0 --relativity-server-release 2025

  6. Remove manual packaging scripts once you've verified the RAP Builder output matches your expectations.

Common Pitfalls

  • Case sensitivity. Manual packaging may have been case-insensitive, but RAP Builder enforces exact case matching. Check that all filenames and GUIDs are consistent.
  • Missing assemblies. If your manual process included assemblies that aren't in application.xml, you'll need to add them to the schema.
  • Path separators. Use backslashes (\) or forward slashes (/) consistently in build.xml. Both are accepted.
Feedback