데스크톱 UI 프레임워크¶

Windows SDK는 .NET UI 프레임워크와 Native HWND 애플리케이션을 모두 지원합니다. .NET은 프레임워크 어댑터를 제공하고, Native 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 등의 유형을 생성합니다. Native 애플리케이션은 동일한 안정적인 유형 이름을 사용하고, 동일한 상호작용에 대해 자동 및 수동 보고를 동시에 수행하지 않아야 합니다.

다중 창¶

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

Native UI 지연 및 크래시¶

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

SDK 종료¶

.NET / C#Native C/C++

WPF 및 WinForms는 동기 종료 경계에서 ShutdownAsync()를 기다릴 수 있습니다. WinUI 3는 마지막 Window가 닫힐 때 종료가 완료될 때까지 기다려야 합니다.

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

guance_sdk_shutdown(rum);
rum = nullptr;