Skip to content

Windows Application Integration

The Windows SDK provides unified RUM, Log, and HTTP Trace correlation for .NET/C# and Native C/C++. Applications choose the integration method based on the runtime, and data enters the console using the same application ID, service, and environment dimensions.

Reading Path

Prerequisites

Supported Scope

Item Supported Scope
Operating System Windows 10+
.NET Target Frameworks net6.0 / net8.0
Native Standard C11 ABI, C++17 adapter
NuGet Native RIDs win-x64 / win-x86 / win-arm64
vcpkg Native Dynamic x64-windows, non-UWP
Distribution NuGet / vcpkg
Data Reporting Public DataWay, Local Environment (DataKit)
RUM View, Action, Resource, Error, Long Task
Log Custom/Batch Log, Independent Queue, RUM Correlation; C# supports System.Diagnostics.Trace collection
Trace HTTP Header Propagation and RUM Resource Correlation, no independent APM Span uploaded
Session Replay Disabled by default; can be explicitly enabled and verified for WPF, WinForms, WinUI 3, WebView2, Electron, and Native. Currently experimental.
Feature Boundaries

Session Replay can be explicitly enabled and verified, but is still an experimental feature and not part of the stable compatibility commitment. Avalonia, .NET MAUI, and UWP do not have dedicated automatic collection adapters; frameworks that can reuse the Native C ABI need to manage the window and control lifecycle themselves.

Application Integration

Choose Integration Method

Integration Method Applicable Applications Installation UI Boundary
.NET / C# WPF, WinForms, WinUI 3 Guance.Windows NuGet Framework automatically collects; WinUI 3 explicitly associates with Window
Native C/C++ Win32, desktop frameworks based on HWND CMake, header files, import library, guance_windows_native.dll Window and control lifecycle explicitly calls C ABI
WebView2 Edge WebView2 in .NET host Included with .NET SDK Automatically discovered or explicitly associated control
Electron Electron Renderer + Windows Native Bridge Browser SDK + guance-windows-native[electron-bridge] Browser SDK only collects and serializes; trusted Main Process and native side manage Session, queue, and upload

Create an Application

Log in to the TrueWatch console, go to Real User Monitoring (RUM), and click Create Application:

  1. Enter the application name and application ID.
  2. Select Custom as the application type.
  3. Save the application ID for use in RumAppId or rum_app_id.

The same Windows product's C#, C++, WebView2, and Electron can share the same application ID, then differentiate data via service, version, and runtime tags.

Installation

dotnet add package Guance.Windows --version [latest_version]

Examples:

It is recommended to install guance-windows-native via the GuanceCloud vcpkg registry. Follow the registry, manifest, and CMake configuration in Quick Start; after installation, link against the public CMake Target:

find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)

For debugging the SDK source code, you can also build directly:

git clone https://github.com/GuanceCloud/datakit-windows-desktop.git
cd datakit-windows-desktop
cmake -S src/Guance.Windows.Native -B build/native -A x64
cmake --build build/native --config Release

Public header files:

  • guance_rum.h: C11 ABI, usable in both C and C++;
  • guance_sdk.hpp: C++ scoped Resource and std::terminate adapter;
  • guance_rum_winhttp.hpp: synchronous and asynchronous WinHTTP Resource/Trace adapters.

The architecture of the application, import library, and DLL must match. The current vcpkg port only provides dynamic x64-windows; the x86, x64, and ARM64 Native DLLs in the NuGet package are used by the .NET wrapper layer and do not include C/C++ header files and import libraries.

Install the Browser SDK in the Renderer:

npm install @cloudcare/browser-rum @cloudcare/browser-logs

For the full Electron mode, you also need to configure the GuanceCloud vcpkg registry as described in Quick Start, then enable the electron-bridge Feature for guance-windows-native in vcpkg.json, and execute vcpkg install --triplet x64-windows in manifest mode. This Feature installs the Bridge EXE and the matching Native DLL; both must be packaged together.

The mixed mode with C++ initialization does not start the Bridge EXE; the C++ host provides an Adapter that writes to an existing SDK handle. For full installation, packaging, and capability boundaries, refer to Electron Monitoring.

Source Code: GuanceCloud/datakit-windows-desktop

Initialization Notes

Reporting Method

Runtime Address Credential
.NET / C# GuanceConfig.DatawayUrl GuanceConfig.ClientToken
Native C/C++ guance_sdk_config.dataway_url guance_sdk_config.client_token
Runtime Address Credential
.NET / C# GuanceConfig.DatakitUrl Client Token not required
Native C/C++ guance_sdk_config.datakit_url Client Token not required

Before using the local environment, install DataKit and enable the RUM Collector.

Initialization Order

// config must include at least the reporting address and RUM application information; Log/Trace can be added as needed.
GuanceSdk.Init(config);
GuanceSdk.EnableAutomaticInstrumentation();

// Execute before the application exits.
await GuanceSdk.ShutdownAsync();

guance_sdk_handle rum = guance_sdk_init(&config);
guance_rum_start_view(rum, "MainWindow");

// Execute after the message loop ends.
guance_rum_stop_view(rum);
guance_sdk_shutdown(rum);

If Log or Trace is needed, call guance_log_configure() and guance_trace_configure() after guance_sdk_init() succeeds.

The SDK uses a disk queue to cache RUM and Log. Ensure proper shutdown on normal exit to avoid losing unpersisted operations when the process terminates.

Detailed Configuration Entry Points

Advanced Scenarios

Frequently Asked Questions

For issues related to initialization, data reporting, desktop UI, WebView2, Electron, Log, Trace, and Session Replay, see Troubleshooting.