Page 35 - MSDN Magazine, October 2017

Figure 1 Windows Device Portal Web UI
WindowsDevicePortalWrapper (bit.ly/2tx2NXF) open source project offers a library for developing custom WDP user agents in C#. In this article, I’ll use the browser and the free command-line utility curl (curl.haxx.se) to exercise my custom REST APIs.
WDP was designed with extensibility in mind. For example, WDP is customized for each edition of Windows via built-in plug-ins. With the Windows 10 Creators Update, it’s now possible for third parties to extend WDP by creating packaged plug-ins. A pack- aged plug-in provides custom REST endpoints, with an optional Web-based UI, implemented and deployed within a Windows Store app. Figure 2 illustrates how the system works.
Readers familiar with the internals of Microsoft’s IIS will recog- nizethedesignofWDP.AswithIIS,WDPisbuiltupontheHTTP Server API (also referred to as HTTP.SYS), dividing responsibilities between the HTTP Controller and HTTP Worker roles. The WDP service implements the controller, running under the local SYSTEM account. Each WDP packaged plug-in implements a worker, run- ning within the AppContainer sandbox in the user’s security context.
It’spossibletohostaWebserverfromscratchwithinastoreapp, using the HTTP Server API. However, implementing a WDP
Session 1 AppContainer Packaged Plug-in (User)
packaged plug-in offers several advantages. WDP provides en- cryption, authentication, and security services for all content and REST APIs, including those in packaged plug-ins. This includes protection from cross-site request forgery and cross-site Web- Socket hijacking attacks. Additionally, WDP manages the lifespan of each packaged plug-in, which may execute from either a fore- ground UI-visible app or as a background task. In short, it’s simpler and safer to implement REST APIs with a packaged plug-in. The sequence diagram in Figure 3 illustrates the flow of execution for a packaged plug-in.
In its package app manifest, each plug-in identifies itself with a windows.devicePortalProvider app extension and associated app service, and declares its routes (URLs) of interest. A plug-in can register either a content route, a REST API route or both. At pack- age install time, the manifest data is registered with the system.
At startup, the WDP service scans the system for registered WDP packaged plug-ins, as identified by the windows.devicePortal- Provider app extension. For each plug-in discovered, the WDP service reads the package manifest for route information. The set of routes requested by the packaged plug-in, referred to as the URLGroup, is registered with HTTP.SYS to create an on-demand HTTP request queue. The WDP service then monitors each pack- aged plug-in request queue for incoming requests.
At the first route request for a plug-in, the WDP service launches a WDP sponsor in the user’s security context. The WDP sponsor in turn activates the packaged plug-in, transferring the HTTP request queue to the plug-in. The WDP service activates and communicates with the packaged plug-in via the app service described in the mani- fest. The app service connection functions like a named pipe, with the WDP sponsor acting as the client of this connection, and the pack- aged plug-in acting as the server. This sponsorship design ensures that long-running requests aren’t interrupted by the system’s resource management policies. The WDP runtime then begins servicing requests on behalf of the plug-in. Content requests are serviced auto- matically, while REST API requests are dispatched to the packaged plug-in’s registered RequestReceived event handler. Plug-in lifetime is managed by both the WDP service and the Process Lifetime Manager (PLM). For details on managing plug-in state when a background task is suspended, see the article, “Launching, Resuming and Background Tasks” (bit.ly/2u0N7fO). A job object further ensures that WDP service rundown is complete, terminating any running WDP sponsors and their associated packaged plug-ins.
Writing a Packaged Plug-in
Creating the Project Before creating your packaged plug-in, you’ll need to decide whether your Web request handler can run as a back- ground task or whether it must run in the process of a foreground app. Foreground execution is necessary if, for example, the handler requires access to the app’s internal data structures. This flexibility in execution is enabled by the underlying AppService, which can be configured for either background or foreground operation. For a more thorough discussion of AppServices, please consult the articles, “Create and Consume an App Service” (bit.ly/2uZsSfz), and, “Convert an App Service to Run in the Same Process as Its Host App” (bit.ly/2u0G8n1).
October 2017 31
Session 0 Job Object
URL Group
WDP
Sponsor AppSe
(User)
WDP Service Controller (SYSTEM)
HTTP.SYS
App Manifest
Provider ... Provider
HTTP.SYS
Figure 2 Windows Device Portal Architecture msdnmagazine.com
WDP rvice Runtime Worker
...
WDP Runtime Worker