Optimization for Microsoft Teams 编辑

Citrix delivers optimization for desktop-based Microsoft Teams using Citrix Virtual Apps and Desktops and Citrix Workspace app. By default, we bundle all the necessary components into the Citrix Workspace app and the Virtual Delivery Agent (VDA).

Our optimization for Microsoft Teams includes VDA-side HDX services and an API to interface with the Microsoft Teams hosted app to receive commands. These components open a control virtual channel (CTXMTOP) to the Citrix Workspace app-side media engine. The endpoint decodes and provides the multimedia locally, moving the Citrix Workspace app window back into the hosted Microsoft Teams app.

Authentication and signaling occur natively on the Microsoft Teams-hosted app, just like the other Microsoft Teams services (for example chat or collaboration). Audio/video redirection doesn’t affect them.

The CTXMTOP is a command and control virtual channel. That means that media isn’t exchanged between the Citrix Workspace app and the VDA.

Only client-fetch/client-render is available.

This video demo gives you an idea of how Microsoft Teams works in a Citrix virtual environment.

Microsoft Teams installation

Citrix and Microsoft recommend the latest available version of Microsoft Teams and to keep it up to date. Microsoft Teams desktop app versions with release dates that are more than 90 days older than the current version’s release date aren’t supported. Unsupported Microsoft Teams desktop app versions show a blocking page to users and request to update the app.

For information on the latest available versions, see Update history for Teams App (Desktop and Mac).

We recommend that you follow the Microsoft Teams machine-wide installation guidelines. Also, avoid using the .exe installer that installs Microsoft Teams in AppData. Instead, install in C:\Program Files (x86)\Microsoft\Teams by using the ALLUSER=1 flag from the command line.

msiexec /i <path_to_msi> /l*v <install_logfile_name> ALLUSER=1 ALLUSERS=1

This example also uses the ALLUSERS=1 parameter. When you set this parameter, the Microsoft Teams Machine-Wide Installer appears in Programs and Features in the Control Panel. Also, in Apps & features in Windows Settings for all users of the computer. All users can then uninstall Microsoft Teams if they have administrator credentials.

It’s important to understand the difference between ALLUSERS=1 and ALLUSER=1. You can use the ALLUSERS=1 parameter in non-VDI and VDI environments. Use the ALLUSER=1 parameter only in VDI environments to specify a per-machine installation.

In ALLUSER=1 mode, the Microsoft Teams application doesn’t auto-update whenever there’s a new version. We recommend this mode for non-persistent environments, such as hosted shared apps or desktops out of a Windows Server or Windows 10 random/pooled catalogs. For more information, see Install Microsoft Teams using MSI (VDI Installation section).

Suppose you have Windows 10 dedicated persistent VDI environments. You want the Microsoft Teams application to auto-update and prefer Microsoft Teams to install per-user under Appdata/Local. In this case, use the .exe installer or the MSI without ALLUSER=1.

Note:

We recommend installing the VDA before installing Microsoft Teams in the golden image. This installation order is needed for the ALLUSER=1 flag to take effect. If you installed Microsoft Teams in the virtual machine before installing the VDA, uninstall and reinstall Microsoft Teams.

For Remote PC Access

We recommend that you install Microsoft Teams version 1.4.00.22472 or later after installing the VDA. Otherwise, you need to sign out and sign in again for Microsoft Teams to detect the VDA as expected. Version 1.4.00.22472 and later includes augmented logic run at Microsoft Teams launch time and sign in time for VDA detection. These versions also include active session type identification (HDX, RDP or locally connected to the client machine). If you’re locally connected, previous versions of Microsoft Teams might fail to detect and disable certain features or UI elements. For example, Breakout Rooms, pop out windows for meetings and chat, or meeting reactions.

Important:

When you roam from a local session to an HDX session and if Microsoft Teams is kept open and running on the background, you must exit and relaunch Microsoft Teams to optimize with HDX correctly. Conversely, if you use Microsoft Teams remotely via an optimized HDX session, disconnect the HDX session and reconnect to the same Windows session locally at the device. When working from the office, you must relaunch Microsoft Teams so it can correctly detect the remote PC state (HDX or local). Because Microsoft Teams can only assess VDI mode at app launch time, and not while it is already running on the background. Without a restart, Microsoft Teams might fail to load features like pop out Windows, Breakout Rooms, or meeting reactions.

For App Layering

If using Citrix App Layering to manage VDA and Microsoft Teams installations in different layers, you must create a new registry key on Windows VDAs before installing Microsoft Teams with the ALLUSER=1 flag from the command line. For more information, see the Optimization for Microsoft Teams with Citrix App Layering section under Multimedia.

Profile Management recommendations

We recommend using the machine-wide installer for Windows Server and Pooled VDI Windows 10 environments.

When the ALLUSER=1 flag is passed to the MSI from the command line (the machine-wide installer), the Microsoft Teams app installs under C:\Program Files (x86) (~300 MB). The app uses AppData\Local\Microsoft\TeamsMeetingAddin for logs and AppData\Roaming\Microsoft\Teams (~600–700 MB) for user specific configurations, caching of elements in the user interface, and so forth.

Important:

If you don’t pass the ALLUSER=1 flag, the MSI places the Teams.exe installer and setup.json under C:\Program Files (x86)\Teams Installer. A registry key (TeamsMachineInstaller) is added under: HKEY_LOCAL_MACHINE \SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Run

A subsequent user logon triggers the final installation in AppData instead.

Machine-wide installer

The following is an example of folders, desktop shortcuts, and registries created by installing Microsoft Teams machine-wide installer on a Windows Server 2016 64-bit VM:

Folder:

• C:\Program Files (x86)\Microsoft\Teams
• C:\Users\<username>\AppData\Roaming\Microsoft\Teams

Desktop Shortcut:

C:\Program Files (x86)\Microsoft\Teams\current\Teams.exe

Registry:

• HKEY_LOCAL_MACHINE \SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Run
• HKEY_LOCAL_MACHINE \SOFTWARE\Microsoft\Windows\CurrentVersion\Run
• HKEY_CURRENT_USER \SOFTWARE\Microsoft\Windows\CurrentVersion\Run
• Name: Teams
• Type: REG_SZ
• Value: C:\Program Files (x86)\Microsoft\Teams\current\Teams.exe

Note:

The registry location varies based on the underlying Operating Systems and bitness.

