Merge pull request #1 from Microsoft/master

1. Fork the repository. Click on the "Fork" button on the top right of the page and follow the flow.

2. If your work needs more time, the consider branching off of master else just code in your fork.

3. Ensure your changes check for the appropriate device families (ex: Windows Desktop and IoT only).

4. Implement one or more tests to ensure the change works on the target platform(s).

5. Make small and frequent commits that include tests which could be a unity scene showing usage of your feature.

6. Make sure that all existing tests continue to pass.

7. Ensure you update the [README](https://github.com/Microsoft/WindowsDevicePortalWrapper/blob/master/README.md) with additional documentation as needed.

4. Implement one or more [tests](https://github.com/Microsoft/WindowsDevicePortalWrapper/blob/master/Testing.md) to ensure the change works on the target platform(s).

5. Make small and frequent commits that include [tests](https://github.com/Microsoft/WindowsDevicePortalWrapper/blob/master/Testing.md) against mock data or manual tests which can be run against real devices.

6. Make sure that all existing [tests](https://github.com/Microsoft/WindowsDevicePortalWrapper/blob/master/Testing.md) continue to pass.

# Updating code documentation

The Windows Device Portal Wrapper uses [Doxygen](http://www.stack.nl/~dimitri/doxygen/download.html) to automatically generate code documentation directly from the source code. Any changes to existing or new classes or methods should also update the documentation.

1. Download and install [Doxygen](http://www.stack.nl/~dimitri/doxygen/download.html) (our docs are generated using version 1.8.11).

2. Open a CMD prompt and navigate to your git repository's root directory.

3. Run '\<Doxygen Install Location\>\\doxygen.exe DocConfig.txt'. This will update the files under the html folder relative to the root directory.

4. Include the updated files with your PR.

# Run StyleCop

---

---

## Source layout

The Windows Device Portal Wrapper source code has the following layout.

### \

The project root folder contains the Visual Studio 2015 solution (.sln) and all sub-folders that make up the project.

#### WindowsDevicePortalWrapper.sln

#### License.txt

#### CONTRIBUTING.md

#### README.md

---

### \WindowsDevicePortalWrapper.Shared

The WindowsDevicePortalWrapper.Shared folder is a code only project that contains platform independent code for accessing the Windows Device Portal. Large methods use conditional compilation blocks for platform specific code. Small methods requiring platform specific code are duplicated into source files residing in the folders containing that platform's .csproj file.

#### DevicePortal.cs

The root file for the Microsoft.Tools.WindowsDevicePortal.DevicePortal class.

Events:

(All events are part of the DevicePortal class)

* ConnectionStatus

Properties:

(All properties are part of the DevicePortal class)

* Address

* ConnectionHttpStatusCode

* DeviceFamily

* OperatingSystemVersion

* Platform

* PlatformName

Methods:

(All methods are part of the DevicePortal class)

* DevicePortal()

* Connect()

* SendConnectionStatus()

#### Utilities.cs

A static class providing utility functions utilized throughout the Windows Device Portal Wrapper project.

Methods:

(All methods are part of the Utilities class)

* BuildEndpoint()

* Hex64Encode()

---

### \WindowsDevicePortalWrapper.Shared\Core

The Core sub-folder contains the implementation of methods supported by all Windows Device Portal platforms.

#### AppDeployment.cs

Events:

(All events are part of the DevicePortal class)

* AppInstallStatus

Methods:

(All methods are part of the DevicePortal class)

* CopyInstallationFileToStream()

* CreateAppInstallEndpointAndBoundaryString()

* GetInstalledAppPackages()

* InstallApplication()

* UninstallApplication()

* SendAppInstallStats()

Defines the data contract used by the application deployment methods.

#### AppFileExplorer.cs

#### DeviceManager.cs

#### Dns-Sd.cs

#### DumpCollection.cs

#### Etw.cs

#### Networking.cs

#### OsInformation.cs

#### PerformanceData.cs

#### Power.cs

#### RemoteControl.cs

#### TaskManager.cs

#### WiFiManagement.cs

#### WindowsErrorReporting.cs

#### WindowsPerformanceRecorder.cs

To start contributing, see [Contributing](https://github.com/Microsoft/WindowsDevicePortalWrapper/blob/master/CONTRIBUTING.md)

---

### \WindowsDevicePortalWrapper.Shared\Events

The Interfaces sub-folder contains events defined by the Windows Device Portal Wrapper and their associated event arg classes.

#### ApplicationInstallStatus.cs

#### ConnectionStatus.cs

#### WebSocketMessageReceivedEventArgs.cs

---

### \WindowsDevicePortalWrapper.Shared\Exceptions

The Interfaces sub-folder contains the exceptions defined by the Windows Device Portal Wrapper.

#### DevicePortalException.cs

For source code documentation, open \<local repository\>\\html\\index.html in a browser.

---

### \WindowsDevicePortalWrapper.Shared\HoloLens

The HoloLens sub-folder contains the implmentation of HoloLens specific Windows Device Portal methods.

#### HolographicOs.cs

#### HolographicPerception.cs

#### HolographicThermal.cs

#### MixedRealityCapture.cs

#### PerceptionSimulationPlayback.cs

#### PerceptionSimulationRecording.cs

---

### \WindowsDevicePortalWrapper.Shared\HttpRest

The HttpRest sub-folder contains methods used to send requests and receive data from the Windows Device Portal's REST API.

#### CsrfToken.cs

Provides CSRF token management support.

Methods:

(All methods are part of the DevicePortal class)

* ApplyCsrfToken()

Sets the CSRF token header on the HTTP request.

* RetrieveCsrfToken

Gets the CSRF token header value from the HTTP response and stores it for future use.

#### RestDelete.cs

Methods:

(All methods are part of the DevicePortal class)

* Delete()

#### RestGet.cs

Methods:

(All methods are part of the DevicePortal class)

* Get<T>()

#### RestPost.cs

Methods:

(All methods are part of the DevicePortal class)

* Post()

#### RestPut.cs

Methods:

(All methods are part of the DevicePortal class)

* Put()

* Put<T>()

#### WebSocket.cs

---

### \WindowsDevicePortalWrapper.Shared\Interfaces

The Interfaces sub-folder contains the definitions of interfaces defined by the Windows Device Portal Wrapper.

#### IDevicePortalConnection.cs

Defines the IDevicePortalConnection interface, for which an implementation must be provided by tools which consume the Windows Device Portal Wrapper.

---

### \WindowsDevicePortalWrapper.Shared\Xbox

The Xbox sub-folder contains the implmentation of Xbox One specific Windows Device Portal methods.

#### SmbShare.cs

#### UserManagement.cs

#### XboxAppDeployment.cs

---

### \WindowsDevicePortalWrapper

The WindowsDevicePortalWrapper folder contains the references and files required to build a the Windows Device Portal Wrapper project targeting version 4.5.2 of the .net framework.

#### CertificateHandling.cs

Methods:

(All methods are part of the DevicePortal class)

* GetDeviceCertificate()

* ServerCertificateValidation()

* ServerCertificateNonValidation()

---

### \WindowsDevicePortalWrapper\Core

The WindowsDevicePortalWrapper\Core folder contains the .net 4.5.2 specific Core Device Portal API functionality.

#### AppDeployment.cs

Methods:

(All methods are part of the DevicePortal class)

* GetInstallStatus()

---

### \WindowsDevicePortalWrapper\HttpRest

The WindowsDevicePortalWrapper\Core folder contains the .net 4.5.2 specific HTTP REST functionality.

#### RestDelete.cs

Methods:

(All methods are part of the DevicePortal class)

* Delete(Uri)

#### RestGet.cs

Methods:

(All methods are part of the DevicePortal class)

* Get(Uri)

#### RestPost.cs

Methods:

(All methods are part of the DevicePortal class)

* Post(Uri)

#### RestPut.cs

Methods:

(All methods are part of the DevicePortal class)

* Put(Uri)

---

### \WindowsDevicePortalWrapper.UniversalWindows

The WindowsDevicePortalWrapper.UnversalWindows folder contains the references and files required to build a the Windows Device Portal Wrapper project targeting the Windows 10 Universal Windows Platform.

#### CertificateHandling.cs

Methods:

(All methods are part of the DevicePortal class)

* GetDeviceCertificate()

* SetDeviceCertificate()

---

### \WindowsDevicePortalWrapper.UniversalWindows\Core

The WindowsDevicePortalWrapper\Core folder contains the Universal Windows Platform specific Core Device Portal API functionality.

#### AppDeployment.cs

Methods:

(All methods are part of the DevicePortal class)

* GetInstallStatus()

---

### \WindowsDevicePortalWrapper.UniversalWindows\HttpRest

The WindowsDevicePortalWrapper\Core folder contains the Universal Windows Platform specific HTTP REST functionality.

#### RestDelete.cs

Methods:

(All methods are part of the DevicePortal class)

* Delete(Uri)

#### RestGet.cs

Methods:

(All methods are part of the DevicePortal class)

* Get(Uri)

#### RestPost.cs

Methods:

(All methods are part of the DevicePortal class)

* Post(Uri)

#### RestPut.cs

Methods:

(All methods are part of the DevicePortal class)

* Put(Uri)

---

For documentation on the WDP REST endpoints which the project wraps, see the following references.

### Core methods

Please see the [Windows Device Portal Core API reference](https://msdn.microsoft.com/en-us/windows/uwp/debug-test-perf/device-portal-api-core) for additional information.

[Windows Device Portal Core API reference](https://msdn.microsoft.com/en-us/windows/uwp/debug-test-perf/device-portal-api-core)

---

### HoloLens specific methods

Please see the [HoloLens Device Portal API reference](https://developer.microsoft.com/en-us/windows/holographic/device_portal_api_reference) for additional information.

[HoloLens Device Portal API reference](https://developer.microsoft.com/en-us/windows/holographic/device_portal_api_reference)

---

### Xbox One specific methods

Please see the [Xbox Device Portal API reference](https://msdn.microsoft.com/en-us/windows/uwp/xbox-apps/reference) for additional information.

[Xbox Device Portal API reference](https://msdn.microsoft.com/en-us/windows/uwp/xbox-apps/reference)

---

# Running Tests

There are two types of tests for excercising the wrapper library. 

First, unit tests built against mock responses should be run before every Pull Request. Use Run All via the Test Explorer in Visual Studio prior to submitting any Pull Requests. You can also configure Visual Studio to automatically run the tests after each build of the solution via Test Settings in the Test menu.

<br>

  ![runalltests](https://cloud.githubusercontent.com/assets/19478513/17338380/16900018-589c-11e6-87a6-8091d62ce399.png)

Second, manual or semi-automated tests can also be run on a per-device basis via the device specific test apps. See the following for information on running these test apps:

For Xbox One: [Using the Xbox Test App.](https://github.com/Microsoft/WindowsDevicePortalWrapper/blob/master/XboxWDPDriver.md)

# Writing Tests

Windows Device Portal Wrapper (WDPW) tests are run against mock data so that a windows device is not required to run the tests.

1.	Create a Unit Test class in the Unit Test Project

  ![addunittest](https://cloud.githubusercontent.com/assets/1520739/17310088/225af006-57f7-11e6-834c-7735b7270d85.png)

2.	Have the test class inherit from the BaseTests class which will automatically establish your mock connection (the constructor and TestContext can be removed)

  ```c#

 /// <summary>

  /// Summary description for DemoTest

  /// </summary>

  [TestClass]

  public class DemoTest : BaseTests

  {

  }

  ```

  a. If you are writing a device specific version test then override the PlatformType, the FriendlyOperatingSystemVersion used to specify where mock files are stored/named, and the OperatingSystemVersion to be used when validating the OS’s actual version number.

  ```c#

 /// <summary>

/// Gets the Platform type these tests are targeting.

/// </summary>

protected override DevicePortalPlatforms PlatformType

{

  get { return DevicePortalPlatforms.XboxOne;}

}

/// <summary>

/// Gets the friendly OS Version these tests are targeting.

/// </summary>

protected override string FriendlyOperatingSystemVersion

{

  get { return "rs1_xbox_rel_1608";}

}

/// <summary>

/// Gets the OS Version these tests are targeting.

/// </summary>

protected override string OperatingSystemVersion

{

  get { return "14385_1002_amd64fre_rs1_xbox_rel_1608_160709_1700";}

}

  ```

3.	Define void methods with no parameters tagged with “testMethod” for each test case you want to run

  ```c#

  [TestMethod]

  public void TestMethod1()

  {

    //

    // TODO: Add test logic here

    //

  }

  ```

4. Each test should start with a call to TestHelpers.MockHttpResponder.AddMockResponse to prepare a mock response for a specified endpoint in one of three ways:

  a. Default mock

  Use mock data from the MockData\Defaults\ \<endpoint\>\_Default.dat file.

  ```c#

  TestHelpers.MockHttpResponder.AddMockResponse(DevicePortal.MachineNameApi, HttpMethods.Get);

  ```

  b. Version specific mock

  Use mock data from the MockData\ \<platform>\ \<friendly OS version\>\ \<endpoint\>\_\<platform\>\_\<friendly OS version\>.dat file

  ```c#

  TestHelpers.MockHttpResponder.AddMockResponse(DevicePortal.KnownFoldersApi, this.PlatformType, this.FriendlyOperatingSystemVersion, HttpMethods.Get);

  ```

  c. Provided response

  Use a response object as a mock.

  ```c#

  TestHelpers.MockHttpResponder.AddMockResponse(DevicePortal.GetFilesApi, response, HttpMethods.Get);

  ```

5. Have the test methods use TestHelpers.Portal to call DevicePortal methods and then Assert methods to validate results

  ```c#

  Task<string> getNameTask = TestHelpers.Portal.GetDeviceName();

  getNameTask.Wait();

  Assert.IsNotNull(TestHelpers.Portal.OperatingSystemVersion);

  ```

6. After building the test right click on it in the test explorer and select “Debug Selected Tests” to be able to hit selected break points as it runs.

  ![debugselectedtests](https://cloud.githubusercontent.com/assets/1520739/17310093/27a33636-57f7-11e6-8cab-45620c167dcf.png)

# Collecting Data for Tests

## Using MockDataGenerator.exe to Generate Mock Data

MockDataGenerator.exe, from the MockDataGenerator project, is used to target a WDP instance to create mock data.

### MockDataGenerator Parameters

| Parameter               | Purpose                                        |

|-------------------------|------------------------------------------------|

| /Address                | URL for device (eg. https://10.0.0.1:11443)    |

| /User                   | WDP username                                   |

| /Pwd                    | WDP password                                   |

| /Endpoint               | API to call (default is all endoints in program.cs)   |

| /Method                 | HTTP method to use (default is GET)            |

| /Directory              | Directory to save mock data file(s) (default is .\MockData) |

### MockDataGenerator File Name Format

All mock data is saved as files in the \<endpoint\>\_\<platform\>\_\<friendly OS version\>.dat format, such as api_os_devicefamily_XboxOne_rs1_xbox_rel_1608.dat. 

All file names are pre-pended with the HTTP method except for GET (as it is the default). Hence the file name for calling the System Performance API with GET is api_resourcemanager_systemperf_XboxOne_rs1_xbox_rel_1608.dat but calling the WebSocket is WebSocket_api_resourcemanager_systemperf_XboxOne_rs1_xbox_rel_1608.dat.

### MockDataGenerator Examples

All examples connect to 10.0.0.1:11443 with username TestUser and password SuperSecret.

* Generate all mocks specified in the Program.cs Endpoints array and store them in .\MockData

  ```shell

  MockDataGenerator.exe  /ip: 10.0.0.1:11443 /user:TestUser /pwd:SuperSecret

  ```

* Generate mock for the device family API and store it in .\MockData

  ```shell

  MockDataGenerator.exe  /ip: 10.0.0.1:11443 /user:TestUser /pwd:SuperSecret /endpoint:api/os/devicefamily

  ```

  or

  ```shell

  MockDataGenerator.exe  /ip: 10.0.0.1:11443 /user:TestUser /pwd:SuperSecret /endpoint:api/os/devicefamily /method:Get

  ```

* Generate mock for the System Performance API web socket connection and store it in .\MockData

  ```shell

  MockDataGenerator.exe  /ip: 10.0.0.1:11443/user:TestUser /pwd:SuperSecret /endpoint:api/resourcemanager/systemperf /method:WebSocket

  ```

  ## Adding Mock Data to the Solution

  1. Mock data should be added to the UnitTestProject in the MockData directory. 

    * Default mock data should be added to the MockData\Defaults directory.

      ![defaultmocks](https://cloud.githubusercontent.com/assets/1520739/17312218/ff62b160-5805-11e6-92f9-0934fc50b961.png)

    * Device-version mock data should be added to the MockData<Device\>\ \<Friendly OS Version\> directory with the Friendly OS Version parsed from the mock data’s file name.

      ![platformspecificmocks](https://cloud.githubusercontent.com/assets/1520739/17312269/5248edf4-5806-11e6-833e-cb2445ffc0f1.png)

  2. In the properties view the mock data files should have their “Copy to Output Directory” property marked as “Copy if newer.” If this is not done then the tests will be unable to find the files.

    ![copytooutputdirectory](https://cloud.githubusercontent.com/assets/1520739/17312271/55911450-5806-11e6-9616-eaf7de842121.png)

    <FileAlignment>512</FileAlignment>

    <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>

    <StyleCopTreatErrorsAsWarnings>True</StyleCopTreatErrorsAsWarnings>

    <StyleCopTargetsDir>$(registry:HKEY_LOCAL_MACHINE\Software\CodePlex\StyleCop@TargetsDir)</StyleCopTargetsDir>

  </PropertyGroup>

  <PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">

    <PlatformTarget>AnyCPU</PlatformTarget>

    <Reference Include="System.Xml" />

  </ItemGroup>

  <ItemGroup>

    <Compile Include="DevicePortalConnection.cs" />

    <Compile Include="ParameterHelper.cs" />

    <Compile Include="Program.cs" />

    <Compile Include="Properties\AssemblyInfo.cs" />

    </ProjectReference>

  </ItemGroup>

  <Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />

  <Import Project="$(ProgramFiles)\MSBuild\StyleCop\v4.7\StyleCop.targets" />

  <Import Project="$(StyleCopTargetsDir)StyleCop.targets" Condition="'$(StyleCopTargetsDir)' != ''"/>

  <!-- To modify your build process, add your task inside one of the targets below and uncomment it. 

       Other similar extension points exist, see Microsoft.Common.targets.

  <Target Name="BeforeBuild">