Quick Start¶

The Windows SDK provides two independently released packages: .NET/C# applications use Guance.Windows via NuGet, and Native C/C++ applications use guance-windows-native from the GuanceCloud vcpkg registry. Both packages use the same RUM application ID and data upload method, but their package versions, release cadence, and changelogs are independent of each other.

Prerequisites¶

1. Create a "Custom" application in Real User Monitoring (RUM) and obtain the application ID.
2. Prepare one of the following data upload methods:
3. Public DataWay: upload address and Client Token.
4. Local environment deployment (DataKit): a DataKit address accessible to the application process.
5. Ensure that the application runs on Windows 10 or later.

Integration Steps¶

1. Select the NuGet or vcpkg package based on your application's technology stack.
2. Install the dependency and fill in the RUM application and upload configuration.
3. Initialize the SDK, and enable automatic collection, Log, Trace, and Session Replay as needed.
4. Run the application and verify successful data upload in the console.

Select a Package¶

.NET / C#: Using NuGet¶

Install in the project directory:

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

Or add to the project file:

<PackageReference Include="Guance.Windows" Version="[latest_version]" />

The NuGet package brings in the following Native DLLs based on the 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 GuanceCloud Registry¶

Create or update vcpkg-configuration.json in the project root directory. Replace the default registry baseline with a verified Microsoft vcpkg commit for your project; <latest-guance-vcpkg-registry-commit> represents the latest commit of the GuanceCloud registry. When integrating, replace the placeholder with the actual commit and pin it 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-guance-vcpkg-registry-commit>",
      "packages": [
        "guance-windows-native"
      ]
    }
  ]
}

Declare the Dependency and Install¶

Declare the port in vcpkg.json at the project root:

{
  "dependencies": [
    "guance-windows-native"
  ]
}

Then install in manifest mode:

vcpkg install

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, guance_log.h, or the C++ helper header guance_sdk.hpp. For the complete C API, refer to the public guance_sdk.h.

Minimal Initialization Example¶

During initialization, you must provide the RUM application ID, service name, environment, and application version. The public DataWay mode uses DatawayUrl and ClientToken; when using local environment deployment (DataKit), only set DatakitUrl without a public token.

using Guance.Windows;

GuanceSdk.Init(new GuanceConfig
{
    DatawayUrl = "https://openway.<your-domain>",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "prod",
    Version = "1.0.0"
});

GuanceSdk.EnableAutomaticInstrumentation();

using Guance.Windows;

GuanceSdk.Init(new GuanceConfig
{
    DatakitUrl = "http://127.0.0.1:9529",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "local",
    Version = "1.0.0"
});

#include "guance_sdk.h"

guance_sdk_config config;
guance_sdk_config_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.version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init(&config);
if (sdk == nullptr) {
    // Handle initialization failure.
}

#include "guance_sdk.h"

guance_sdk_config config;
guance_sdk_config_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.version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init(&config);

After initializing once, explicitly flush the queue and shut down the SDK before the application exits:

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(sdk);
guance_sdk_shutdown(sdk);

Optional: Initialize Log, Trace, and Session Replay¶

• For .NET/C#, you can optionally enable automatic instrumentation for WPF, WinForms, WinUI 3, HttpClient, unhandled exceptions, and UI thread blocking. Call GuanceSdk.EnableAutomaticInstrumentation() before the first window is created. For Native C/C++, use the public C API to explicitly instrument at window, command, and network boundaries.
• Trace headers should only be sent to trusted services. Use the target address allowlist in the Trace configuration to restrict requests that can be injected with headers.
• The SDK uses privacy-protecting configuration by default. Session Replay is disabled by default and must be explicitly enabled; it is still an experimental feature and is not part of the stability compatibility promise.

For configuration related to UI, WebView2, Electron, and individual signals, see Desktop UI Frameworks, WebView2 Monitoring, Electron Monitoring, RUM Configuration, Log Configuration, and Trace Configuration.

Verify Successful Integration¶

1. Start the application and open at least one View.
2. Perform a click action and initiate an HTTP request.
3. In RUM > Explorer, select the corresponding application and confirm that Session, View, Action, and Resource data appear.
4. After enabling Log or Trace, verify that log data and Trace Header/RUM Resource associations are working correctly.
5. After enabling Session Replay, confirm that the Replay upload diagnostic status is successful, and check the replay entry in the session details.

If no data appears in the console, refer to Troubleshooting.

Next Steps¶

• Complete base parameters, caching, diagnostics, and lifecycle configuration: SDK Initialization
• Configuration for RUM, Log, and Trace: 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 are not considered the same release:

Stable versions like 1.2.3 are supported, as well as pre-release versions in the form 1.2.3-alpha.1 and 1.2.3-beta.1. When upgrading, read the corresponding changelog for each package and update the NuGet version or vcpkg registry baseline. The two release streams are displayed in separate sections in the Changelog.

Frequently Asked Questions¶

• The package is not found in the NuGet UI in Visual Studio: enable "Include prerelease", or use the dotnet add package command provided in this document.
• vcpkg install does not find the port: verify that the registry URL, packages list, and pinned baseline in vcpkg-configuration.json are correct, and run the installation in manifest mode from the project root.
• The .NET application does not load the Native DLL: confirm that the project target framework is one of the supported frameworks listed on this page, and that the RID at publish time matches the deployment environment architecture.