Recommendations

• We recommend disabling auto-start by deleting the Microsoft Teams registry keys. Doing so prevents many logons that occur at the same time (for example, at the beginning of your work day) from spiking up the VM’s CPU.
• If the virtual desktop does not have a GPU/vGPU, we recommend setting Disable GPU hardware acceleration in the Microsoft Teams Settings to improve performance. This setting ("disableGpu":true) is stored in %Appdata%\Microsoft\Teams in desktop-config.json. You can use a logon script to edit that file and set the value to true.
• If using Citrix Workspace Environment Management (WEM), enable CPU Spikes Protection to manage processor consumption for Microsoft Teams.

Per-user installer

When using the .exe installer, the installation process differs. All the files are placed in AppData.

Folder:

• C:\Users\<username>\AppData\Local\Microsoft\Teams
• C:\Users\<username>\AppData\Local\Microsoft\TeamsPresenceAddin
• C:\Users\<username>\AppData\Local\Microsoft\TeamsMeetingAddin
• C:\Users\<username>\AppData\Local\SquirrelTemp
• C:\Users\<username>\AppData\Roaming\Microsoft\Teams

Desktop shortcut:

C:\Users\<username>\AppData\Local\Microsoft\Teams\Update.exe --processStart "Teams.exe"

Registry:

HKEY_CURRENT_USER \SOFTWARE\Microsoft\Windows\CurrentVersion\Run

Best Practices

The best practice recommendations are based on the use-case scenarios. Using Microsoft Teams with a non-persistent setup requires a profile caching manager for efficient Microsoft Teams runtime data synchronization. With a profile caching manager, the appropriate user-specific information is cached during the user session. For example, the user-specific information includes, user data, profile, and settings. Synchronize the data in these two folders:

• C:\Users\<username>\AppData\Local\Microsoft\IdentityCache
• C:\Users\<username>\AppData\Roaming\Microsoft\Teams

Microsoft Teams cached content exclusion list for non-persistent setup

Exclude the files and directories from the Microsoft Teams caching folder as described in the Microsoft documentation. This action helps you to reduce the user caching size to further optimize your non-persistent setup.

Use case: single-session scenario

In this scenario, the end user uses Microsoft Teams in one location at a time. They don’t need to run Microsoft Teams in two Windows sessions at the same time. In a common virtual desktop deployment, each user is assigned to one desktop, and Microsoft Teams is deployed in the virtual desktop as one application. We recommend enabling the Citrix Profile container and redirecting the per-user directories listed in Per-user installer into the container.

1. Deploy the Microsoft Teams machine-wide installer (ALLUSER=1) in the golden image.
2. Enable Citrix Profile Management and set up the user profile store with the proper permissions.

3. Enable the following Profile Management policy setting: File system > Synchronization > Profile container – List of folders to be contained in profile disk.

   

   List all the per-user directories into this configuration. You can also configure these settings using the Citrix Workspace Environment Management (WEM) service.

4. Apply the settings to the correct delivery group.
5. Log in to validate the deployment.

System requirements

Minimum recommended version - Delivery Controller (DDCs) 1906.2

If you’re using an earlier version, see Enable optimization of Microsoft Teams:

Supported operating systems:

• Windows Server 2022, 2019, 2016, 2012R2 Standard and data center Editions, and with the Server Core option

Minimum version - Virtual Delivery Agents (VDAs) 1906.2

Supported operating systems:

• Windows 11.
• Windows 10 64-bit, versions 1607 and later. VM hosted apps are supported in Citrix Workspace app for Windows 2109.1 and later.
• Windows Server 2022, 2019, 2016, and 2012 R2 (Standard and data center Editions).

Requirements:

• BCR_x64.msi - the MSI that includes the Microsoft Teams optimization code and starts automatically from the GUI. If you’re using the command line interface for the VDA installation, don’t exclude it.

Recommended version – Citrix Workspace app for Windows latest CR and Minimum version - Citrix Workspace app 1907 for Windows

• Windows 11.
• Windows 10 (32-bit and 64-bit editions, including Embedded editions) (Support for Windows 7 stopped at Version 2006) (Support for Windows 8.1 stopped at version 2204.1).
• Windows 10 IoT Enterprise 2016 LTSB (v1607) and 2019 LTSC (v1809).
• Processor (CPU) architectures supported: x86 and x64 (ARM isn’t supported).
• Endpoint requirement: Approximately 2.2–2.4 GHz dual core CPU that can support 720p HD resolution during a peer-to-peer video conference call.
• Dual or quad-core CPUs with lower base speeds (~1.5 GHz) equipped with Intel Turbo Boost or AMD Turbo Core that can boost up to at least 2.4 GHz.
• HP Thin Clients verified: t630/t640, t730/t740, mt44/mt45.
• Dell Thin Clients verified: 5070, 5470 Mobile TC and AIO.
• 10ZiG Thin Clients verified: 4510 and 5810q.
• For a complete list of verified endpoints, see Thin Clients.
• Citrix Workspace app requires at least 600 MB free disk space and 1 GB RAM.
• Microsoft .NET Framework minimum requirement is version 4.8. Citrix Workspace app automatically downloads and installs .NET Framework if it’s not present in the system.

Administrators can enable/disable Microsoft Teams starting in optimized mode by changing the Teams Optimization policy. Users starting in optimized mode in Citrix Workspace app can’t disable Microsoft Teams.

Minimum version - Citrix Workspace app 2006 for Linux

For more information, see Optimization for Microsoft Teams in Citrix Workspace app for Linux documentation.

Software:

• GStreamer 1.0 or later or Cairo 2
• libc++-9.0 or later
• libgdk 3.22 or later
• OpenSSL 1.1.1d
• x64 Linux distribution

Hardware:

• Minimum 1.8 GHz dual-core CPU that can support 720p HD resolution during a peer-to-peer video conference call
• Dual or quad-core CPU with a base speed of 1.8 GHz and a high Intel Turbo Boost speed of at least 2.9 GHz

For a complete list of verified endpoints, see Thin Clients.

For more information, see Prerequisites to install Citrix Workspace app.

You can disable Microsoft Teams optimization updating the value of the VDWEBRTC field to Off in the /opt/Citrix/ICAClient/config/module.ini file. The default is VDWEBRTC=On. After the update is complete, restart the Session. (Root permission is required).

