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 via the SDK's vcpkg registry. They share the same RUM application ID and data reporting method, but package versions, upgrade cadence, and changelogs are independent of each other.

Prerequisites¶

1. In RUM, create a Custom application and obtain its application ID.
2. Prepare one of the following data reporting methods:
3. Public DataWay: reporting URL and Client Token;
4. Local deployment (DataKit): a DataKit address accessible to the application process.
5. Confirm that the application runs on Windows 10 or later.

Integration Steps¶

1. Choose the NuGet or vcpkg package based on your application's tech stack.
2. Install dependencies and fill in the RUM application and reporting configuration.
3. Initialize the SDK and enable automatic instrumentation, Log, Trace, and Session Replay as needed.
4. Run the application and confirm successful data reporting in the console.

Select a Package¶

.NET / C#: Use 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 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++: Use vcpkg¶

Configure the SDK Registry¶

Create or update vcpkg-configuration.json in the project root. Replace the default registry baseline with a Microsoft vcpkg commit verified by your project; <latest-sdk-vcpkg-registry-commit> denotes the latest commit of the SDK registry. When integrating, replace the placeholders with actual commits and pin them to keep builds reproducible.

{
  "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 the Dependency and Install¶

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

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

Then install in manifest mode:

vcpkg install

CMake Linking¶

When configuring CMake, pass the vcpkg toolchain file, 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, refer to the public guance_sdk.h.

Minimal Initialization Example¶

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

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¶

• .NET/C# can optionally automatically collect WPF, WinForms, WinUI 3, HttpClient, unhandled exceptions, and UI thread blocking; call GuanceSdk.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 requests that can have headers injected.
• The SDK uses a privacy-protective configuration by default. Session Replay is disabled by default and must be explicitly enabled; it is still an experimental feature and is not covered by stable compatibility guarantees.

For configuration of the UI, WebView2, Electron, and each signal, see Desktop UI Frameworks, WebView2 Monitoring, Electron Monitoring, RUM Configuration, Log Configuration, and Trace Configuration.

Verify the Integration¶

1. Start the application and open at least one View.
2. Perform one click action and make one 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, confirm that log data and Trace Header/RUM Resource correlation work 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 basic 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 should not be considered the same release:

Stable releases such as 1.2.3, as well as prerelease versions in the form 1.2.3-alpha.1 and 1.2.3-beta.1, are supported. When upgrading, read the changelog for the corresponding package and update the NuGet version or vcpkg registry baseline; the two release streams are shown in separate sections in the Changelog.

FAQ¶

• Package not found in Visual Studio's NuGet UI: enable "Include prerelease," or use the dotnet add package command provided in this document.
• vcpkg install cannot find the port: confirm 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's target framework is one of the supported frameworks listed on this page, and that the RID used during publishing matches the architecture of the deployment environment.