Skip to content

Commit 0a30f0e

Browse files
griffin-meteviagriffin-metevia
committed
REL-1238691: PR feedback
1 parent b5950ec commit 0a30f0e

2 files changed

Lines changed: 82 additions & 156 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ Before running the build, ensure the following tools are installed and available
99
- **[.NET SDK](https://dotnet.microsoft.com/download)** — required for `dotnet restore`
1010
- **[MSBuild](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild)** — required to compile the solution (included with Visual Studio or the Build Tools for Visual Studio)
1111
- **[Node.js and npm](https://nodejs.org/)** — required to install front-end dependencies for the custom page
12-
- **[relsvr-rap CLI](relsvr-rap-Usage-Guide.md)** — Relativity's RAP build tool; This should be installed from the Relativity.Server.RAPTool NuGet package using `dotnet tool install`
12+
- **[relsvr-rap CLI](relsvr-rap-Usage-Guide.md)** — Relativity's RAP build tool; intall from the Relativity.Server.RAPTool NuGet package using `dotnet tool install`
1313

1414
## Building
1515

@@ -53,7 +53,7 @@ Artifacts/
5353
└── SampleRap.rap # The final Relativity Application Package
5454
```
5555

56-
**`SampleRap.rap`** is the primary output. It is a ZIP-based package that can be installed into a Relativity Server environment. It contains:
56+
**`SampleRap.rap`** is the primary deployable output. It is a ZIP-based package that can be installed into a Relativity Server environment. It contains:
5757
- `SampleRap.dll` — the main .NET assembly (agents, event handlers, services)
5858
- The compiled `SampleRap.CustomPage` ASP.NET MVC application (zipped as a custom page)
5959
- `application.xml` — the Relativity application schema defining the app's components

‎relsvr-rap-Usage-Guide.md‎

Lines changed: 80 additions & 154 deletions
Original file line numberDiff line numberDiff line change
@@ -1,228 +1,154 @@
11
# relsvr-rap Command-Line Usage Guide
22

3-
The `relsvr-rap` CLI tool builds Relativity Application Package (RAP) files from source assemblies and custom pages.
3+
The `relsvr-rap` CLI builds Relativity Application Package (RAP) files from your application schema, assemblies, and custom pages.
44

55
## Command Syntax
66

7-
```
8-
relsvr-rap build --source <path> --input <file> --version <version> --relativity-server-release <year> [--warnings-as-errors] [--log-file <path>] [--log-level <level>]
7+
```text
8+
relsvr-rap build --source <path> --input <file> --version <version> --relativity-server-release <year> [--warnings-as-errors <true|false>] [--log-file <path>] [--log-level <level>]
99
```
1010

1111
## Parameters
1212

1313
| Parameter | Required | Type | Description |
1414
|-----------|----------|------|-------------|
15-
| `--source` | Yes | String | The root directory of the repository containing your RAP source files. All paths in the input build XML file are relative to this directory. |
16-
| `--input` | Yes | String | Path to the build configuration XML file (e.g., `build.xml`) that defines the RAP structure, assemblies, custom pages, and resources. Path can be relative to `--source` or absolute. |
17-
| `--version` | Yes | String | The application version number to assign to the RAP package (e.g., `1.0.0.0`). This is the RAP version, NOT the Relativity application schema version. |
18-
| `--relativity-server-release` | Yes | Integer | The version of Relativity Server that the RAP targets. Use: `2024`, `2025`, etc. Determines which SDK versions are used for validation. `2024` is the minimum version. |
19-
| `--warnings-as-errors` | No | Boolean | **Default: true**. When enabled, validation warnings cause the build to fail. Set to `false` to treat warnings as non-fatal. |
20-
| `--log-file` | No | String | File path where build logs should be written (e.g., `Artifacts/Logs/build.log`). If not specified, logs only appear in console output. |
21-
| `--log-level` | No | String | Sets the logging verbosity. Values: `Debug`, `Information`, `Warning`, `Error`, `Fatal`. Default is `Information`. |
15+
| └──source` | Yes | String | Repository root for the RAP build. Paths inside the input XML are resolved from this directory. |
16+
| └──input` | Yes | String | Path to the RAP build XML (for example, `DevelopmentScripts\build.xml`). Can be absolute or relative to └──source`. |
17+
| └──version` | Yes | String | RAP package version (for example, `1.0.0.0`). |
18+
| └──relativity-server-release` | Yes | Integer | Target Relativity Server release year (for example, `2024`, `2025`). |
19+
| └──warnings-as-errors` | No | Boolean | Treat warnings as build failures when set to `true`. |
20+
| └──log-file` | No | String | File path for build logs (for example, `Artifacts\Logs\rapbuild.log`). |
21+
| └──log-level` | No | String | Logging verbosity. Typical values: `Debug`, `Information`, `Warning`, `Error`, `Fatal`. |
2222

23-
## Command-Line Examples
23+
## Quick Start for This Repository
2424

25-
### Basic Build
25+
From the repo root (`server-sample-rap`):
26+
27+
```powershell
28+
relsvr-rap build `
29+
Sour --source "C:\Projects\MyRelativityApp" `
30+
--input "DevelopmentScripts\build.xml" `
31+
--version "1.0.0.0" `
32+
--relativity-server-release 2024 `
33+
--log-file "Artifacts\Logs\rapbuild.log"
2634
```
35+
36+
The repository build script (`build.ps1`) already runs this command after restore/build steps.
37+
38+
## Additional Examples
39+
40+
### Basic Build
41+
42+
```powershell
2743
relsvr-rap build --source C:\MyApp --input DevelopmentScripts\build.xml --version 1.0.0.0 --relativity-server-release 2025
2844
```
2945

30-
### Build with Logging
31-
```
32-
relsvr-rap build --source C:\MyApp --input build.xml --version 1.2.3.4 --relativity-server-release 2024 --log-file Artifacts\Logs\build.log
33-
```
46+
### Disable Warnings-As-Errors
3447

35-
### Build with Warnings as Errors Disabled
36-
```
37-
relsvr-rap build --source C:\MyApp --input build.xml --version 2.0.0.0 --relativity-server-release 2025 --warnings-as-errors false
48+
```powershell
49+
relsvr-rap build --source C:\MyApp --input DevelopmentScripts\build.xml --version 2.0.0.0 --relativity-server-release 2025 --warnings-as-errors false
3850
```
3951

40-
### Complete Example with All Options
41-
```
52+
### Full Example
53+
54+
```powershell
4255
relsvr-rap build `
4356
--source "C:\Projects\MyRelativityApp" `
4457
--input "DevelopmentScripts\build.xml" `
4558
--version "1.5.0.0" `
4659
--relativity-server-release 2025 `
4760
--warnings-as-errors false `
48-
--log-file "Artifacts\Logs\rap-build.log" `
61+
--log-file "Artifacts\Logs\rapbuild.log" `
4962
--log-level Debug
5063
```
5164

52-
## Example Repository Structure
65+
## Expected Repository Layout
5366

54-
Here's a typical repository layout for a RAP project with assemblies and a custom page:
55-
56-
```
67+
```text
5768
MyRelativityApplication/
5869
├── DevelopmentScripts/
59-
│ └── build.xml # RAP build configuration
70+
| └── build.xml
6071
├── ApplicationsXML/
61-
│ └── application.xml # Relativity application schema
72+
| └── application.xml
6273
├── Source/
63-
│ ├── MyApp/ # Main application assembly project
64-
│ │ ├── MyApp.csproj
65-
│ │ ├── bin/
66-
│ │ │ └── Debug/
67-
│ │ │ └── MyApp.dll # Main assembly to include in RAP
68-
│ │ ├── Agents/
69-
│ │ │ └── MyAgent.cs
70-
│ │ ├── EventHandlers/
71-
│ │ │ └── InstallHandler.cs
72-
│ │ └── Services/
73-
│ │ └── MyService.cs
74-
│ │
75-
│ ├── MyApp.CustomPage/ # Custom page (ASP.NET MVC/Blazor)
76-
│ │ ├── MyApp.CustomPage.csproj
77-
| | ├── MyApp.CustomPage
78-
│ │ │ └── MyApp.CustomPage.dll
79-
│ │ │ └── Views/
80-
│ │ │ ├── Home/
81-
│ │ │ │ └── Index.cshtml
82-
│ │ │ └── Shared/
83-
│ │ │ └── _Layout.cshtml
84-
│ │ ├── bin/
85-
│ │ │ └── Debug/
86-
│ │ │ └── MyApp.CustomPage.dll
87-
│ │ ├── Controllers/
88-
│ │ │ └── HomeController.cs
89-
│ │ ├── Views/
90-
│ │ │ ├── Home/
91-
│ │ │ │ └── Index.cshtml
92-
│ │ │ └── Shared/
93-
│ │ │ └── _Layout.cshtml
94-
│ │ ├── Content/
95-
│ │ │ ├── styles.css
96-
│ │ │ └── logo.png
97-
│ │ └── App_Start/
98-
│ │ ├── RouteConfig.cs
99-
│ │ └── BundleConfig.cs
100-
│
101-
├── Artifacts/ # Build output (created during build)
102-
│ ├── Logs/
103-
│ │ ├── buildsummary.log
104-
│ │ └── builderrors.log
105-
│ ├── NuGet/
106-
│ │ └── MyRelativityApplication.1.0.0-local.nupkg
107-
│ └── MyRelativityApplication.rap # Final RAP package
74+
| ├── MyApp/
75+
| | ├── MyApp.csproj
76+
| | └── bin/
77+
| | └── MyApp.dll
78+
| └── MyApp.CustomPage/
79+
| ├── MyApp.CustomPage.csproj
80+
| ├── Controllers/
81+
| ├── Views/
82+
| └── MyApp.CustomPage/
83+
└── Artifacts/
84+
├── Logs/
85+
└── MyRelativityApplication.rap
10886
```
10987

11088
## build.xml Configuration
11189

112-
The build XML file referenced by `--input` should follow this structure:
90+
The XML file provided to └──input` defines what goes into the RAP package.
11391

11492
```xml
115-
<?xml version="1.0" encoding="UTF-8"?>
11693
<BuildTools>
11794
<RAPBuilder>
11895
<Applications>
119-
<Application name="MyRelativityApplication" generatenuspec="true">
120-
<!-- Output path for the RAP file -->
121-
<Destination>Artifacts\MyRelativityApplication.rap</Destination>
122-
123-
<!-- Path to the application schema XML -->
96+
<Application name="SampleRap">
97+
<Destination>Artifacts\SampleRap.rap</Destination>
12498
<ApplicationSchema>ApplicationsXML/application.xml</ApplicationSchema>
12599

126-
<!-- Assembly DLLs to include in RAP -->
127100
<Assemblies>
128-
<Assembly>Source\MyApp\bin\MyApp.dll</Assembly>
129-
<Assembly>Source\MyApp.Verifier\bin\MyApp.Verifier.dll</Assembly>
130-
<!-- Include any Relativity SDK dependencies that aren't built-in -->
131-
<Assembly>Source\MyApp.Verifier\bin\Relativity.Core.dll</Assembly>
101+
<Assembly>Source\SampleRap\bin\SampleRap.dll</Assembly>
132102
</Assemblies>
133103

134-
<!-- Optional: Resource files (images, documents, etc.) -->
135-
<ResourceFiles>
136-
<ResourceFile>Source\MyApp\Resources\logo.png</ResourceFile>
137-
<ResourceFile>Source\MyApp\Resources\documentation.pdf</ResourceFile>
138-
</ResourceFiles>
104+
<ResourceFiles />
139105

140-
<!-- Custom page definition with its unique GUID -->
141106
<CustomPages>
142-
<CustomPage guid="f28fb91d-16ea-40f3-b869-a08b1cd7159c">
143-
Source\MyApp.CustomPage\MyApp.CustomPage
144-
</CustomPage>
107+
<CustomPage guid="a412cfce-098d-4339-96ba-72933ac2e707">Source\SampleRap.CustomPage\SampleRap.CustomPage</CustomPage>
145108
</CustomPages>
146109
</Application>
147110
</Applications>
148111
</RAPBuilder>
149112
</BuildTools>
150113
```
151114

152-
## application.xml Schema File
115+
## application.xml Alignment Requirements
153116

154-
The `application.xml` file (referenced in build.xml) must match your build definition. The easiest way to
155-
generate the application.xml file is to export the applicaiton schema from Relativity. Key sections:
117+
The `application.xml` schema must stay aligned with `build.xml`.
156118

157-
```xml
158-
<?xml version="1.0" encoding="UTF-8"?>
159-
<Application xmlns:xsd="http://www.w3.org/2001/XMLSchema"
160-
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
161-
<DeploymentTarget>Server</DeploymentTarget>
162-
163-
<!-- List of assemblies (must match build.xml) -->
164-
<Assemblies>
165-
<Assembly>
166-
<Name>MyApp.dll</Name>
167-
<ArtifactId>1000001</ArtifactId>
168-
</Assembly>
169-
<Assembly>
170-
<Name>MyApp.Verifier.dll</Name>
171-
<ArtifactId>1000002</ArtifactId>
172-
</Assembly>
173-
</Assemblies>
174-
175-
<!-- Application metadata -->
176-
<Name>MyRelativityApplication</Name>
177-
<Guid>6374418f-6fd2-474e-8ce6-b22c046b4212</Guid>
178-
<Version>1.0.0.0</Version>
179-
180-
<!-- Custom pages (GUIDs must match build.xml) -->
181-
<CustomPages>
182-
<CustomPage>
183-
<Guid>f28fb91d-16ea-40f3-b869-a08b1cd7159c</Guid>
184-
<Name>MyApplication Page</Name>
185-
<FileName>MyApp.CustomPage.zip</FileName>
186-
</CustomPage>
187-
</CustomPages>
188-
189-
<!-- Define agents, event handlers, and other components -->
190-
<AgentTypes>
191-
<AgentType>
192-
<AgentTypeName>My Custom Agent</AgentTypeName>
193-
<FullNameSpace>MyApp.Agents.MyAgent</FullNameSpace>
194-
</AgentType>
195-
</AgentTypes>
196-
</Application>
197-
```
119+
- Assembly names in `application.xml` must match assemblies included in `build.xml`.
120+
- Custom page GUIDs must match exactly between both files.
121+
- The application name/version metadata should reflect the package you are building.
122+
123+
The easiest way to create `application.xml` is exporting the application schema from Relativity and then validating that it matches your build inputs.
198124

199125
## Build Output
200126

201-
After running the build command, the following artifacts are created:
127+
After a successful build in this repository:
202128

203-
```
129+
```text
204130
Artifacts/
205131
├── Logs/
206-
│ ├── buildsummary.log # General build information
207-
│ ├── builderrors.log # Errors only
208-
│ └── {assembly}.{framework}.TestResults.xml # Test results (if tests run)
209-
├── NuGet/
210-
│ └── MyApp.1.0.0-local.nupkg # NuGet package
211-
└── MyApp.rap # Final RAP package (ZIP-based)
132+
| ├── buildsummary.log
133+
| ├── builderrors.log
134+
| └── rapbuild.log
135+
└── SampleRap.rap
212136
```
213137

138+
`SampleRap.rap` is the deployable package.
139+
214140
## Common Errors and Solutions
215141

216142
| Error | Cause | Solution |
217143
|-------|-------|----------|
218-
| "Source directory does not exist" | Invalid `--source` path | Verify path exists and is accessible |
219-
| "Project input file does not exist" | Invalid `--input` path | Ensure build.xml exists at specified location |
220-
| "Assembly not found in schema" | Assembly in build.xml but not in application.xml | Add missing assembly to application.xml |
221-
| "Custom page GUID mismatch" | GUID in build.xml differs from application.xml | Ensure GUIDs match exactly |
222-
| "SDK version validation failed" | Assembly incompatible with target Relativity version | Check Relativity Server 2024/2025 SDK compatibility |
144+
| `relsvr-rap` is not recognized | Tool not installed or not on `PATH` | Install the tool and ensure your shell can resolve `relsvr-rap` |
145+
| Source directory does not exist | Invalid └──source` path | Verify the path exists and is readable |
146+
| Project input file does not exist | Invalid └──input` path | Ensure `DevelopmentScripts\build.xml` exists at the specified location |
147+
| Assembly not found in schema | `build.xml` and `application.xml` are out of sync | Add/update the assembly entry in `application.xml` |
148+
| Custom page GUID mismatch | GUID differs between files | Ensure the same GUID is used in both files |
223149

224150
## Return Codes
225151

226-
- `0` — Success
227-
- `1` — General error (file not found, invalid path, etc.)
228-
- `4` — RAPBuilderException (validation or build logic error)
152+
- `0` Success
153+
- `1` General error (for example, bad path or missing file)
154+
- `4` RAPBuilder validation/build logic error

0 commit comments

Comments
 (0)