Deploy, tune and troubleshoot an SDK app
8 min read
Most SDK problems fall into a handful of causes, and most of them show up the first time you run the app on a host. This page covers getting the app onto the host properly and what to check when something does not work.
Deploy to a host
Package the app so the host needs nothing else from you:
- Copy your executable and its dependencies to one folder on the host, with Onscryn.Capture.dll beside the executable.
- Install what your app needs to run, for example the .NET runtime it targets and any database client.
- Put the app in a folder every session account can read and run from. A path under your own profile will not work for the accounts sessions run as.
- In Admin, then Apps, add the application, give it the full path to the executable, add any arguments, and set the capture mode to SDK.
Tune it
Use the image quality and format settings in the app's dashboard entry to trade sharpness for bandwidth, and look at the result at the size people will actually use. Warm slots keep a few sessions started and ready, so people who open the app do not wait for it to start. Turn them on for apps with a slow start and steady use.
The session fails straight away
A message about the app exiting before producing a first frame means the process ended or never presented.
- The DLL is missing, or it sits somewhere other than beside the executable.
- The architecture does not match. The SDK is 64-bit, so a 32-bit app cannot load it.
- Onscryn_Start returned 0. Log its result and exit with a clear message.
- The app crashed during startup. Run it with the file-dump transport on the host and read its own log.
- Present was never called, because nothing has changed yet. Send one frame after the window shows.
A blank or black picture
The session starts but the tab shows nothing useful.
- You acquired a surface but never rendered into it before presenting.
- PrintWindow used the wrong flag for a composited window. Use the render-full-content flag for XAML and similar content.
- The window you rendered is hidden or minimized, which gives an empty bitmap.
- The surface size does not match the window, so the picture is cropped.
Input does nothing
The picture is there but clicks and keys have no effect.
- The handle you passed to Onscryn_AcquireSurface is not the window that should receive input.
- Automatic input is switched off in the options and you have not handled the input callback.
- The app reads input through DirectInput or raw input, which ignores window messages. Handle the input callback instead.
- Clicks land in the wrong place after you composited several windows. Set the surface rectangle each frame.
A .NET app crashes at random
Crashes that come and go, usually right after a callback, point at the interop layer.
- A delegate was passed to the SDK but not stored in a field, and was garbage collected. Keep every delegate alive for the life of the process.
- A struct does not match the header. Check the options struct field by field, including the disable flags at the end.
- A handler touched a control from an SDK thread in a way that is not thread safe.
Actions time out or say unknown
A workflow step that calls an action fails or never returns.
- The name is not registered, or is spelled differently from the one in the workflow.
- The handler never calls Onscryn_SendActionResult on some path, such as an exception.
- The handler opened a dialog or waited on the UI thread, which blocks the thread that should reply.
- You registered the actions before starting the SDK. Register after Onscryn_Start.
The UI tree is empty or missing controls
Workflows cannot find a control that is plainly on screen.
- Controls have no name or id, so they appear as anonymous items.
- The controls are hidden, which drops them from the tree.
- The controls are owner-drawn and expose nothing to UI Automation.
- Auto UI tree is disabled in the options.
Printing does not reach the browser
Onscryn_EnablePrinting returning 2 means the printer is not installed on that host. Install it, or fall back to sending the PDF with Onscryn_SendFile.
Related