Skip to content

Windows Application Integration

The Windows SDK provides unified RUM, Log, and HTTP Trace correlation capabilities for .NET/C# and Native C/C++. Applications choose an 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 deployment (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 correlated with RUM Resources; no standalone APM spans uploaded
Session Replay Disabled by default; WPF, WinForms, WinUI 3, WebView2, Electron, and Native can all explicitly enable and verify it; currently experimental
Feature Boundaries

Session Replay can be explicitly enabled and verified, but it remains an experimental capability and is not part of any stability or compatibility guarantee. Avalonia, .NET MAUI, and UWP do not have dedicated automatic collection adapters; frameworks that reuse the Native C ABI must manage window and control lifecycles themselves.

Application Integration

Select an Integration Method

Integration Method Applicable Applications Installation Method UI Boundary
.NET / C# WPF, WinForms, WinUI 3 Guance.Windows NuGet Framework automatic collection; WinUI 3 explicitly associates Window
Native C/C++ Win32, HWND-based desktop frameworks CMake, headers, import library, guance_windows_native.dll Window and control lifecycle: explicit C ABI calls
WebView2 Edge WebView2 hosted in .NET Ships with the .NET SDK Automatic discovery or explicit control association
Electron Electron Renderer + Windows Native Bridge Browser SDK + guance-windows-native[electron-bridge] Browser SDK only collects and serializes; the trusted Main Process and native side manage Session, queue, and upload

Create an Application

Log in to the Guance console, go to 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 C#, C++, WebView2, and Electron variants of the same Windows product can use the same application ID, with data distinguished by service, version, and runtime tags.

Installation

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

Samples:

We recommend installing guance-windows-native from the SDK vcpkg registry. Complete the registry, manifest, and CMake configuration as described in Quick Start; after installation, link the public CMake target:

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

If you need to debug the SDK source code, you can also build it 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 headers:

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

The architecture of the application, import libraries, and DLLs 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++ headers or import libraries.

Install the Browser SDK in the Renderer:

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

Electron full mode also requires configuring the SDK vcpkg registry as described in Quick Start, enabling the electron-bridge feature for guance-windows-native in vcpkg.json, and running vcpkg install --triplet x64-windows in manifest mode. This feature installs the Bridge EXE and the matching Native DLL; both must be packaged together.

Hybrid mode with C++ initialization does not start the Bridge EXE; the C++ host provides an adapter that writes to an existing SDK Handle. For complete installation, packaging, and capability boundaries, see Electron Monitoring.

Source code: Windows SDK source code

Initialization

Data Reporting

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 local deployment, install DataKit and enable the RUM Collector.

Initialization Sequence

// config must contain at least the reporting address and RUM application information; add Log/Trace as needed.
GuanceSdk.Init(config);
GuanceSdk.EnableAutomaticInstrumentation();

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

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

// Call 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() respectively after guance_sdk_init() succeeds.

The SDK uses a disk queue to cache RUM and Log data. Complete the shutdown flow on normal exit to avoid unpersisted operations when the process terminates.

Detailed Configuration

Advanced Scenarios

FAQ

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

Feedback

Is this page helpful?