Table of Contents

Class SapGuiClient

Namespace
SapGui.Wrapper
Assembly
SapGui.Wrapper.dll

Top-level entry point for SAP GUI automation.

Typical usage (C#):

using var sap = SapGuiClient.Attach();
var session = sap.Session;
session.StartTransaction("SE16");
session.TextField("wnd[0]/usr/ctxtDATABROWSE-TABLENAME").Text = "MARA";
session.PressEnter();
var status = session.Statusbar();
Console.WriteLine(status.Text);

Typical usage (VB.NET for UiPath Invoke Code activity):

Dim sap As SapGuiClient = SapGuiClient.Attach()
Dim session As GuiSession = sap.Session
session.StartTransaction("MM60")
session.TextField("wnd[0]/usr/txtS_WERKS-LOW").Text = "1000"
session.PressEnter()
public sealed class SapGuiClient : IDisposable
Inheritance
SapGuiClient
Implements
Inherited Members

Properties

Application

The underlying GuiApplication instance.

public GuiApplication Application { get; }

Property Value

GuiApplication

Session

The first available session. For multi-session scenarios use GetSession(int, int).

public GuiSession Session { get; }

Property Value

GuiSession

Methods

Attach(SapLogAction?, SapLogLevel, ILogger?)

Attaches to the currently running SAP GUI application. Requires SAP GUI to be open and scripting to be enabled.

public static SapGuiClient Attach(SapLogAction? logAction = null, SapLogLevel minLevel = SapLogLevel.Debug, ILogger? logger = null)

Parameters

logAction SapLogAction

Optional delegate that receives log messages. Use (level, msg, ex) => Log($"[SAP/{level}] {msg}") in UiPath, or map to any logging framework. Leave null (default) for silent operation.

minLevel SapLogLevel

Minimum severity forwarded to logAction. Defaults to Debug (all messages). Ignored when logger is used — ILogger uses its own configured minimum level.

logger ILogger

Optional ILogger (ASP.NET Core DI, Serilog, NLog via MEL adapter). When both logAction and logger are supplied, logAction takes precedence.

Returns

SapGuiClient

Exceptions

SapGuiNotFoundException

SAP GUI is not running or scripting is disabled.

Dispose()

Releases the managed wrapper and the underlying COM reference to the GuiApplication object.

Does NOT close SAP GUI or log off any sessions. Sessions obtained before Dispose remain valid COM objects inside SAP GUI and can continue to be used. If you also want to release a GuiSession reference, call Dispose() on it explicitly (or use a using block).

Safe to call multiple times. 

public void Dispose()

EnsureHealthy()

Runs HealthCheck() and throws InvalidOperationException when any check fails. Prefer this in workflows that require a fully healthy SAP environment at startup and want a single fail-fast call.

// Fail fast at the top of the workflow
SapGuiClient.EnsureHealthy();

using var sap = SapGuiClient.Attach();
sap.Session.StartTransaction("SE16");
public static void EnsureHealthy()

Exceptions

InvalidOperationException

One or more health checks failed. The message contains all FAIL: findings.

GetConnections()

All active connections.

public IReadOnlyList<GuiConnection> GetConnections()

Returns

IReadOnlyList<GuiConnection>

GetSession(int, int)

Gets a session by connection index and session index (both 0-based).

public GuiSession GetSession(int connectionIndex = 0, int sessionIndex = 0)

Parameters

connectionIndex int
sessionIndex int

Returns

GuiSession

HealthCheck()

Runs a set of pre-flight checks and returns a structured HealthCheckResult. Never throws.

Checks performed (in order):

  1. SAP GUI process (saplogon.exe) is running.
  2. Scripting API is accessible via the Windows ROT.
  3. At least one active server connection exists.
  4. At least one active session exists.
  5. Session info (user, system, client) is readable — confirms the session is fully logged in.

Each finding is prefixed with OK:, WARN:, or FAIL:.

var result = SapGuiClient.HealthCheck();
if (!result.IsHealthy)
    throw new InvalidOperationException(result.FailureSummary);

foreach (var line in result.Findings)
    Console.WriteLine(line);
public static HealthCheckResult HealthCheck()

Returns

HealthCheckResult

LaunchWithSso(string, bool, int, SapLogAction?, SapLogLevel, ILogger?)

Ensures SAP Logon is running, opens a connection to systemDescription via SSO (no credential dialog), waits until a usable session is available, and returns the client.

This method is designed for Single Sign-On (SNC / Kerberos / etc.) environments. The target system entry must be configured in SAP Logon Pad and the system must allow SSO so that the connection completes without prompting for credentials.

If a session to the same system is already open, SAP Logon shows a "License information for multiple logons" dialog that blocks the new connection from completing. Use reuseExistingSession to control this behaviour:

  • true — skip opening a new connection and return a client wrapping the first existing session for that system.
  • false (default) — throw InvalidOperationException if an existing session for that system is detected, so the caller can decide what to do (attach, close, or abort). 
// Reuse any already-open session for the system:
using var sap = SapGuiClient.LaunchWithSso("PRD - Production", reuseExistingSession: true);
var session = sap.Session;
session.DismissPostLoginPopups();
session.StartTransaction("MM60");
public static SapGuiClient LaunchWithSso(string systemDescription, bool reuseExistingSession = false, int connectionTimeoutMs = 30000, SapLogAction? logAction = null, SapLogLevel minLevel = SapLogLevel.Debug, ILogger? logger = null)

Parameters

systemDescription string

System entry name exactly as it appears in SAP Logon Pad, e.g. "PRD - Production".

reuseExistingSession bool

When true, an existing open session for systemDescription is reused instead of opening a new connection. When false (default), an existing session causes an InvalidOperationException to be thrown.

connectionTimeoutMs int

Total time (ms) to wait for SAP Logon to start and a ready session to appear. Defaults to 30 seconds.

logAction SapLogAction

Optional delegate for log messages (see Attach(SapLogAction?, SapLogLevel, ILogger?)).

minLevel SapLogLevel

Minimum severity forwarded to logAction. Default: Debug (all messages).

logger ILogger

Optional ILogger. Ignored when logAction is also supplied.

Returns

SapGuiClient

Exceptions

SapGuiNotFoundException

saplogon.exe could not be started, or SAP GUI scripting is disabled.

InvalidOperationException

An existing session for systemDescription is already open and reuseExistingSession is false, or the connection could not be opened.

TimeoutException

SAP Logon started but no ready session appeared within connectionTimeoutMs ms.

Edit this page