Setting up the virtual app interop

Experimental

This feature is experimental in Finsemble 7. It might change substantially over time or it might not be supported in the future. Use at your own risk.

When a user runs a Finsemble smart desktop on their local machine, such as a work laptop, they can load and run multiple FDC3-enabled native apps that are located on and run from the same local machine. They can also run apps hosted on a remote server, such as a Citrix server. (See Citrix's product page or Wikipedia's article about Citrix Virtual Apps.) Citrix virtual apps run on the remote Citrix server, but are displayed within windows on the local desktop so that the app appears to the user to be running locally. This is akin to a remote desktop connection where the display screen is cropped to fit a single window as opposed to the full desktop view.

When virtual apps include API integration and are launched through Finsemble, they communicate with Finsemble through a Microsoft Terminal Services plug-in to participate in FDC3 Interop. A virtual app then behaves in a similar way to a local app: the user can link such an app to a channel, have it broadcast and receive context, and raise and listen for intents.

Before you begin

Before you begin configuring virtual apps to participate in FDC3 Interop within Finsemble, make sure that you:

• Run Microsoft Windows (only Windows virtual clients are supported at this point);
• Install Finsemble's Microsoft Terminal Services client plug-in (Finsemble.IWTSPlugin.dll). This plug-in has these requirements:
  • Requires administrative privileges;
  • It must be located on the user's desktop;
  • It must be registered as a COM object within the MS Windows registry;
  • It must be listed as a Terminal Services Client Plug-in within the Windows registry.
• Verify that the native app includes API integration and is configured as a virtual app. It also must meet these requirements:
• Currently, only .NET Core WPF apps are supported;
• The app must be deployed to a Citrix server and registered with an alias as a virtual app;
• An entry in the FDC3 appd.config for the app must specify windowType:"Citrix".
• Install Citrix Workspace on the user's desktop. The user must be given access to both the Citrix server and the virtual app.

Installing Finsemble's MSTS client plug-in

Finsemble's virtual app interop uses the same set of Microsoft Windows APIs that Citrix uses to connect to the remote server and display the app. You need no additional networking infrastructure to establish communication between Finsemble and the virtual app running on the server.

The Microsoft Terminal Services Client plug-in DLL enables communication between virtual apps and Finsemble. The plug-in DLL must be registered to be automatically loaded whenever Citrix makes a connection to the remote server. This involves a couple of steps and requires administrative privileges. Here is the process to configure it:

1. Copy the plug-in. Copy Finsemble.IWTSPlugin.dll to each user's computer. The location can be anywhere you want as long as it is persistent. In other words, make sure it won't be removed by another system operation (such as when removing an application or processing an update). Also, don't install it in the same location as Finsemble unless you opt for a system level installation of Finsemble.

2. Register the plug-in. Register the DLL as a COM add-in by executing this command in a elevated command prompt:

   regsvr32.exe Finsemble.IWTSPlugin.dll

   Then, add this registry entry so that Citrix loads the DLL each time it makes a connection.

   [HKEY_CURRENT_USER\SOFTWARE\Microsoft\Terminal Server Client\Default\AddIns\Finsemble.IWTSPlugin] "Name"="{3C8458A3-2EBE-4840-BB07-3BA5BF810588}"

note

The Citrix plug-in is not a standard part of Finsemble and you must obtain it separately. Contact your sales rep for details.

Developing Finsemble virtual apps

note

Currently, Finsemble supports only .NET Core WPF apps.

Any native app that includes the finsemble-dll .NET library can be launched as a virtual app. This is because when the component is configured as a virtual app, it connects to the plug-in we've configured in the previous section and sends all communication to it.

For each native app, a Citrix administrator needs to deploy it to the Citrix server, provide an alias for it, enable command line arguments, and grant users rights to launch it. Finsemble will launch the virtual app through Citrix's SelfService.exe (adding additional proprietary command line arguments that are picked up by finsemble.dll). You must configure the app within Citrix to accept dynamic arguments by setting the command line parameter to %*. See Driving the Citrix Receiver Self-Service Plug-in Programmatically (external) for details.

