데스크톱 UI 프레임워크¶

Windows SDK는 .NET UI 프레임워크와 네이티브 HWND 애플리케이션을 모두 다룹니다. .NET은 프레임워크 어댑터를 제공하고, 네이티브 C/C++은 창, 명령, 메시지 수명 주기를 통해 명시적으로 C ABI를 호출합니다.

기능 비교¶

기능	WPF	WinForms	WinUI 3	Native Win32/HWND
Window View	자동	자동	명시적 연결 후 자동	명시적으로 View C ABI 호출
컨트롤 Action	자동	자동	명시적 연결 후 자동	명령 또는 메시지에서 명시적으로 호출
동적 컨트롤	Loaded 이벤트	Idle 스캔	연결된 창 내에서 발견	애플리케이션이 수명 주기 관리
네트워크 Resource	`HttpClient`	`HttpClient`	`HttpClient`	WinHTTP 어댑터 또는 수동 C ABI
Error	처리되지 않은 예외	처리되지 않은 예외	처리되지 않은 예외	충돌 복구 또는 수동 C ABI
Long Task	UI 스레드 탐지	UI 스레드 탐지	UI 스레드 탐지	`HWND` Watchdog

프레임워크 통합¶

WPFWinFormsWinUI 3Native C/C++

App.OnStartup()에서 초기화하고 자동 수집을 활성화합니다:

protected override void OnStartup(StartupEventArgs e)
{
    GuanceSdk.Init(config);
    GuanceSdk.EnableAutomaticInstrumentation();
    base.OnStartup(e);
}

protected override void OnExit(ExitEventArgs e)
{
    GuanceSdk.ShutdownAsync().GetAwaiter().GetResult();
    base.OnExit(e);
}

첫 번째 Form 생성 전에 초기화하고, 메시지 루프 종료 후 종료합니다:

ApplicationConfiguration.Initialize();
GuanceSdk.Init(config);
GuanceSdk.EnableAutomaticInstrumentation();

Application.Run(new MainForm());
GuanceSdk.ShutdownAsync().GetAwaiter().GetResult();

WinUI 3의 각 Window는 명시적으로 연결해야 합니다:

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    window = new MainWindow().UseGuanceRum("MainWindow");
    window.Activate();
}

GuanceSdk.AttachWinUIWindow(window, "MainWindow")를 호출할 수도 있습니다. Window 생성 후 Activate() 전에 연결을 완료해야 합니다.

최상위 창의 표시 수명 주기 동안 View를 유지합니다:

guance_rum_start_view(rum, "MainWindow");

// 창 메시지 루프를 실행합니다.

guance_rum_stop_view(rum);

명령 또는 창 메시지 처리 경계에서 Action을 유지합니다:

const char* action_id =
    guance_rum_start_action(rum, "SaveButton", "click");

save_settings();

guance_rum_stop_action(rum, action_id);

MFC 등 안정적인 창과 상호 작용 수명 주기를 제공하는 Windows 데스크톱 프레임워크는 동일한 C ABI를 사용할 수 있지만, 현재 프레임워크 수준의 자동 검색 어댑터는 없습니다.

View 명명¶

안정적인 비즈니스 이름을 우선 사용하고, 개체 주소, 임의 값 또는 사용자 데이터가 포함된 창 제목을 사용하지 마세요.

출처	권장 이름
WPF	Window 유형 이름 또는 안정적인 Title
WinForms	Form 유형 이름, Name 또는 안정적인 Text
WinUI 3	`UseGuanceRum()`에 전달된 비즈니스 이름
Native	`guance_rum_start_view()`에 전달된 비즈니스 이름

Action 유형¶

.NET 자동 수집은 입력 소스에 따라 click, key_press, input, select, toggle 등의 유형을 생성합니다. 네이티브 애플리케이션은 동일한 안정적인 유형 이름을 사용해야 하며, 동일한 상호 작용에 대해 자동과 수동 보고를 동시에 수행하지 않아야 합니다.

다중 창¶

WPF와 WinForms는 현재 표시되는 창을 추적합니다.
WinUI 3는 Window를 생성할 때마다 연결해야 합니다.
네이티브 애플리케이션은 활성 최상위 창이 전환될 때 이전 View를 종료하고 새 View를 시작합니다.
새 View가 시작되면 현재 활성 View가 종료되므로 여러 View를 병렬로 유지하지 마세요.

네이티브 UI 지연 및 충돌¶

네이티브 애플리케이션은 guance_sdk_native_monitoring_config를 통해 기본 창 HWND를 연결하고 UI Watchdog 및 다음 시작 시 충돌 복구를 활성화할 수 있습니다. 구성 필드와 기본 임계값은 RUM 구성을 참조하세요.

SDK 종료¶

.NET / C#Native C/C++

WPF 및 WinForms는 동기 종료 경계에서 ShutdownAsync()를 대기할 수 있습니다. WinUI 3는 마지막 창 닫기 흐름에서 종료가 완료될 때까지 대기해야 합니다.

메시지 루프가 종료되고 비즈니스 스레드가 더 이상 Handle에 액세스하지 않을 때 호출합니다:

guance_sdk_shutdown(rum);
rum = nullptr;