Minimum version - Citrix Workspace app 2012 for Mac

Supported operating systems:

• macOS Catalina (10.15).
• macOS Big Sur 11.0.1 and later.
• macOS Monterey.

Features supported:

• Audio
• Video
• Screen sharing optimization (incoming and outgoing)

Note:

Citrix Viewer app requires access to macOS Security and Privacy preferences for screen sharing to work. Users configure this preference in Apple menu > System preferences > Security & Privacy > Privacy tab > Screen recording and select Citrix Viewer.

Microsoft Teams optimization works by default with Citrix Workspace app 2012 and later and macOS 10.15.

If you want to disable Microsoft Teams optimization, run this command in a terminal and restart the Citrix Workspace app:

defaults write com.citrix.receiver.nomas mtopEnabled -bool NO

Minimum version - Latest version of Citrix Workspace app for Chrome OS running on the latest version of Chrome OS

Hardware:

• Processors that perform at par or better than Intel i3, quad core 2.4 GHz.

Features supported:

• Audio
• Video
• Screen sharing optimization (incoming and outgoing) - disabled by default. See these settings for instructions on how to turn it on.

Single Server Scalability

This section provides recommendations and guidance to estimate how many users or virtual machines (VMs) can be supported on a single physical host. This is commonly referred to as Citrix Virtual Apps and Desktops Single Server Scalability (SSS). In the context of Citrix Virtual Apps (CVA) or session virtualization, it is also commonly known as user density. The idea is to find out how many users or VMs can be ran on a single piece of hardware running a major hypervisor.

Note:

This section includes guidance to estimate SSS. Note that the guidance is high level and might not necessarily be specific to your unique situation or environment. The only way to truly understand Citrix Virtual Apps and Desktops SSS is to use a scalability or load testing tool such as Login VSI. Citrix recommends using this guidance and these simple rules to quickly estimate SSS only. However, Citrix recommends using Login VSI or the load testing tool of your choice to validate results, especially before purchasing hardware or making any financial decisions.

Hardware (system under test)

• Dell PowerEdge R740
• Intel Xeon (Gold) 6126 @ 2.60 GHz (max Turbo 3.70 GHz), 12 cores per socket, dual socket with Hyperthreading enabled
• 382 GB of RAM
• Local SSD RAID 0 storage (11 disk) 6 TB

Software

A single virtual machine (40 logical processors) with Windows 2019 (TSVDA) running Citrix Virtual Apps and Desktops 2106 VMware ESXi 6.7

Terminology

• Knowledge worker workload: Includes Acrobat Reader, Freemind/Java, Photo viewer, Edge, and MS Office apps such as Excel, Outlook, PowerPoint, and Word.
• Baseline: Server Scalability tests run with knowledge worker workload (without Microsoft Teams).
• Microsoft Teams Workload: Knowledge worker typical workload + Microsoft Teams.

How Microsoft Teams is stress-tested

• Microsoft Teams is optimized with HDX. Hence, all the multimedia processing is offloaded to the endpoint or client and is not part of the measurement.
• All Microsoft Teams processes stopped or killed, before workload starts.
• Open Microsoft Teams (Cold start).
• Measure the time taken by Microsoft Teams to load and grab the focus of Microsoft Teams primary window.
• Switch to chat window using keyboard shortcuts.
• Switch to calendar window using keyboard shortcuts.
• Send the chat message to a specific user using keyboard shortcuts.
• Switch to Microsoft Teams window using keyboard shortcuts.

Results

• 40% scalability impact with Microsoft Teams Workload (81 users), when compared to Baseline (137 users).
• Increasing the server capacity by ~40% (in CPU) restores the number of users as with Baseline workload.
• 20% extra memory required with Microsoft Teams Workload, when compared to Baseline.
• Increase per user storage size by 512-1024 MB.
• ~50% increase in IOPS write, ~100% increase in IOPS reads. Microsoft Teams can have a significant impact in environment with slower storage.

Feature matrix and version support

1. Disabled by default, requires Admin to enable.
2. CD Viewer in full screen mode only. SHIFT+F2 not supported.
3. Negotiate/Kerberos, NTLM, Basic, and Digest. Pac files are also supported.
4. Anonymous only.
5. Only on Windows 10, Windows IoT Client OS.
6. Features currently unavailable in Microsoft Teams. For information on ETA, go to www.microsoft.com and search for Microsoft 365 roadmap.
7. If VDA is 2112 or higher, Live Captions will only work if Citrix Workspace app version is 2203.1 for MAC and 2203 Linux or 2112 for Windows. This is because Live Captions behave differently if Microsoft Teams is in Single Window UI mode or MultiWindow mode.

Note:

All features listed in Citrix Workspace app for Windows 1912 CU6 (or later) are applicable to Citrix Workspace app for Windows 2203.1 LTSR CU1.

Enable optimization of Microsoft Teams

To enable optimization for Microsoft Teams, use the Manage console policy described in the Microsoft Teams redirection policy. This policy is ON by default. In addition to this policy being enabled, HDX checks to verify that the version of the Citrix Workspace app is at least the minimum required version. If you enabled the policy and the Citrix Workspace app version is supported, the HKEY_CURRENT_USER\Software\Citrix\HDXMediaStream\MSTeamsRedirSupport registry key is set to 1 automatically on the VDA. Microsoft Teams reads the key to load in VDI mode.

Note:

If you’re using version 1906.2 or later VDAs or with older controller versions (for example, version 7.15) that don’t have the policy available in the Manage console (Studio), your VDA can still be optimized. HDX optimization for Microsoft Teams is enabled by default in the VDA.

If you click About > Version, the Citrix HDX Optimized legend displays:

If you see Citrix HDX Not Connected, the Citrix API is loaded in Microsoft Teams. Loading the API is the first step toward redirection. But there’s an error in later parts of the stack. The error is most likely in the VDA services or the Citrix Workspace app.

If you don’t see any legend, Microsoft Teams failed to load the Citrix API. Exit Microsoft Teams by right-clicking the notification area icon and restarting. Make sure that the Manage console policy isn’t set to Prohibited and that the Citrix Workspace app version is supported.

Important: session reconnects

