Windows Device Portal overview
The Windows Device Portal (WDP) is a web server included with Windows devices that lets you configure and manage the settings for the device over a network or USB connection (local connections are also supported on devices with a web browser).
WDP also provides advanced diagnostic tools for troubleshooting and viewing the real-time performance of your Windows device.
WDP functionality is programmatically exposed through a collection of REST APIs.
This article provides a general description of the Windows Device Portal and includes links to articles with more specific information on each Windows device family.
Note
A device family identifies the APIs, system characteristics, and behaviors that you can expect across a class of devices.
Setup
Each device family provides a version of the WDP, but features and setup vary based on the requirements of a device.
These are the basic steps for all devices.
Enable Developer Mode and Device Portal on your device (Settings -> Privacy & security -> For developers).
Connect your device and PC through a local network or with USB.
Navigate to the Device Portal page in your browser. This table shows the ports and protocols used by each device family.
The following table includes device-specific details for the WDP.
Note
Windows Mixed Reality runs on regular desktop, so it’s the same portal as Desktop.
| Device family | On by default? | HTTP | HTTPS | USB | Instructions |
|---|---|---|---|---|---|
| Desktop and IoT Enterprise | Enable inside Dev Mode | 50080* | 50043* | N/A | Device Portal for Desktop or IoT Enterprise device |
| Xbox | Enable inside Dev Mode | Disabled | 11443 | N/A | Device Portal for Xbox |
| HoloLens | Yes, in Dev Mode | 80 (default) | 443 (default) | http://127.0.0.1:10080 |
Device Portal for HoloLens |
| IoT Core | Yes, in Dev Mode | 8080 | Enable via regkey | N/A | Device Portal for IoT Core |
| Phone | Enable inside Dev Mode | 80 | 443 | http://127.0.0.1:10080 |
Device Portal for Mobile |
* 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 Registry-based configuration section in Windows Device Portal for Desktop.
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.
- Deploy apps: Deploy packaged apps from local, network, or web hosts and register loose files from network shares.
- Installed apps: Use the dropdown menu to remove or start apps that are installed on the device.
- Running apps: Get information about the apps that are currently running and close them as necessary.
Install (sideload) an app
You can sideload apps during development using Windows Device Portal:
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.
In Windows Device Portal, navigate to the Apps manager page.
In the Deploy apps section, select Local Storage.
Under Select the application package, select Choose File and browse to the app package that you want to sideload.
Under Select certificate file (.cer) used to sign app package, select Choose File and browse to the certificate associated with that app package.
Check the respective boxes if you want to install optional or framework packages along with the app installation, and select Next to choose them.
Select Install to initiate the installation.
If the device is running Windows 10 in S mode, and it is the first time that the given certificate has been installed on the device, restart the device.
Install a certificate
Alternatively, you can install the certificate via Windows Device Portal, and install the app through other means:
In Windows Device Portal, navigate to the Apps manager page.
In the Deploy apps section, select Install Certificate.
Under Select certificate file (.cer) used to sign an app package, select Choose File and browse to the certificate associated with the app package that you want to sideload.
Select Install to initiate the installation.
If the device is running Windows 10 in S mode, and it is the first time that the given certificate has been installed on the device, restart the device.
Uninstall an app
- Ensure that your app is not running.
- 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.
- 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.
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.
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
Event Tracing for Windows (ETW) logging
The ETW logging page manages real-time Event Tracing for Windows (ETW) information on the device.
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:
- Abnormal exit or termination
- Severe errors
- Warnings
- Non-error warnings
- 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 Windows Performance Toolkit includes the Performance tracing page, which allows you for view the Windows Performance Recorder (WPR) traces from the host device.
- 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.
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.
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.*", for example, 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.