Windows Device Portal overview

The Windows Device Portal lets you configure and manage your device remotely over a network or USB connection. It also provides advanced diagnostic tools to help you troubleshoot and view the real-time performance of your Windows device.

Windows Device Portal is a web server on your device that you can connect to from a web browser on a PC. If your device has a web browser, you can also connect locally with the browser on that device.

Windows Device Portal is available on each device family, but features and setup vary based on each device's requirements. This article provides a general description of Device Portal and links to articles with more specific information for each device family.

The functionality of the Windows Device Portal is implemented with REST APIs that you can use directly to access data and control your device programmatically.

Setup

Each device has specific instructions for connecting to Device Portal, but each requires these general steps:

  1. Enable Developer Mode and Device Portal on your device (configured in the Settings app).
  2. Connect your device and PC through a local network or with USB.
  3. Navigate to the Device Portal page in your browser. This table shows the ports and protocols used by each device family.
Device family On by default? HTTP HTTPS USB
HoloLens Yes, in Dev Mode 80 (default) 443 (default) http://127.0.0.1:10080
IoT Yes, in Dev Mode 8080 Enable via regkey N/A
Xbox Enable inside Dev Mode Disabled 11443 N/A
Desktop Enable inside Dev Mode 50080* 50043* N/A
Phone Enable inside Dev Mode 80 443 http://127.0.0.1:10080

* This is not always the case, as Device Portal on desktop claims ports in the ephemeral range (>50,000) to prevent collisions with existing port claims on the device. To learn more, see the Port Settings section for desktop.

For device-specific setup instructions, see:

Features

Toolbar and navigation

The toolbar at the top of the page provides access to commonly used features.

  • Power: Access power options.
    • Shutdown: Turns off the device.
    • Restart: Cycles power on the device.
  • Help: Opens the help page.

Use the links in the navigation pane along the left side of the page to navigate to the available management and monitoring tools for your device.

Tools that are common across device families are described here. Other options might be available depending on the device. For more info, see the specific page for your device type.

Apps manager

The Apps manager provides install/uninstall and management functionality for app packages and bundles on the host device.

Device Portal Apps manager page

  • Installed apps: Use the dropdown menu to remove or start apps that are installed on the device. Install a new app by clicking Add. This initiates the installation UX to deploy packaged apps from local, network or web hosts and register loose files from network shares.
  • Running apps: Get information about the apps that are currently running and close them as necessary.

Install an app

  1. When you've created an app package, you can remotely install it onto your device. After you build it in Visual Studio, an output folder is generated. App install
  2. In the Device Portal's Apps manager section, click Add and select Install app package from local storage.
  3. Click browse and find your app package.
  4. Click browse and find the certificate (.cer) file (not required on all devices.)
  5. Check the respective boxes if you want to install optional or framework packages along with the app installation. If you have more than one, add each one individually.
  6. Click Next to move to the next step and Install to initiate the installation.

Uninstall an app

  1. Ensure that your app is not running.
  2. If it is, go to Running apps and close it. If you attempt to uninstall while the app is running, it will cause issues when you attempt to reinstall the app.
  3. Select the app from the dropdown and click Remove.

Running processes

This page shows details about processes currently running on the host device. This includes both apps and system processes. On some platforms (Desktop, IoT, and HoloLens), you can terminate processes.

Device Portal Running processes page

File explorer

This page allows you to view and manipulate files stored by any sideloaded apps. See the Using the App File Explorer blog post to learn more about the File explorer and how to use it.

Device Portal File explorer page

Performance

The Performance page shows real-time graphs of system diagnostic info like power usage, frame rate, and CPU load.

These are the available metrics:

  • CPU: Percent of total available CPU utilization
  • Memory: Total, in use, available, committed, paged, and non-paged
  • I/O: Read and write data quantities
  • Network: Received and sent data
  • GPU: Percent of total available GPU engine utilization

Device Portal Performance page

Event Tracing for Windows (ETW) logging

The ETW logging page manages real-time Event Tracing for Windows (ETW) information on the device.

Device Portal ETW logging page