• You might require to relaunch Microsoft Teams to get an HDX optimized session when your connectivity changes. For example, if you are roaming from an unsupported endpoint (Workspace app for iOS, Android, or old versions of Windows/Linux/Mac) to a supported one (Workspace app for Windows/Linux/Mac/ChromeOS/HTML5), or the opposite way.
• A Microsoft Teams relaunch is also required if you have installed the app using the Microsoft Teams .exe installer in the VDA. The .exe installer is recommended for persistent VDI deployments. In such cases, Microsoft Teams can auto-update while the HDX session is in the disconnected state. So, users reconnecting to an HDX session finds that the Microsoft Teams is not running optimized.
• When you roam from a local session to an HDX session, you must relaunch Microsoft Teams to optimize with HDX. This action is required in a Remote PC Access scenario.

Network requirements

Microsoft Teams relies on Media Processor servers in Microsoft 365 for meetings or multiparty calls. Also, Microsoft Teams relies on Microsoft 365 Transport Relays for these scenarios:

• Two peers in a point-to-point call do not have direct connectivity
• A participant does not have direct connectivity to the media processor.

So the network health between the peer and the Microsoft 365 cloud determines the performance of the call. Please refer to Microsoft 365 network connectivity principles for detailed guidelines around network planning.

We recommend evaluating your environment to identify any risks and requirements that can influence your overall cloud voice and video deployment. Use the Skype for Business Network Assessment Tool to test if your network is ready for Microsoft Teams. For support information, see Support.

Summary of key network recommendations for Real Time Protocol (RTP) traffic

• Connect to the Microsoft 365 network as directly as possible from the branch office.
• Plan for and provide sufficient bandwidth at the branch office.
• Check each branch office for network connectivity and quality.
• If you must use any of the following at the branch office, make sure that RTP/UDP traffic (handled by HdxRtcEngine.exe in Citrix workspace app) is unhindered.
  • Bypass proxy servers
  • Network SSL intercept
  • Deep packet inspection devices
  • VPN hairpins (use split tunneling if possible)

Important: VPN Split tunnel configuration

HdxRtcEngine.exe traffic has to be diverted from the VPN tunnel and allowed to use the user’s local Internet connection to connect directly to the service. The manner in which this is accomplished will vary depending on the VPN product and machine platform used but most VPN solutions will allow some simple configuration of policy to apply this logic. For more information on VPN platform-specific split tunnel guidance, see this Microsoft article.

The WebRTC media engine in the Workspace app (HdxRtcEngine.exe) uses the Secure Real-time Transport Protocol (SRTP) for multimedia streams that are offloaded to the client. SRTP provides confidentiality and authentication to RTP. For this feature, symmetric keys (negotiated with DTLS) are used to encrypt media and control messages using the AES encryption cipher.

The following metrics are recommended for a positive user experience:

For more information, see Prepare your organization’s network for Microsoft Teams.

For bandwidth requirements, optimization for Microsoft Teams can use a wide variety of codecs for audio (OPUS/G.722/PCM G711) and video (H264).

The peers negotiate these codecs during the call establishment process using the Session Description Protocol (SDP) Offer/Answer. Citrix minimum recommendations per user are:

* Opus supports constant and variable bitrate encoding from 6 kbps up to 510 kbps.

Opus and H264 are the preferred codecs for peer-to-peer and conference calls.

Important:

About performance, encoding is more expensive than decoding for CPU use at the client machine. You can hardcode the maximum encoding resolution in the Citrix Workspace app for Linux and Windows. See Encoder performance estimator and Optimization for Microsoft Teams.

Proxy servers

Depending on the location of the proxy, consider the following:

• Proxy configuration on the VDA:

  If you configure an explicit proxy server in the VDA and route connections to localhost through a proxy, redirection fails. To configure the proxy correctly, you must select the Bypass proxy servers for local address setting in Internet Options > Connections > LAN Settings > Proxy Servers and bypass 127.0.0.1:9002.

  If you use a PAC file, your VDA proxy configuration script from the PAC file must return DIRECT for wss://127.0.0.1:9002. If not, optimization fails. To make sure that the script returns DIRECT, use shExpMatch(url, "wss://127.0.0.1:9002/*").

• Proxy configuration on Citrix Workspace app:

  If the branch office is configured to access the internet through a proxy, these versions support proxy servers:

  • Citrix Workspace app for Windows version 2012 (Negotiate/Kerberos, NTLM, Basic, and Digest. Pac files are also supported)
  • Citrix Workspace app for Windows version 1912 CU5 (Negotiate/Kerberos, NTLM, Basic, and Digest. Pac files are also supported)
  • Citrix Workspace app for Linux version 2101 (anonymous authentication)
  • Citrix Workspace app for Mac version 2104 (anonymous authentication)

Client devices with earlier versions of Citrix Workspace app can’t read proxy configurations. These devices send traffic directly to Microsoft 365 TURN servers.

Important:

• Verify that the client device can connect to the DNS server to do DNS resolutions. A client device must be able to resolve the following Microsoft Teams Relay server’s FQDNs:
  • worldaz.relay.teams.microsoft.com
  • inaz.relay.teams.microsoft.com
  • uaeaz.relay.teams.microsoft.com
  • euaz.relay.teams.microsoft.com
  • usaz.relay.teams.microsoft.com
  • turn.dod.teams.microsoft.us
  • turn.gov.teams.microsoft.us

If DNS requests are unsuccessful, P2P calls with outside users and conference calls media establishment fails.

• The location of the conference server is selected based on the first participant’s virtual desktop location (and not the client).

Call establishment and media flow paths

When possible, the HDX WebRTC media engine in the Citrix Workspace app (HdxRtcEngine.exe) tries to establish a direct network Secure Real-time Transport Protocol (SRTP) connection over User Datagram Protocol (UDP) in a peer-to-peer call. If the UDP high ports are blocked, the media engine falls back to TCP/TLS 443.

The HDX media engine supports ICE, Session Traversal Utilities for NAT (STUN), and Traversal Using Relays around NAT (TURN) for candidate discovery and establishing connection. This support means that the endpoint must be able to perform DNS resolutions.

Consider a scenario where there is no direct path between the two peers or between a peer and a conference server and you are joining a multi-party call or meeting. The HdxRtcEngine.exe uses a Microsoft Teams transport relay server in Microsoft 365 to reach the other peer or the media processor, where meetings are hosted. Your client machine must have access to three Microsoft 365 subnet IP address ranges and four UDP ports (or TCP/TLS 443 as fallback if UDP is blocked). For more information, see the Architecture diagram in the Call setup and Office 365 URLs and IP address ranges ID 11.

