Quick Start¶
The Windows SDK provides two independent distribution channels: .NET/C# applications use Guance.Windows and its optional components via NuGet, while Native C/C++ applications use guance-windows-native and its optional features via the SDK's vcpkg registry. Both use the same RUM application ID and data reporting method, but their package versions, release cadence, and changelogs are independent of each other.
Applications support automatic Agent integration and manual integration. The following steps describe the minimal configuration for manual integration.
Prerequisites¶
- Create a "Custom" application in RUM and obtain the application ID.
- Prepare one data reporting method:
- Public DataWay: the reporting URL and Client Token;
- Local deployment (DataKit): a DataKit address reachable by the application process.
- Ensure the application runs on Windows 10 or later.
Integration Steps¶
- Choose the NuGet or vcpkg package based on your application's technology stack.
- Install the dependencies and fill in the RUM application and reporting configuration.
- Initialize the SDK and enable automatic instrumentation, Log, Trace, and Session Replay as needed.
- Run the application and confirm in the console that data is reported successfully.
Choose a Package¶
| Application Type | Package | Installation | Currently Supported |
|---|---|---|---|
| .NET / C# | Guance.Windows |
NuGet.org | net6.0, net8.0, net6.0-windows10.0.17763.0, net8.0-windows10.0.17763.0; x86, x64, and ARM64 native runtime assets |
| Native C/C++ | guance-windows-native |
SDK vcpkg registry | Windows x64, non-UWP; the first release is a dynamic library |
Version Information
This document uses [latest_version] to indicate the latest version. The NuGet search UI requires prerelease packages to be enabled; for production projects, replace [latest_version] with a verified specific version and pin the dependency.
.NET / C#: Using NuGet¶
Install in the project directory:
Or add it to the project file:
The NuGet package brings in the following native DLLs by runtime identifier (RID); no manual copying is required:
runtimes/win-x64/native/guance_windows_native.dll
runtimes/win-arm64/native/guance_windows_native.dll
runtimes/win-x86/native/guance_windows_native.dll
Native C/C++: Using vcpkg¶
Configure the SDK Registry¶
Create or update vcpkg-configuration.json in the project root directory. Replace the default registry baseline with the Microsoft vcpkg commit verified by your project; <latest-sdk-vcpkg-registry-commit> indicates the latest commit of the SDK registry. During integration, replace the placeholders with actual commits and pin them to ensure reproducible builds.
{
"default-registry": {
"kind": "git",
"repository": "https://github.com/microsoft/vcpkg",
"baseline": "<compatible-microsoft-vcpkg-commit>"
},
"registries": [
{
"kind": "git",
"repository": "https://github.com/GuanceCloud/gc-vcpkg-registry.git",
"baseline": "<latest-sdk-vcpkg-registry-commit>",
"packages": [
"guance-windows-native"
]
}
]
}
Declare Dependencies and Install¶
Declare the port in vcpkg.json in the project root directory:
Then install in manifest mode:
CMake Linking¶
Pass the vcpkg toolchain file when configuring CMake, then find and link the package in CMakeLists.txt:
find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)
You can use the C header guance_sdk.h, the signal-specific C headers guance_rum.h, guance_trace.h, and guance_log.h, or the C++ helper header guance_sdk.hpp. For the complete C API, see the public guance_sdk.h.
Install Optional Components¶
Starting with NuGet 0.1.0-alpha.9 and vcpkg 0.1.0-alpha.10, Session Replay is delivered as an optional component. If you only use RUM, Log, and Trace, installing the base package is sufficient; when upgrading an existing Replay application to the split-package version, you need to additionally install the Replay component, while the existing configuration and control calls are preserved.
| Capability | .NET / C# | Native C/C++ |
|---|---|---|
| Session Replay | Guance.Windows.SessionReplay |
The replay feature of the same port, which installs guance_windows_replay.dll |
When using Replay in .NET, add the following component and pin [latest_version] to the same NuGet version as the base package:
The Replay NuGet package depends exactly on the same version of the base package; the managed Replay package does not include the native Replay DLL. Native applications select the replay feature:
After installation, the native Replay DLL must be placed in the same directory as the same-version, same-architecture guance_windows_native.dll. Installing the component does not automatically enable Replay; you also need to configure enabling and starting recording. See RUM Configuration.
In Electron Full Mode, the npm adapter installs the additional Replay runtime at build time; in Mixed Mode, the native host installs the replay feature. See Electron Monitoring.
Minimal Initialization Example¶
Initialization requires the RUM application ID, service name, environment, and application version. Public DataWay mode uses DatawayUrl and ClientToken; when using a local deployment (DataKit), set only DatakitUrl, and a public token is not required.
#include "guance_sdk.h"
guance_sdk_config_v2 config; // Supported since vcpkg 0.1.0-alpha.9
guance_sdk_config_v2_init(&config);
config.dataway_url = "https://openway.<your-domain>";
config.client_token = "<client-token>";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "prod";
config.application_version = "1.0.0";
guance_sdk_handle sdk = guance_sdk_init_v2(&config);
if (sdk == nullptr) {
// Handle initialization failure.
}
#include "guance_sdk.h"
guance_sdk_config_v2 config; // Supported since vcpkg 0.1.0-alpha.9
guance_sdk_config_v2_init(&config);
config.datakit_url = "http://127.0.0.1:9529";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "local";
config.application_version = "1.0.0";
guance_sdk_handle sdk = guance_sdk_init_v2(&config);
After initializing once, explicitly flush the queue and shut down the SDK before the application exits:
Optional: Initialize Log, Trace, and Session Replay¶
- .NET/C# can optionally instrument WPF, WinForms, WinUI 3,
HttpClient, unhandled exceptions, and UI thread blocking automatically; callGuanceSdk.EnableAutomaticInstrumentation()before the first window is created. Native C/C++ integrates explicitly at window, command, and network boundaries through the public C API. - Trace headers should only be sent to trusted services. Use the target address allowlist in the Trace configuration to restrict which requests can have headers injected.
- The SDK uses privacy-preserving defaults. Session Replay is disabled by default and must be explicitly enabled; it is still an experimental feature and is not covered by a stable compatibility commitment.
For configuration of UI, WebView2, Electron, and the various signals, see Desktop UI Frameworks, WebView2 Monitoring, Electron Monitoring, RUM Configuration, Log Configuration, and Trace Configuration.
Verify the Integration¶
- Start the application and open at least one View.
- Perform a click operation and make an HTTP request.
- In RUM > Explorer, select the corresponding application and confirm that Session, View, Action, and Resource data appears.
- After enabling Log or Trace, confirm that log data and the Trace Header/RUM Resource correlation work correctly.
- After enabling Session Replay, confirm that the Replay upload diagnostic status is successful, and check the replay entry in the session details.
If there is no data in the console, see Troubleshooting.
Next Steps¶
- Full base parameters, cache, diagnostics, and lifecycle configuration: SDK Initialization
- RUM, Log, and Trace configuration: RUM Configuration, Log Configuration, Trace Configuration
- Desktop UI, WebView2, and Electron: Desktop UI Frameworks, WebView2 Monitoring, Electron Monitoring
- Privacy and data protection: Privacy and Permissions
Upgrades and Changelogs¶
NuGet and vcpkg use independent version streams; even if the version numbers are the same, they must not be treated as the same release:
| Distribution | Version Tag | Changelog |
|---|---|---|
| NuGet / C# | nuget_<semver> |
C# Changelog |
| vcpkg / Native C/C++ | vcpkg_<semver> |
Native C/C++ Changelog |
Stable versions in the form 1.2.3 are supported, as well as prerelease versions in the form 1.2.3-alpha.1 and 1.2.3-beta.1. When upgrading, read the changelog for the corresponding package separately and update the NuGet version or the vcpkg registry baseline; the two release streams are presented in separate sections in the Changelog.
FAQ¶
- Cannot find the package in the Visual Studio NuGet UI: enable "Include prerelease", or use the
dotnet add packagecommand given in this document. vcpkg installcannot find the port: verify that the registry URL, thepackageslist, and the pinned baseline invcpkg-configuration.jsonare correct, and run the installation in manifest mode from the project root directory.- The .NET application does not load the native DLL: verify that the project's target framework is one of the supported frameworks listed on this page, and that the RID used at publish time matches the architecture of the deployment environment.