Check Hide providers to show the Events list only.

  • Registered providers: Select the event provider and the tracing level. The tracing level is one of these values:

    1. Abnormal exit or termination
    2. Severe errors
    3. Warnings
    4. Non-error warnings
    5. Detailed trace

    Click or tap Enable to start tracing. The provider is added to the Enabled Providers dropdown.

  • Custom providers: Select a custom ETW provider and the tracing level. Identify the provider by its GUID. Do not include brackets in the GUID.
  • Enabled providers: This lists the enabled providers. Select a provider from the dropdown and click or tap Disable to stop tracing. Click or tap Stop all to suspend all tracing.
  • Providers history: This shows the ETW providers that were enabled during the current session. Click or tap Enable to activate a provider that was disabled. Click or tap Clear to clear the history.
  • Filters / Events: The Events section lists ETW events from the selected providers in table format. The table is updated in real time. Use the Filters menu to set up custom filters for which events will be displayed. Click the Clear button to delete all ETW events from the table. This does not disable any providers. You can click Save to file to export the currently collected ETW events to a local CSV file.

For more details on using ETW logging, see the Use Device Portal to view debug logs blog post.

Performance tracing

The Performance tracing page allows you for view the Windows Performance Recorder (WPR) traces from the host device.

Device Portal performance tracing page

  • Available profiles: Select the WPR profile from the dropdown, and click or tap Start to start tracing.
  • Custom profiles: Click or tap Browse to choose a WPR profile from your PC. Click or tap Upload and start to start tracing.

To stop the trace, click Stop. Stay on this page until the trace file (.ETL) has finished downloading.

Captured .ETL files can be opened for analysis in the Windows Performance Analyzer.

Device manager

The Device manager page enumerates all peripherals attached to your device. You can click the settings icons to view the properties of each.

Device Portal Device manager page

Networking

The Networking page manages network connections on the device. Unless you are connected to Device Portal through USB, changing these settings will likely disconnect you from Device Portal.

  • Available networks: Shows the WiFi networks available to the device. Clicking or tapping on a network will allow you to connect to it and supply a passkey if needed. Device Portal does not yet support Enterprise Authentication. You can also use the Profiles dropdown to attempt to connect to any of the WiFi profiles known to the device.
  • IP configuration: Shows address information about each of the host device's network ports.

Device Portal Networking page

Service features and notes

DNS-SD

Device Portal advertises its presence on the local network using DNS-SD. All Device Portal instances, regardless of their device type, advertise under "WDP._wdp._tcp.local". The TXT records for the service instance provide the following:

Key Type Description
S int Secure port for Device Portal. If 0 (zero), Device Portal is not listening for HTTPS connections.
D string Type of device. This will be in the format "Windows.*", e.g. Windows.Xbox or Windows.Desktop
A string Device architecture. This will be ARM, x86, or AMD64.
T null-character delineated list of strings User-applied tags for the device. See the Tags REST API for how to use this. List is double-null terminated.

Connecting on the HTTPS port is suggested, as not all devices are listening on the HTTP port advertised by the DNS-SD record.

CSRF Protection and Scripting

In order to protect against CSRF attacks, a unique token is required on all non-GET requests. This token, the X-CSRF-Token request header, is derived from a session cookie, CSRF-Token. In the Device Portal web UI, the CSRF-Token cookie is copied into the X-CSRF-Token header on each request.

Important

This protection prevents usages of the REST APIs from a standalone client (such as command-line utilities). This can be solved in 3 ways:

  • Use an "auto-" username. Clients that prepend "auto-" to their username will bypass CSRF protection. It is important that this username not be used to log in to Device Portal through the browser, as it will open up the service to CSRF attacks. Example: If Device Portal's username is "admin", curl -u auto-admin:password <args> should be used to bypass CSRF protection.
  • Implement the cookie-to-header scheme in the client. This requires a GET request to establish the session cookie, and then the inclusion of both the header and the cookie on all subsequent requests.
  • Disable authentication and use HTTP. CSRF protection only applies to HTTPS endpoints, so connections on HTTP endpoints will not need to do either of the above.

Cross-Site WebSocket Hijacking (CSWSH) protection

To protect against CSWSH attacks, all clients opening a WebSocket connection to Device Portal must also provide an Origin header that matches the Host header. This proves to Device Portal that the request comes either from the Device Portal UI or a valid client application. Without the Origin header your request will be rejected.