These ranges include both Transport Relays and media processors, front-ended by an Azure Load Balancer. The Microsoft Teams Transport Relays provide STUN and TURN functionality, but they aren’t ICE endpoints. Also, the Microsoft Teams Transport Relays don’t terminate media, TLS, or do any transcoding. They can bridge TCP (if HdxRtcEngine.exe uses TCP) to UDP when they forward traffic to other peers or media processors.

Workspace app WebRTC media engine contacts the closest Microsoft Teams Transport Relay in the Microsoft 365 cloud. The media engine uses anycast IP and port 3478–3481 UDP (different UDP ports per workload, though multiplexing can happen) or 443 TCP/TLS for fallbacks. Call quality depends on the underlying network protocol. Because UDP is always recommended over TCP, we advise you to design your networks to accommodate UDP traffic in the branch office.

If Microsoft Teams loaded in optimized mode and HdxRtcEngine.exe is running on the endpoint, ICE failures might cause a call setup failure or one-way-only audio/video. When a call can’t be completed or the media streams aren’t full duplex, check the Wireshark trace on the endpoint first. For more information about the ICE candidate gathering process, see “Collecting logs” in the Support section.

Note:

If the endpoints don’t have internet access, the users might still be able to make a peer-to-peer call if they are both on the same LAN. Meetings fail. In this case, there’s a 30-second timeout before the call setup begins.

Call setup

Use this architecture diagram as a visual reference for the call flow sequence. The corresponding steps are indicated in the diagram.

Architecture

1. Start Microsoft Teams.
2. Microsoft Teams authenticates to O365. Tenant policies are pushed down to the Microsoft Teams client, and relevant TURN and signaling channel information is relayed to the app.
3. Microsoft Teams detects that it’s running in a VDA and makes API calls to the Citrix JavaScript API.
4. Citrix JavaScript in Microsoft Teams opens a secure WebSocket connection to WebSocketService.exe running on the VDA, which spawns WebSocketAgent.exe inside the user session.
5. WebSocketAgent.exe instantiates a generic virtual channel by calling into the Citrix HDX Microsoft Teams Redirection Service (CtxSvcHost.exe).
6. Citrix Workspace app’s wfica32.exe (HDX engine) spawns a new process called HdxRtcEngine.exe, which is the new WebRTC engine used for Microsoft Teams optimization.

7. Citrix media engine and Teams.exe have a 2-way virtual channel path and can start processing multimedia requests.

   —–User calls——

8. Peer A clicks the call button. Teams.exe communicates with the Microsoft Teams services in Microsoft 365, establishing an end-to-end signaling path with Peer B. Microsoft Teams asks HdxRtcEngine for a series of supported call parameters (codecs, resolutions, and so forth, which is known as a Session Description Protocol (SDP) offer). These call parameters are then relayed using the signaling path to the Microsoft Teams services in Microsoft 365 and from there to the other peer.
9. The SDP offer/answer (single-pass negotiation) takes place through the signaling channel, and the ICE connectivity checks (NAT and Firewall traversal using STUN bind requests) complete. Then, Secure Real-time Transport Protocol (SRTP) media flows directly between HdxRtcEngine.exe and the other peer (or Microsoft 365 conference servers if it’s a meeting).

Microsoft Phone System

Phone System is Microsoft’s technology that enables call control and PBX in the Microsoft 365 cloud with Microsoft Teams. Optimization for Microsoft Teams supports Phone System, using Microsoft 365 Calling Plans or Direct Routing. With Direct Routing, you connect your own supported session border controller to the Microsoft Phone System directly without any additional on-premises software. Call queues, transfer, forward, hold, mute, and resume a call are supported.

DTMF

The dual-tone multi-frequency (DTMF) feature is supported with these versions of Citrix Workspace app (and later):

• Citrix Workspace app for Windows version 2102
• Citrix Workspace app for Windows LTSR 1912 CU5 (Windows 10 OS only)
• Citrix Workspace app for Linux version 2101
• Citrix Workspace app for Mac version 2101
• Citrix Workspace app for Chrome OS version 2111.1

Support for dynamic e911

Starting with version 2112, Citrix Workspace app supports dynamic emergency calling. When used in Microsoft Calling Plans, Operator Connect, and Direct Routing, it allows you to do the following:

• Configure and route emergency calls.
• Notify security personnel.

The notification is provided based on the current location of the Citrix Workspace app that runs on the endpoint, instead of the Microsoft Teams client that runs on the VDA.

Ray Baum’s law requires the 911 caller’s dispatchable location to be transmitted to the appropriate Public Safety Answering Point (PSAP). Microsoft Teams Optimization with HDX is compliant with Ray Baum’s law when used with the following versions of Citrix Workspace app:

• Citrix Workspace app for Windows version 2112.1 and later
• Citrix Workspace app for Linux version 2112 and later
• Citrix Workspace app for Mac version 2112 and later
• Citrix Workspace app for Chrome OS version 2112 and later

To enable dynamic emergency calling, the administrator must use the Microsoft Teams Admin Center and configure the following to create a network or emergency location map:

• Network settings
• Location Information Service (LIS)

For more information on Dynamic emergency calling, see Microsoft’s documentation.

The dispatchable location information that Citrix Workspace app relays to Microsoft Teams are:

• Chassis ID / Port ID using Link Layer Discovery Protocol (LLDP) for Ethernet/Switch connections. Ethernet/Switch (LLDP) is supported on:

  • Windows versions 8.1 and 10
  • macOS, which requires LLDP enablement software. To download the LLDP enablement software, go to www.microsoft.com and search for LLDP enablement software.
  • Linux, which requires the LLDP library to be included in the operating system(OS) distribution of the Thin Client.
• WLAN BBSID and {IPv4-IPv6; Subnet; MAC Address} of the endpoint where Citrix Workspace app is installed.
  • Subnet and WiFi-based locations are supported on the Workspace app for Windows, Linux, and Mac.
• Latitude and Longitude, if user permission is granted at the OS-level where Citrix Workspace app is installed (permission is set to HDX RTC Engine)
  • Supported on all Workspace app platforms. However, for Citrix Workspace for Linux, you must include the libgps library in the OS distribution of the Thin Client (>sudo apt-get install libgps-dev gpsd lldpd).

