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 select an integration method based on the runtime, and data enters the console with the same application ID, service, and environment dimensions.

Reading Guide

Prerequisites

Supported Scope

Item Supported scope
Operating system Windows 10+
.NET target frameworks net6.0 / net8.0
Native standards 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 deployment (DataKit)
RUM View, Action, Resource, Error, Long Task
Log Custom/batch Log, independent queue, RUM correlation; C# supports collection via System.Diagnostics.Trace
Trace HTTP Header propagation and RUM Resource correlation; does not upload standalone APM spans
Session Replay Disabled by default; requires installation of a matching optional component and explicit enablement; supports WPF, WinForms, WinUI 3, WebView2, Electron, and Native; currently an experimental capability
Feature Boundaries

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

Application Integration

Choose an SDK and Runtime

SDK and runtime Applicable applications Installation method UI boundary
.NET / C# WPF, WinForms, WinUI 3 Guance.Windows NuGet Automatic collection by the framework; WinUI 3 requires explicit Window association
Native C/C++ Win32, desktop frameworks based on HWND CMake, header files, import libraries, guance_windows_native.dll Explicit C ABI calls for window and control lifecycles
WebView2 Edge WebView2 in a .NET host Included with the .NET SDK Automatic discovery or explicit control association
Electron Electron Renderer + Windows Native Bridge Browser SDK + guance-windows-native[electron-bridge] The Browser SDK only collects and serializes; the trusted Main Process and native side manage sessions, queues, and uploads

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.

C#, C++, WebView2, and Electron in the same Windows product can use the same application ID, and you can then distinguish data by service, version, and runtime tags.

Choose an Integration Method

On the application configuration page, select Agent Auto-Integration or Manual Integration, and then complete Integration Configuration. For an existing application, go directly to the configuration page to continue integration.

Integration method Use cases Entry point
Agent Auto-Integration Want a coding assistant to analyze the project and complete SDK integration Copy the prompt generated by the console and hand it to the coding assistant for execution in the application code repository
Manual Integration Want to install the SDK and configure parameters yourself Confirm the data reporting method, then complete configuration according to this document and Quick Start

Agent Auto-Integration

  1. On the current application's configuration page, select Agent Auto-Integration.
  2. Copy the complete prompt from Integration Configuration, and ensure that it uses the current application's integration information.
  3. Open the coding assistant in the application code repository, paste the prompt, and let the Agent analyze the project and complete the SDK configuration according to the integration guide.
  4. Build and run the application, trigger operations such as page views, and confirm in the current application's Explorer that data is received.

If the page indicates that the Personal API Key or temporary authorization code is not ready, follow the prompts to complete it, and then copy the prompt again.

Manual Integration

On the application configuration page, select Manual Integration, and confirm the data reporting method:

  • Public DataWay: Obtain the reporting URL and Client Token from the current application's integration configuration; you do not need to deploy DataKit yourself.
  • Local deployment: Use a deployed DataKit to receive data, and make sure that the application can access its reporting URL.

Complete SDK installation, initialization, and verification by following Installation and Quick Start below. If an SDK configuration already exists, review and reuse it first to avoid duplicate initialization.

Installation

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

When using Session Replay, add Guance.Windows.SessionReplay at the same version. For installation and migration requirements, see Optional Component Installation.

Samples:

We recommend installing guance-windows-native through the SDK vcpkg registry. For the registry, manifest, and CMake configuration, follow 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 header files:

  • guance_rum.h: C11 ABI, usable from 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 libraries, and DLLs must match. The current vcpkg port provides only dynamic x64-windows; the x86, x64, and ARM64 Native DLLs in the NuGet package are for the .NET wrapper layer and do not include C/C++ headers or import libraries. Session Replay is installed through the replay feature of the same port.

Install the Main Process Adapter and Renderer Browser SDK:

npm install @cloudcare/electron-native-adapter@alpha @cloudcare/browser-rum @cloudcare/browser-logs

In Electron full mode, the npm Adapter downloads the base runtime and manages the Bridge EXE. When using Replay, you also need to explicitly install the Replay supplementary archive of the same version and architecture, and package it with the base runtime outside the ASAR.

In hybrid mode initialized by C++, the host starts a named-pipe Bridge Server, and the Electron Adapter connects to an existing SDK Handle; the Replay component is provided by the host's vcpkg replay feature. For complete installation, packaging, and capability boundaries, see Electron Monitoring.

Source Code: Windows SDK source code

Initialization

Reporting Methods

Runtime URL Credentials
.NET / C# GuanceConfig.DatawayUrl GuanceConfig.ClientToken
Native C/C++ guance_sdk_config.dataway_url guance_sdk_config.client_token
Runtime URL Credentials
.NET / C# GuanceConfig.DatakitUrl No Client Token required
Native C/C++ guance_sdk_config.datakit_url No Client Token required

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

Initialization Order

// config must contain at least the reporting URL and RUM application information; add Log/Trace 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 you need Log or Trace, after guance_sdk_init() succeeds, call guance_log_configure() and guance_trace_configure() respectively.

The SDK uses an on-disk queue to buffer RUM and Log data. Complete the shutdown process on normal exit to avoid operations that have not been persisted when the process terminates.

Detailed Configuration

Advanced Scenarios

FAQ

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

Feedback

Is this page helpful?