For more info about how to set this up, see Citrix documentation or contact your Citrix or partner representative for assistance.

Configuring virtual apps in Finsemble

After you configure the remote Citrix environment and you have the virtual app available in your Citrix Workspace app launcher, you can launch the app within Finsemble by adding an AppD entry for the remote app which contains these additional parameters:

• manifest.window.windowType: "Citrix"
• manifest.window.alias: the Citrix alias / name of the virtual app
• manifest.window.arguments: Any additional command line arguments, separated by & (e.g. param1=value1&param2=value2)

For example, an AppD entry to launch a remotely-hosted app with name of "WPF App Alias" can look like this:

  "Remotely-hosted FDC3 WPF App": {
      "appId": "Remotely-hosted FDC3 WPF App",
      "name": "Remotely-hosted FDC3 WPF App",
      "manifest": {
          "window": {
               "windowType": "Citrix",
               "alias": "WPF App Alias",
               "arguments": "param1=value1&param2=value2"
              },
           "foreign": {
                "components": {
                    "App Launcher": {
                           "launchableByUser": true
                    }
                }
           }
      }
  },          

Pitfalls and troubleshooting

Where are my MSTS plug-ins logged?

If the virtual app loads successfully, you will find all its logs within the Central Logger. If it doesn't, the Finsemble.IWTSPlugin.dll logs initialization and connection attempts are logged by default to the user's TEMP directory, %TEMP%\Finsemble.IWTSPlugin.log.

There is one exception. If the Citrix Workspace is running under a different user, the directory could be located in that other user's TEMP directory.

Why doesn't my virtual app participate in data interop?

The most likely cause is that you didn't launch the app from Finsemble. If you launch a virtual app standalone from the Citrix Workspace app storefront, the virtual app won't communicate with Finsemble and it won't participate in data interop. Virtual apps must be configured within Finsemble as described in Configuring virtual apps in Finsemble and then launched directly from the app launcher if you want the app to participate in data interop with other Finsemble apps.

Why aren't my virtual apps opening or closing when I expect?

Finsemble can launch Citrix virtual apps and allow them to connect to the inter-application communication in order to participate in data interop, but such apps cannot be included in Finsemble's workspaces. This means that users must explicitly open and close virtual apps because these apps aren't affected by workspace switches.

Why don't my virtual apps snap, group, or auto-arrange?

Virtual apps are not included under window management. The size and position of virtual app windows is dictated by Citrix and the underlying server. As a result, virtual apps don't snap, group, or auto-arrange with other, locally-running, Finsemble apps.

Why is my app unresponsive when I lose connectivity?

The connectivity and responsiveness of your virtual app is the responsibility of Citrix, not of Finsemble. When you experience network connectivity issues, Citrix uses its own logic for handling virtual apps. By default, if you lose network connection with the Citrix server while using a virtual app, the app remains open in an unresponsive state on your desktop for up to 5 minutes. After this time has elapsed, if the connection can't be re-established Citrix closes all the unresponsive virtual apps. This is controlled via Citrix, so if you want to adjust this behavior, you must contact your own Citrix admin.

Can I use virtual apps on a Mac?

No. Virtual app interop is only supported in full Windows environments, meaning both the local Finsemble desktop and the Citrix server must be running Windows. If your local Finsemble desktop is running on a Mac, you won't be able to participate in data interop with virtual apps.

Can I use virtual app interop for Java or web-based apps?

No. Virtual app interop is supported only for .NET-based projects. Apps that implement Finsemble's interop API via the .NET-based Finsemble.DLL are supported by Virtual App Interop. Java or web-based apps that are hosted virtually can't participate in virtual data interop.

See also

Integrating native apps