Firewall considerations

When users start an optimized call using the Microsoft Teams client for the first time, they might notice a warning with the Windows firewall settings. The warning asks for users to allow communication for HdxTeams.exe or HdxRtcEngine.exe (HDX Overlay Microsoft Teams).

The following four entries are added under Inbound Rules in the Windows Defender Firewall > Advanced Security console. You can apply more restrictive rules if you want.

Microsoft Teams and Skype for Business Coexistence

You can deploy Microsoft Teams and Skype for Business side by side as two separate solutions with overlapping capabilities. For more information, see Understand Microsoft Teams and Skype for Business coexistence and interoperability.

Citrix RealTime Optimization Pack and HDX optimization for Microsoft Teams multimedia engines then honor the configuration set in your environment. Examples include island modes and Skype for Business with Microsoft Teams collaboration. Also, Skype for Business with Microsoft Teams collaboration and meetings.

Peripheral access can be granted only to a single application at the time. For example, webcam access by the RealTime Media Engine during a call locks the imaging device during a call. When the device is released, it becomes available for Microsoft Teams.

Citrix SD-WAN: optimized network connectivity for Microsoft Teams

Optimal audio and video quality require a network connection to the Microsoft 365 cloud that has low latency, low jitter, and low packet loss. Backhauling of Microsoft Teams audio-video RTP traffic from Citrix Workspace app users at branch office locations to a data center before going to the internet can add excessive latency. It might also cause congestion on WAN links. Citrix SD-WAN optimizes connectivity for Microsoft Teams following Microsoft 365 network connectivity principles. Citrix SD-WAN uses the Microsoft REST-based Microsoft 365 IP address and web service and proximate DNS. This use is to identify, categorize, and steer Microsoft Teams traffic.

Business broadband internet connections in many areas suffer from intermittent packet loss, periods of excessive jitter, and outages.

Citrix SD-WAN offers two solutions to preserve Microsoft Teams audio-video quality when network health is variable or degraded.

• If you use Microsoft Azure, a Citrix SD-WAN virtual appliance (VPX) deployed in the Azure VNET provides advanced connectivity optimizations. These optimizations include seamless link failover and audio packet racing.
• Citrix SD-WAN customers can connect to Microsoft 365 through the Citrix Cloud Direct service. This service provides reliable and secure delivery for all internet-bound traffic.

If the quality of the branch office internet connection isn’t a concern, it might be enough to minimize latency. Steer Microsoft Teams traffic directly from the Citrix SD-WAN branch appliance to the nearest Microsoft 365 front door to minimize latency. For more information, see Citrix SD-WAN Office 365 optimization.

Multi-window meetings and chat

You can use multiple meetings or chat windows for Microsoft Teams in Windows. For details on the pop-out feature, see Microsoft Teams Pop-Out Windows for Chats and Meetings on the Microsoft 365 site.

Note:

This feature is supported with Citrix Workspace app for Windows 2112.1, Mac 2203, Linux 2203, and VDA 2112.

Background Blurring

Citrix Workspace app for Windows now supports background blurring and effects in Microsoft Teams optimization with HDX.

Now, you can either blur or replace the background with a default image and avoid unexpected distractions by helping the conversation stay focused on the silhouette (body and face). The feature can be used with either P2P or conference calls.

Note:

This feature is now integrated with the Microsoft Teams UI/buttons. MultiWindow support is a prerequisite that requires a VDA update to 2112 or higher. CWA 2207 is required for UI control to work from Microsoft Teams. For more information, see Multi-window meetings and chat.

Limitations:

• Background Blurring or replacement with Microsoft Teams default images is supported only for Windows clients.
• Admin and user-defined background image replacement is not supported in the Teams UI. Custom background images can be configured using HKCU registry settings on the client, as long as the image is also stored on the endpoint.
• The background effect doesn’t persist between desktop sessions. When you close and relaunch Microsoft Teams or the VDA is reconnected, the background effect is reset to off.
• After the ICA session is reconnected, the effect is off. However, the Microsoft Teams UI shows that the previous effect is still set to On by a tick mark. Citrix and Microsoft are working together to resolve this issue.
• The client device must be connected to the internet while replacing the background image with a Teams default image.

Setting a background image

The following registry keys are only required:

• if you don’t plan to use the Teams UI to control the feature, or
• if an admin wants to override default behaviors.

For example, disable Background Blurring because the endpoint is not powerful enough.

To set a custom background image, administrators or end-users must configure the following registry key on the client/endpoint:

Location: HKEY_CURRENT_USER\SOFTWARE\Citrix\HDXMediaStream

• Name: VideoBackgroundEffect
• Type: DWORD
• Value: 0 (disabled), 1 (enabled), 2 (background image replacement)

Value set to 1 will blur the background.

Value set to 2 also requires the VideoBackgroundImage key to be present as well. The following key is required only if you want to replace the background image and not for blurring:

• Name: VideoBackgroundImage
• Type: REG_SZ
• Value: my_image_name.jpeg

The video background image must be present in the C:\Program Files (x86)\Citrix\ICA Client directory.

This registry configuration can also be used to enable background blurring or image replacement in Citrix Workspace app 2206 without the Teams UI selector. In other words, if your environment or VDA doesn’t support multi-window, you can still apply the HKCU registry workaround with Citrix Workspace app 2206 or higher to achieve a similar result, although the user cannot control the functionality in the middle of the HDX session or Teams call.

Registry key changes only take effect when the HDX session connects.

Client CPU Consumption considerations

While the feature is frugal on the CPU, you can expect an increase in consumption. For example, on a thin client with a 4 Core, 1.5 GHz Intel® Pentium® Silver chip with TurboBoost up to 2.8 GHz, the background blurring adds about 2% to the CPU usage. Average CPU usage was less than 20%.

Gallery view and active speakers in Microsoft Teams

Microsoft Teams supports Gallery, Large gallery, and Together mode layouts.

Microsoft Teams displays a 2x2 grid with video streams of four participants (known as Gallery). In this case, Microsoft Teams sends four video streams to the client device for decoding. When more than four participants share video, only the last four most active speakers appear on the screen.

Microsoft Teams also provides the large gallery view with a grid up to 7x7. As a result, the Microsoft Teams conference server composites a single video feed and sends it to the client device for decoding, resulting in lower CPU consumption. This single, matrix-style feed might include users’ self-preview video as well.

