Tutorials

Tutorials

Automating Microsoft Teams with Desktop Application Selectors

Not every workflow lives in a browser. GPAL.Application launches a desktop executable, then drives it with the same Selector and fluent action model used for the browser - here, opening Microsoft Teams, clicking into a team, and sending a chat message.

Complete Program

This is a trimmed version of the actual test program. It defines selectors for a Teams team in the sidebar, the chat input box, and the send button, then opens Teams and drives it through clicking the team, typing a message, and sending it - all in one chain.

using System;

using System.Diagnostics;

using GenerallyPositive;

using GenerallyPositive.Application;

GPAL.WithExceptionHandler(ExceptionEventHandler)

.WithInformationHandler(ExceptionEventHandler);

Selector teamSelector = (Selector)GPAL.Selector

.WithXPath("/Pane/Document/Group[3]/Group/Tree/ListItem[1]/TreeItem[4]/Hyperlink");

Selector chatInputSelector = (Selector)GPAL.Selector

.WithXPath("/Pane/Document/Group[7]/Document/Pane/Group/Edit[2]");

Selector sendButtonSelector = (Selector)GPAL.Selector

.WithXPath("/Pane/Document/Group[7]/Document/Pane/Group/ToolBar[2]/Button");

GPAL.Application

.Open(@"C:UsersmeAppDataLocalMicrosoftTeamscurrent eams.exe")

.WithSelector(teamSelector)

.LeftClick()

.WithSelector(chatInputSelector)

.FillInFrom("This is an automated chat message from GPAL")

.WithSelector(sendButtonSelector)

.LeftClick();

static void ExceptionEventHandler(object sender, EventArgs e)

{

Debug.WriteLine(((GPAL.GPALEventArgs)e).Message);

Debug.WriteLine(((GPAL.GPALEventArgs)e).ExceptionRaised?.Message);

}

Selectors Work the Same for Desktop UIs

These selectors use XPath against the UI Automation tree, not the DOM - Pane, Document, Group, Tree, ListItem, TreeItem are UI Automation element types Windows exposes for any desktop app. Aside from the XPath syntax, defining these selectors looks identical to defining selectors for a web page.

Selector teamSelector = (Selector)GPAL.Selector

.WithXPath("/Pane/Document/Group[3]/Group/Tree/ListItem[1]/TreeItem[4]/Hyperlink");

Selector chatInputSelector = (Selector)GPAL.Selector

.WithXPath("/Pane/Document/Group[7]/Document/Pane/Group/Edit[2]");

Selector sendButtonSelector = (Selector)GPAL.Selector

.WithXPath("/Pane/Document/Group[7]/Document/Pane/Group/ToolBar[2]/Button");

WARNING

These index-based XPaths (Group[3], TreeItem[4], and so on) depend on the exact layout of the Teams window at the time they were captured. A Teams UI update, a different window size, or extra items in the sidebar can shift those indexes and break the selector.

GPAL.Application.Open Launches and Returns a Driveable Object

GPAL.Application.Open takes the path to the executable and launches it, returning the same kind of fluent object the browser API returns. From there, WithSelector, LeftClick, and FillInFrom chain together exactly as they would for a browser - click into the team in the sidebar, then move on to the next selector.

GPAL.Application

.Open(@"C:UsersmeAppDataLocalMicrosoftTeamscurrent eams.exe")

.WithSelector(teamSelector)

.LeftClick()

Type and Send

FillInFrom types the message text into the chat input, then WithSelector switches the active target to the send button and LeftClick fires it. The whole interaction - launch, navigate the sidebar, type, and send - is one continuous chain.

.WithSelector(chatInputSelector)

.FillInFrom("This is an automated chat message from GPAL")

.WithSelector(sendButtonSelector)

.LeftClick();

Catching Errors Across the Whole Workflow

WithExceptionHandler and WithInformationHandler register a single callback that GPAL invokes for every exception or informational event raised anywhere in the workflow, not just for this one chain. Wiring this up before the chain runs means selector failures or click failures surface through your own logging instead of crashing silently.

GPAL.WithExceptionHandler(ExceptionEventHandler)

.WithInformationHandler(ExceptionEventHandler);

static void ExceptionEventHandler(object sender, EventArgs e)

{

Debug.WriteLine(((GPAL.GPALEventArgs)e).Message);

Debug.WriteLine(((GPAL.GPALEventArgs)e).ExceptionRaised?.Message);

}

TIP

See The Event System for how GPALEventArgs carries the message and optional exception for both exception and information events.

On this page

Tutorials
Automating Microsoft Teams with Desktop Application Selectors
  • Complete Program
  • Selectors Work the Same for Desktop UIs
  • GPAL.Application.Open Launches and Returns a Driveable Object
  • Type and Send
  • Catching Errors Across the Whole Workflow