Compilation

Contents

• Overview
• Compilation
  • Visual Studio
    • .NET Core (.NET Standard / .NET Framework)
    • .NET Framework (Legacy)
  • Build Environment
• Testing
• Version
• CI
• Dependencies

Compilation

Some of this information applies to an unreleased version of PrtgAPI

PrtgAPI provides full support for .NET Core, providing target frameworks for both net452 and netstandard2.0

Due to the current poor state of .NET Core tooling however, for development PrtgAPI provides both .NET Core SDK style projects (compatible with dotnet.exe / Visual Studio 2017+) as well as legacy .NET Framework style projects (compatible with Visual Studio 2015+). The PrtgAPI Build Environment provides a unified interface for compiling both the SDK and legacy style solutions.

Visual Studio

.NET Core (.NET Standard / .NET Framework)

1. Install Visual Studio 2017 (15.9.11) or higher with either of the following workloads
   • .NET Core cross-platform development
   • .NET desktop development + the .NET Framework 4.6.1 Targeting Pack component
2. Open PrtgAPIv17.sln from the repo root
3. Build!

On Windows, Debug will build assemblies for netstandard2.0, while Release will build assemblies for both net452 and netstandard2.0. On Linux, all projects (including test projects) will build assemblies for netcoreapp2.1. If you wish to import the netstandard2.0 assemblies in Windows PowerShell, you must have .NET Framework 4.7.1 installed.

Note: as of writing, due to the current immaturity of the .NET Core tooling, the following restrictions apply when utilizing PrtgAPIv17.sln

• When switching between Debug and Release you must close and reopen Visual Studio
• The debugger does not work when debugging under PowerShell 5.1, as Visual Studio improperly utilizes the CoreCLR debugger instead of the .NET Framework one. To debug PowerShell 5.1 you must either change the debug target framework in Directory.Build.props, or simply use the legacy PrtgAPI.sln which doesn't have to deal with this nonsense

.NET Framework (Legacy)

1. Install Visual Studio 2015 or higher. For Visual Studio 2017+, install the .NET desktop development workload. Open PrtgAPI.sln from the repo root
2. Open PrtgAPI.sln from the repo root
3. Right cick the PrtgAPI solution in Visual Studio and click Restore Restore NuGet Packages
4. Build!

Build Environment

Build

To build PrtgAPI using the command line, complete the following steps

1. Open build.cmd or build.sh from the project root
   • Note: if you are Linux or macOS you must already have PowerShell Core installed
2. Run Invoke-PrtgBuild
3. Done!

To build the legacy .NET Framework version of PrtgAPI, specify the -Legacy parameter

Invoke-PrtgBuild -Legacy

When building using the .NET Core SDK, Invoke-PrtgBuild will automatically install all dependencies required to complete the build. When building with -Legacy, Invoke-PrtgBuild will search for a version of MSBuild installed in Program Files or alongside Visual Studio. If MSBuild cannot be found, the build will fail.

By default, Invoke-PrtgBuild will compile for Debug. If you wish to compile for Release, specify the -Configuration parameter

Invoke-PrtgBuild -c Release

In the event you wish to debug an issue with the build, you can specify the -Dbg parameter to create a `.binlog trace that will automatically be opened in MSBuild Structured Log Viewer when the build completes.

Invoke-PrtgBuild -Dbg

Clear

To clear previous PrtgAPI builds, use the Clear-PrtgBuild cmdlet. By default Clear-PrtgBuild will attempt to perform a standard MSBuild clear of your solution. If you wish to force a clear however you can specify the -Full parameter

Clear-PrtgBuild -Full

--

PrtgAPI requires Visual Studio 2015. To compile PrtgAPI, simply open the file PrtgAPI.sln in the root of the repository then select Build -> Build Solution within Visual Studio.

PrtgAPI depends on several NuGet packages in order to compile. If you have disabled automatic restoration of NuGet packages, you can manually restore packages by right clicking the PrtgAPI solution within Solution Explorer and selecting Restore NuGet Packages

Tests

If you wish to run any unit tests, ensure Test -> Test Settings -> Keep Test Execution Engine Running is unticked to prevent the PowerShell tests from locking the assemblies (preventing recompilation or moving the files somewhere else). It is advised to group the tests in Test Explorer by Project to separate unit tests from integration tests.

If you wish to run integration tests, it is recommended to create a separate server for integration testing. When integration tests are run, PrtgAPI will create a backup of your PRTG configuration, run its tests, and then revert the server to its original settings. If integration tests do not run to their completion, PrtgAPI will automatically restore the previous config upon next executing integration tests.

To configure PrtgAPI for integration testing, please specify values for all fields listed in PrtgAPI.Tests.IntegrationTests\Settings.cs with values specific to your server. The system running integration tests must be able to connect directly to the server over the network. When specifying the credentials to connect to your server, you must specify a local user on the server; domain users are not currently supported.