Lastly, Microsoft Teams supports Together mode, which is part of the new meeting experience. Using AI segmentation technology to digitally place participants in a shared background, Microsoft Teams puts all participants in the same auditorium.

The user can control these modes during a conference call by selecting Gallery, Large gallery, or Together mode layouts in the ellipses menu.

Support for video aspect ratio constraints (CWA for Windows 2102, CWA for Linux 2106, CWA for MAC 2106 and later):

• The option Fill to frame is available in Gallery/Large Gallery View. This option crops the video size to fit it in the subwindow. Fit to frame, on the other hand, displays black bars (letterbox) on the sides of the video so there is no cropping.

The following table provides a comparison of Gallery and Large Gallery layouts:

Screen sharing in Microsoft Teams

Microsoft Teams relies on video-based screen sharing (VBSS), effectively encoding the desktop being shared with video codecs like H264 and creating a high-definition stream. With HDX optimization, incoming screen sharing is treated as a video stream.

Starting from Citrix Workspace app 2109 or higher for Windows, Linux or Mac, users can share their screens and video camera simultaneously.

With earlier versions, if you’re in the middle of a video call and the other peer starts to share the desktop, the original camera video feed is paused. Instead, the screen sharing video feed shows. The peer must then manually resume the camera sharing.

Note for PowerPoint Live

This limitation does not exist if you’re sharing content from PowerPoint Live. In that case, other peers can still see your webcam and content and navigate back and forth to review other slides. In this scenario, the slides are rendered on the VDA. To access a PowerPoint Live slide deck, click on the ‘Share tray’ button and select one of the suggested PowerPoint slides, or click ‘Browse’ and find a PowerPoint file on your computer or in OneDrive.

Outgoing screen sharing is also optimized and offloaded to Citrix Workspace app. In this case, the media engine captures and transmits only the Citrix Desktop Viewer (CDViewer.exe) window, with a red border drawn around it. Any local application overlapping with Desktop Viewer isn’t captured.

Note

Set specific permission in Citrix Workspace app for Mac to enable screen sharing. For more information, see System Requirements.

Multimonitor

If Desktop Viewer (CDViewer.exe) is in full-screen mode and spanning across multimonitor setups, Citrix Workspace app 2106 or later (Windows/Linux/Mac) allows the screen picker to select the monitor to share.

Known limitation:

• If Desktop Viewer is disabled or if Desktop Lock is being used, multimonitor selection isn’t available in the Microsoft Teams screen picker. The Desktop Viewer might be disabled either by editing the .ICA file template or StoreFront web.config. SHIFT+F2 hotkey isn’t compatible with multimonitor screen sharing.
• In Workspace app versions older than 2106, only the primary monitor is shared. Drag the application in the virtual desktop to the primary monitor for the other peer on the call to see it.
• Multimonitor screen sharing might not work if you configure the Citrix Workspace app with the virtual monitor layout feature (logical partition of a single physical monitor). In this case, all virtual monitors are shared as a composite image.
• Older versions of the Citrix Workspace app for Windows (1907 up to 2008) also shares a local application that runs in the client machine. This sharing is possible only if the local app was overlaid on top of Desktop Viewer. This behavior was removed in 2009.6 or higher, and 1912 CU5 or higher.
• While screen sharing, if you change from windowed mode to full-screen, screen sharing stops. You must stop and share again for screen sharing to work.

Screensharing from seamless application:

If you’re publishing Microsoft Teams as a standalone, seamless application, screen sharing captures the local desktop of your physical endpoint. Citrix Workspace app minimum version 1909 is required.

App sharing

Starting with Citrix Workspace app for Windows 2112.1 and VDA 2112, Microsoft Teams supports app sharing.

Starting with Citrix Workspace app for Windows 2109, Mac 2203 and VDA 2109, Microsoft Teams supports screen sharing of specific apps running in the virtual session. To share a specific app:

1. Navigate to the Microsoft Teams app within your remote session.
2. Click Share content in your Microsoft Teams UI.
3. Select an app to share in the meeting. The red border appears around an app you selected and the peers on the call can see the shared app.

To share a different app, click Share content again and select a new app.

If you want to disable app sharing, create the following registry key on the VDA at HKLM\SOFTWARE\Citrix\Graphics: Name: UseWsProvider Type: DWORD Value: 0

Note:

• If you minimize an app, Microsoft Teams displays the last image from the shared app. You can maximize the window to resume screen sharing.
• Screen sharing depends on the VDA-side capturing of the window. The content is then relayed at a maximum rate to the Citrix Workspace app. The maximm rate is 30 frames per second. The Citrix Workspace app forwards the content to the peers or conference server.

Known limitations with screen sharing of specific app:

• Mouse pointer isn’t visible when you are screen sharing an app.
• If you minimize an app when you’re sharing it, only the app icon appears in the screen picker. The thumbnail of the app isn’t previewed in the screen picker. You can’t share the content and the red border does not appear until you maximize the app.
• LAA apps shows a list of apps that can be shared with desktop apps in the optimized Microsoft Teams in the VDA. However, when you select the app from the list, the result might not be as expected

Compatibility with app protection The screen sharing of a specific app is compatible with the app protection feature in HDX optimized Microsoft Teams. You can screen share a specific app, if you’ve launched the app or desktop from a delivery group that has app protection enabled.

When you click Share content in the Microsoft Teams UI, the screen picker removes the Desktop option. You can only select the Window option to share any open app.

Note:

When you launch apps or desktops from a delivery group with app protection enabled, you aren’t able to see the incoming video or screen sharing if you are using Workspace app for Windows 2202 or earlier. This limitation is not present in Workspace app for Windows 2203 LTSR and later.

Give and Request control in Microsoft Teams

This feature is supported in the following versions of Citrix Workspace app (there is no dependency on the VDA version or Operative System, single session or multisession):

• Citrix Workspace app for Windows version 2112.1 and later
• Citrix Workspace app for Mac version 2203.1 and later

You can request control during a Microsoft Teams call when a participant is sharing the screen. Once you have control, you can make selections, edits, or other keyboard and mouse activities to the shared screen.

To take control when a screen is being shared, click Request control button in the Microsoft Teams UI. The meeting participant who’s sharing the screen can either allow or deny your request.

