TS-31191 update userguide

documentation/userguide.md

@@ -311,14 +311,58 @@ This approach also works if assemblies are spread in multiple directories.
 
 Since the generated coverage must be matched to the correct code revision (otherwise you get
 incorrect coverage results),
-you must furthermore configure a `revisionFile`, which contains
+you must declare the target revision in one of three ways.
+
+### 1. Via `revisionFile`
+
+The revision file consists of a single line of text: 
 
     revision: REVISION
 
 where `REVISION` is the VCS revision (e.g. Git SHA1 or TFS changeset ID) of your application's code.
 Similarly to the PDB directory, you can specify the revision file relative to the loaded assemblies like `pdbDirectory: '@AssemblyDir\revision.txt'`.
 This will scan the assembly directories in the order of loading for the first found revision file.
 
+### 2. Via `uploadTargetFile`
+
+Declaring an upload target file is especially useful, if you want to upload your traces to multiple Teamscale projects and/or different revisions. This file contains a single JSON array that maps Teamscale projects to revisions like this: 
+
+    [{project: "MyProject1", revision: "REVISION1"}, {project: "MyProject2", revision: "REVISION2"}, ...]
+
+where `MyProject1` and `MyProject2` are Teamscale project IDs. These can also be left empty if you instead prefer to move your traces to a file system directory or upload them to an Azure cloud storage.
+Please refrain from declaring a Teamscale project in the `teamscale` section of the `profiler.yml` if you declare a upload target file.
+### 3. Via embedded `Teamscale.resx` Resource 
+
+If you want to include the Teamscale project and revision information directly into your build, you can also create a Teamscale resource and include these information there.
+This option comes in handy if you record traces for library code and have these libraries set up in a separate Teamscale project. 
+
+Here is a step-by-step guide, how to create such a resource in Visual Studio: 
+
+1. Right-click on your Visual Studio project go to `Properties`.
+2. In the properties window, go to `Resources`.
+3. If there are no resources declared, click on the message to create a new default Resource, otherwise, add a new one. 
+4. In the Project Explorer under `Properties`, right-click the newly created Resource and rename it to `Teamscale.resx`.
+5. Optional: Already add a Revision/Timestamp entry into the Resource and a Teamscale Project name. This is optional because this can be done in a later stage with the Azure DevOps pipeline script `TeamscaleResourceUpdate.ps1`.
+
+After creating the Teamscale resource it will be integrated into your assembly. The Teamscale .NET profiler can then extract this information to identify the project and revision/timestamp to upload the trace files to. 
+To automatically update your revision and project entries of the Teamscale resource, you can add a new pipeline step that executes `TeamscaleResourceUpdate.ps1`. This script takes 3 arguments:
+ - `-path`: the path to your `Teamscale.resx` file
+ - `-project` (can be null): The name of the Teamscale project to upload to
+ - `-revision` or `-timestamp` (exclusive): The revision (e.g. Git SHA) or timestamp of the coverage. 
+
+This is an example how to integrate it into a Azure DevOps Pipeline:
+
+    variables:
+      GIT_REVISION: $(git rev-parse HEAD)
+
+    steps:
+    - powershell: |
+          .\TeamscaleResourceUpdate.ps1 -path "YourApplication\Properties\Teamscale.resx" -revision $(GIT_REVISION) -project "ProjectA"
+      displayName: 'Update Teamscale Resource'
+      workingDirectory: $(Build.Repository.LocalPath)
+
+**_Note:_** The Teamscale Resource can work in combination with a revision or an upload target file. So you can create a resource for your libraries and add a revision/uploadTarget file for your "main" application. 
+
 Finally, please configure sensible `assemblyPatterns` in order to only include your application's
 assemblies in the coverage analysis. This prevents lots of useless error log entries both in the
 uploader and in Teamscale. Patterns are glob patterns: `*` matches any number of characters,
@@ -344,6 +388,8 @@ Futher config options for the uploader in this mode:
 
 ## Example: Teamscale upload with local method-accurate coverage conversion
 
+With `revisionFile`: 
+
 **Profiler.yml:**
 
 ```yaml
@@ -368,10 +414,65 @@ match: [{
   }
 }]
 ```
-
 This assumes that the PDB files and `revision.txt` are stored in the same directory as `foo.exe`.
 If this is not the case, simply replace by absolute paths.
 
+
+With an `uploadTargetFile`:
+
+**Profiler.yml:**
+```yaml
+match: [{
+  executableName: foo.exe,
+  profiler: {
+    targetdir: C:\output
+  },
+  uploader: {
+    pdbDirectory: '@AssemblyDir',
+    uploadTargetFile: '@AssemblyDir\targets.json',
+    assemblyPatterns: {
+      include: [ "MyCompany.*" ]
+    },
+    teamscale: {
+      url: http://localhost:8080,
+      username: build,
+      accessKey: u7a9abc32r45r2uiig3vvv,
+      project: your_project,
+      partition: Manual Tests
+    }
+  }
+}]
+```
+(Note that you must then leave out the `project` in the `teamscale` section)
+This assumes that the PDB files and `targets.json` are stored in the same directory as `foo.exe`.
+If this is not the case, simply replace by absolute paths.
+
+
+With only embedded resources: 
+
+**Profiler.yml:**
+```yaml
+match: [{
+  executableName: foo.exe,
+  profiler: {
+    targetdir: C:\output
+  },
+  uploader: {
+    pdbDirectory: '@AssemblyDir',
+    assemblyPatterns: {
+      include: [ "MyCompany.*" ]
+    },
+    teamscale: {
+      url: http://localhost:8080,
+      username: build,
+      accessKey: u7a9abc32r45r2uiig3vvv,
+      partition: Manual Tests
+    }
+  }
+}]
+```
+(Note that you can then leave out the `project` in the `teamscale` section)
+
 ## Example: Teamscale upload without local method-accurate coverage conversion
 
 **Profiler.yml:**