Overview

InsertionsClient updates the versions of NuGet packages in default.config with the corresponding versions specified in manifest.json assets. It also updates the values of properties defined in .props files.

How does InsertionsClient work?

1. Loads into memory the contents of both default.config and manifest.json as well as all the .packageconfig files listed in the default.config
2. Searches default.config and .packageconfig files for corresponding NuGet packages for each manifest.json asset
3. For every match, the NuGet version in the config file is updated with that of the corresponding manifest.json asset
4. The updated default.config and .packageconfig's are saved on disk
5. If an access token is specified with -a: switch, binaries for the updated packages are downloaded. Content of the packages are used to update the values of properties defined in PackagePreprocessorDefinitions tag in .props files
6. Modified .props file are saved on disk

Input

1. -d: Path to the default.config. Example:

   -d:c:\default.config

2. -m: Path to the manifest.json. Example:

   -m:c:\files\manifest.json

3. -i: Path to ignored packages file [optional]. Example:

   -i:c:\files\ignore.txt

4. -idut Indicates that packages relevant to the .NET Dev UX team are ignored [optional]. If -i: is also set, the file specified with that option is used, superceding -idut.

   -idut

5. -p: Path to the directory to search for .props files [optional]. If left unspecified, all the .props files under src\SetupPackages in local VS repo will be searched.

   -p:C:\VS\src\SetupPackages

6. -a: Personal access token to access packages in VS feed [optional]. If not specified, props files will not be updated.

   -a:vv8ofhtojf7xuhehrFxq9k5zvvxstrqg2dzsedhlu757

7. -w: Maximum allowed duration in seconds, excluding downloads [optional]. Example:

   -w:60

8. -ds: Maximum allowed duration in seconds that can be spent downloading nuget packages [optional]. Example:

   -ds:240

9. -c: Maximum concurrency of default.config version updates [optional]. Example:

   -c:10

Warnings

1. NO SPACES ALLOWED IN EITHER default.config OR manifest.json FILE PATHS
2. NO SPACES ALLOWED IN props file search directory
3. The default duration & concurrency values should suffice

Log

• InsertionsClient creates a log detailing every step taken
• The logs are placed in the Logs folder relative to the location of the InsertionsClient.exe
• Full path to log file is display at the end of the program as well.

Log Format

Each log line details...

1. The time stamp when the message was logged
2. the id of the thread where the message was logged
3. the message logged

Sample Log Lines

12-3-2020 11:59:16.114133|thread:1|CMD line param. Specified default.config: C:\Users\bozturk\source\repos\VS\.corext\Configs\default.config
12-3-2020 11:59:16.122993|thread:1|CMD line param. Specified manifest.json: C:\Users\bozturk\source\repos\InsertionsClient\tests\InsertionsClientTest\Assets\manifest.json
12-3-2020 11:59:16.349088|thread:1|De-serialized 19 builds from manifest.json.
12-3-2020 11:59:16.380310|thread:1|Loading default.config content from C:\Users\bozturk\source\repos\VS\.corext\Configs\default.config.
12-3-2020 11:59:16.412066|thread:1|Loaded default.config content.
12-3-2020 11:59:16.419213|thread:1|Loading content of .packageconfig at C:\Users\bozturk\source\repos\VS\.corext\Configs\Microsoft.Developer.IdentityService\IdentityService.packageconfig.
12-3-2020 11:59:16.421827|thread:1|Loaded .packageconfig content.

Use

1. Launch command line session
2. Navigate to the location of InsertionsClient.exe
3. Alternative, if on WINDOWS, set InsertionsClient on the %path% variable to run the application from any location
4. Launch InsertionsClient.exe with the proper parameters

Examples

The examples below rely on the following conditions...

1. InsertionsClient.exe located on \tools
2. default.config located in \repos\Assets
3. manifest.json located in \repos\Assets

Opting to Specify File with NuGet Packages to Ignore

Location of additional needed resources...

1. ignored.txt located in \repos\Assets

$ \tools\InsertionsClient.exe -d:\repos\Assets\default.config -m:\repos\Assets\manifest.json -i:\repos\Assets\ignored.txt

Opting to Ignore .NET Dev UX NuGet Packages

$ \tools\InsertionsClient.exe -d:\repos\Assets\default.config -m:\repos\Assets\manifest.json -idut

Opting Not to Ignore any NuGet Packages

$ \tools\InsertionsClient.exe -d:\repos\Assets\default.config -m:\repos\Assets\manifest.json

Specifying an Access Token to Update .props Files

$ \tools\InsertionsClient.exe -d:\repos\Assets\default.config -m:\repos\Assets\manifest.json -a:vv8ofhtojf7xuhehroaq9k5zvvxstrqg2dzsedhlu757

Specifying a .props File Search Directory

$ \tools\InsertionsClient.exe -d:\repos\Assets\default.config -m:\repos\Assets\manifest.json -a:vv8ofhtojf7xuhehrFxq9k5zvvxstrqg2dzsedhlu757 -p:C:\VS\src\SetupPackages\DotNetCoreSDK

Output

InsertionsClient.exe outputs the results of running operations to both a persistent log file and to console.

Successful NuGet version update Every successfully updated NuGet version in default.config has a corresponding message such as:

12-3-2020 11:59:16.694366|thread:6|Package VS.Redist.Common.WindowsDesktop.SharedFramework.x64.3.1 was updated to version 3.1.2-servicing.20067.4

Completion statistics update duration statistics are summarized

Statistics:

ExactMatch - Update for case of matching manifest.json assets with multiple verions; where version of the exact matching NuGet asset was selected
No. Items: 31
Average: 41.4194-ms
Minimum: 5.0000-ms
Maximum: 269.0000-ms

NoMatch - No matching manifest.json assets for a given default.config NuGet
No. Items: 528
Average: 42.9811-ms
Minimum: 3.0000-ms
Maximum: 10,612.0000-ms

Completion Summary Upon completion, InsertionsClient.exe summarizes the duration & updated NuGet versions, as follows...

Duration: 480.00-ms.
Successful updates: 27.
Updated default.config NuGet package versions...
        VS.Redist.Common.AspNetCore.SharedFramework.x64.3.1, version: 3.1.2-servicing.20068.1
        VS.Redist.Common.AspNetCore.SharedFramework.x86.3.1, version: 3.1.2-servicing.20068.1
        ...