While you have control, you can make selections, edits, and other modifications to the shared screen. For these actions, you can use both keyboard and mouse. When you’re done, click Request control.

Limitations:

Give and Request control are not available if the user is sharing a single app (also known as App sharing). The full desktop or monitor must be shared.

Peripherals in Microsoft Teams

When optimization for Microsoft Teams is active, the Citrix Workspace app accesses the peripherals (headsets, microphones, cameras, speakers, and so forth). Then the peripherals are properly listed in the Microsoft Teams UI (Settings > Devices).

Microsoft Teams does not access the devices directly. Instead, it relies on the Workspace app WebRTC media engine for acquiring, capturing, and processing the media. Microsoft Teams lists the devices for the user to select.

The peripherals that are inserted while Microsoft Teams is active aren’t selected by default. You’ve to manually select the peripherals from the Settings > Devices screen of the Microsoft Teams UI. After the peripheral is selected, Microsoft Teams caches the information of the peripherals. As a result, the peripherals are automatically selected when you reconnect to a session from the same endpoint.

Recommendations:

• Microsoft Teams certified headsets with built-in echo cancellation. In setups with extra peripherals, where microphone and speakers are on separate devices, there might be an echo. An example is a webcam with a built-in microphone and a monitor with speakers. When using external speakers, place them as far as possible from the microphone. Also, place them away from any surface that might refract the sound into the microphone. For more information, go to www.microsoft.com and search for Microsoft Teams certified headsets.
• Microsoft Teams certified cameras, although Skype for Business certified peripherals are compatible with Microsoft Teams. For more information, go to www.microsoft.com and search for Microsoft Teams certified cameras and Skype for Business certified peripherals.
• Citrix Workspace app media engine can’t take advantage of CPU offloading with webcams that perform on-board H.264 encoding -UVC 1.1 and 1.5.

Note:

Workspace app 2009.6 for Windows can now acquire peripherals with audio formats with 24-bit or with frequencies above 96 kHz.

HdxTeams.exe (in the Citrix Workspace app for Windows 2009 or older) supports only these specific audio device formats (channels, bit depth, and sample rate):

• Playback Devices: up to 2 channels, 16 bit, frequencies up to 96,000 Hz
• Recording Devices: up to 4 channels, 16 bit, frequencies up to 96,000 Hz

Even if one speaker or microphone does not match the expected settings, device enumeration in Microsoft Teams fails and None displays under Settings > Devices.

Webrpc logs in HdxTeams.exe show this type of information:

Mar 27 20:58:22.885 webrtcapi.WebRTCEngine Info: init. initializing...

Mar 27 20:58:23.190 webrtcapi.WebRTCEngine Error: init. couldn't create audio module!

As a workaround, disable the specific device or:

1. Open the Sound Control Panel (mmsys.cpl).
2. Select the playback or recording device.
3. Go to Properties > Advanced and change the settings to a supported mode.

Fallback mode

If Microsoft Teams fails to load in optimized VDI mode (“Citrix HDX Not Connected” in Teams/About/Version), the VDA falls back to legacy HDX technologies. The legacy HDX technologies might be webcam redirection and client audio and microphone redirection. If you’re using a Workspace app version/platform OS that does not support Microsoft Teams optimization, fallback registry keys do not apply. In fallback mode, the peripherals are mapped to the VDA. The peripherals appear to the Microsoft Teams app as if they were locally attached to the virtual desktop.

You can now granularly control the fallback mechanism by setting the registry keys in the VDA. For information, see Microsoft Teams fallback mode in the list of features managed through the registry.

This feature requires Microsoft Teams version 1.3.0.13565 or later.

To determine if you are in optimized or unoptimized mode when looking at the Settings > Devices tab in the Microsoft Teams app, the main difference is the camera name. If Microsoft Teams loaded in unoptimized mode, legacy HDX technologies launch. The webcam name has the Citrix HDX suffix as shown in the following graphic. The speaker and microphone device names might be slightly different (or truncated) when compared to the optimized mode.

When legacy HDX technologies are used, Microsoft Teams doesn’t offload audio, video, and screen sharing processing to the endpoint’s Citrix Workspace app WebRTC media engine. Instead, HDX technologies use server-side rendering. Expect high CPU consumption on the VDA when you turn on video. Real-time audio performance might not be optimal.

Known limitations

Citrix limitations

Limitations on Citrix Workspace app:

• HID buttons - Answer and end call aren’t supported. Volume up and down are supported.
• QoS settings in the Admin Center for Microsoft Teams don’t apply for VDI users.
• Users can’t take screenshots of Teams content if using a snipping tool on the VDA. Only if used at the client side the content can be captured.

Limitation on the VDA:

• When you configure the Citrix Workspace app High DPI setting to Yes, the redirected video window appears out of place. This limitation occurs when the monitor’s DPI scaling factor is set to anything above 100%.

Limitations on Citrix Workspace app and the VDA:

• You can only control the volume of an optimized call using the volume bar on the client machine – not on the VDA.

Microsoft limitations

• A 3x3 gallery view isn’t supported. Microsoft Teams dependency – contact Microsoft for when to expect a 3x3 grid.
• Interoperability with Skype for Business is limited to audio calls, no video modality.
• Incoming and outgoing video stream maximum resolution is 720p.
• PSTN call ringback tone isn’t supported.
• Media bypass for Direct Routing isn’t supported.
• Broadcast and live event producer and presenter roles aren’t supported. Attendee role is supported but not optimized (renders on the VDA instead).
• The zoom in and zoom out function in Microsoft Teams isn’t supported.
• Location-Based Routing and Media Bypass are not supported.
• Call health is not available.
• Breakout rooms are supported for VDI participants. Microsoft Teams doesn’t support breakout rooms if the organizer is a VDI user.
• Call merge is not supported (option not displayed in the user interface).

Citrix and Microsoft limitations

• When doing screen sharing, the option include system audio isn’t available.
• Simulcast isn’t available.
• Secondary ringer (Teams > Settings > Devices) isn’t supported.
• The options to blur or customize the background aren’t yet supported on Mac and Linux clients.

Additional information

• Monitor, troubleshoot, and support Microsoft Teams
• Deploy the Microsoft Teams desktop app to the VM
• Install Microsoft Teams using MSI (VDI Installation section)
• Thin clients
• Skype for Business Network Assessment Tool
• Understand Microsoft Teams and Skype for Business coexistence and interoperability