Today we’d like to share improvements in the test and debug workflow while developing native applications for Nano Server. The new workflow leverages Nano Server Containers and enhancements in the Visual Studio 2017 Remote Debugger to run in a Container. By putting these two technologies together we can setup a fast and powerful dev, test and debug environment for Nano Server developers on their local machine that avoids the overhead of configuring Nano Server virtual machines and manually copying over test binaries. Let’s dig into the details.

Prerequisites

1. Windows 10 Anniversary Edition (Professional or Enterprise)

   • Ensure Windows Containers feature is enabled per instructions at Windows Container Documentation page

2. Visual Studio 2017 with the following Workloads installed:

   • Universal Windows Platform Development

   • Desktop Development with C++

     A free Community Edition is available from visualstudio.com. Visual Studio 2017 RC can be used to test before the final version of VS2017 is released.

3. Docker for Windows (v1.13.1 or later recommended)

   • After installation, ensure Docker is configured to use Windows Containers as described in this blog post

     Free download available from Docker site

One-time setup

Once all the prerequisites are in place, it is time to perform the first time setup of the Container-based debug environment. To aid the process we have published a helper batchfile and a Dockerfile on our Github tools page.

Here are the steps to get all setup:

1. Install the Nano Server Project Template for Native applications from the Visual Studio Gallery as described in this post , and create a new Nano Server Project. You can also use an existing Nano Server project if you have one created.

2. In the Project settings, configure an Output directory for your project where the build artifacts should be placed.

   

3. Build the Project to ensure the test binaries are successfully built.

4. Download the zip file that contains the helper batchfile and Dockerfile from this location, and extract its contents

5. Execute NanoDockerBuild.bat in the Visual Studio 2017 Developer Command Prompt (as it defines some convenient environment variables), specifying the path to the Output directory as its only parameter. The batchfile performs the following actions:

   • Copies over the OneCore version Remote Debugger binaries and Native application runtime dependencies to a local staging folder from various well known locations in the Visual Studio 2017 install directory

   • Uses the Dockerfile to build a Nano Server Container which includes the Base Container image layered with staged binaries, and specifies the entrypoint of the Container as the Visual Studio Remote Debugger (msvsmon.exe)

   • Runs the Container, mapping the test binaries location from the Container Host into the Container and outputs the ID of the Container that was created (which is also the Container’s hostname). Example execution below:

     C:\ContainerDebug>NanoDockerBuild.cmd c:\nanodebug
     
     Staging Remote Binaries.
     Building container...
     Launching Nano Container...
     
       Nano Server Container started with id: 4c19ad2927da
     
     C:\ContainerDebug>
     

     Once the Base Nano Container image is downloaded for the first time (typically ~10min), on subsequent invocations, this whole sequence should take well under a minute.

6. Configure the Remote Debugger settings as follows:

   • Debugger to launch: Remote Windows Debugger
   • Remote Command: $(TargetFileName)
   • Working Directory: $(OutDir)
   • Remote Server Name: [enter-container-id-from-batchfile-output]

   • Connection: Remote with no authentication

     

1. Network interface index – We use it to target IP address assignments. In the future, we will move to use MAC-address targeting. Occasionally the network interface index will randomly change as Tron battles inner electrons in a race to see which networking card enumerates first.
2. Boot firmware type – The system creates different partitions depending on your firmware type. Most new servers are UEFI.
3. System board information – Validate that you are targeting the right server.
4. Disks and volumes – Choose wisely when selecting a disk partition to format.
5. Devices without a driver! - List devices that have no driver in the Server Core drivers package. Useful!

Accept the License Agreement (Nano Server requires customers have Software Assurance on the device)

Use the USB hardware detection process to see which devices need drivers.   Pro-tip:  Audio drivers are not necessary.

Choose your machine name and password: Join the Active Directory domain: Enable WinRM, Virtual LAN and set static IP addresses: Use the hardware detection USB drive to figure out which network adapter interface index to target. ~ You are ready to create a basic Nano Server image – or continue to advanced settings:

Update Nano Server to the latest revision using a servicing package: Learn about the servicing options for Nano Server.

Emergency Management Services: Get out your serial cable and an RS-232-accessible console. If you have no monitor and no networking is working, this might be your only way into the server. I use putty.exe or my 1998 copy of hyper-terminal.

    Select your USB drive:  

Now you have a bootable USB drive to deploy and you can optionally create a bootable ISO file using the same binaries:

1. VMAccess: Used to change the Administrator password through the Azure interface
2. CustomScript: Used for running arbitrary customization scripts

Azure Service Manager

New-AzureStorageContainer -Name "my-script-container"
Set-AzureStorageBlobContent -File .\RunMe.ps1 -Container "my-script-container"
$vm = Get-AzureVM -Name "my-vm" -ServiceName "my-service-name"
$vm = Set-AzureVMCustomScriptExtension -VM $vm -ContainerName "my-script-container" -FileName "RunMe.ps1" -Run "RunMe.ps1" -Argument "MyArg1 MyArg2"
$vm | Update-AzureVM

Azure Resource Manager

• To run a plain Windows command, without any scripts to download into the extension:

Set-HelperAzureRmCustomScript -ResourceGroupName "testrg001" -VMName "test-vm001" -Location "West US" -NoDownload -FullCommand "echo with No Download" -Verbose

• Set-HelperAzureRmCustomScript can create the storage account and container, if they didn't already exist. To upload the PowerShell script "RunMe.ps1" and an input data file from C:\MyScripts and run the script:

Set-HelperAzureRmCustomScript -ResourceGroupName "testrg001" -VMName "test-vm001" -Location "West US" -Account "my-storage" -NewAccount -Container "my-script-container" -NewContainer -Script "RunMe.ps1", "input.txt" -UploadPath "C:\MyScripts" -Arguments "With new accounts < input.txt" -Verbose

• To run a PowerShell script downloaded from a public resource:

Set-HelperAzureRmCustomScript -ResourceGroupName "testrg001" -VMName "test-vm001" -Location "West US" -ScriptUri "https://raw.githubusercontent.com/My/Dir/master/MyScript.ps1" -Arguments "With URI" -Verbose

• To run a PowerShell script that has been already uploaded to Azure storage:

Set-HelperAzureRmCustomScript -ResourceGroupName "testrg001" -VMName "test-vm001" -Location "West US" -Account "my-storage" -Container "my-script-container" -Script "RunMe.ps1" -Arguments "Without upload" -Verbose

Nano Server Azure Helper

• https://catalog.update.microsoft.com/v7/site/Search.aspx?q=KB3192366
• https://catalog.update.microsoft.com/v7/site/Search.aspx?q=KB3176936

mkdir C:\ServicingPackages_expanded
mkdir C:\ServicingPackages_expanded\KB3176936
mkdir C:\ServicingPackages_expanded\KB3192366
Expand C:\ServicingPackages\KB3176936.msu -F:* C:\ServicingPackages_expanded\KB3176936
Expand C:\ServicingPackages\KB3192366.msu -F:* C:\ServicingPackages_expanded\KB3192366
mkdir C:\ServicingPackages_cabs
copy C:\ServicingPackages_expanded\KB3176936\Windows10.0-KB3176936-x64.cab C:\ServicingPackages_cabs
copy C:\ServicingPackages_expanded\KB3192366\Windows10.0-KB3192366-x64.cab C:\ServicingPackages_cabs

Option 1: Integrate a cumulative update into a new image

New-NanoServerImage -ServicingPackagePath 'C:\ServicingPackages_cabs\Windows10.0-KB3176936-x64.cab', 'C:\ServicingPackages_cabs\Windows10.0-KB3192366-x64.cab' -<other parameters>

Option 2: Integrate a cumulative update into an existing image

Edit-NanoServerImage -ServicingPackagePath 'C:\ServicingPackages_cabs\Windows10.0-KB3176936-x64.cab', 'C:\ServicingPackages_cabs\Windows10.0-KB3192366-x64.cab' -TargetPath .\NanoServer.wim

Option 3: Apply the cumulative update to an existing offline VHD or VHDX

• Using PowerShell

Mount-WindowsImage -ImagePath .\NanoServer.vhdx -Path .\MountDir -Index 1
Add-WindowsPackage -Path .\MountDir -PackagePath  C:\ServicingPackages_cabs
Dismount-WindowsImage -Path .\MountDir -Save

• Using dism.exe

dism.exe /Mount-Image /ImageFile:C:\NanoServer.vhdx /Index:1 /MountDir:C:\MountDir
dism.exe /Image:C:\MountDir /Add-Package /PackagePath:C:\ServicingPackages_cabs
dism.exe /Unmount-Image /MountDir:C:\MountDir /Commit

Option 4: Apply the cumulative update to a running Nano Server

$s = New-PSSession -ComputerName (Read-Host "Enter Nano Server IP address") -Credential (Get-Credential)
Copy-Item -ToSession $s -Path C:\ServicingPackages_cabs -Destination C:\ServicingPackages_cabs -Recurse
Enter-PSSession $s

• Using PowerShell

# Apply the servicing stack update first and then restart
Add-WindowsPackage -Online -PackagePath C:\ServicingPackages_cabs\Windows10.0-KB3176936-x64.cab
Restart-Computer; exit
# After restarting, apply the cumulative update and then restart
Enter-PSSession -ComputerName (Read-Host "Enter Nano Server IP address") -Credential (Get-Credential)
Add-WindowsPackage -Online -PackagePath C:\ServicingPackages_cabs\Windows10.0-KB3192366-x64.cab
Restart-Computer; exit

• Using dism.exe

# Apply the servicing stack update first and then restart
dism.exe /Online /Add-Package /PackagePath:C:\ServicingPackages_cabs\Windows10.0-KB3176936-x64.cab
# After the operation completes successfully and you are prompted to restart,
# it's safe to press Ctrl+C to cancel the pipeline and return to the prompt
Restart-Computer; exit
# After restarting, apply the cumulative update and then restart
Enter-PSSession -ComputerName (Read-Host "Enter Nano Server IP address") -Credential (Get-Credential)
dism.exe /Online /Add-Package /PackagePath:C:\ServicingPackages_cabs\Windows10.0-KB3192366-x64.cab
Restart-Computer; exit

Option 5: Download and install the cumulative update to a running Nano Server

Enter-PSSession -ComputerName (Read-Host "Enter Nano Server IP address") -Credential (Get-Credential)

• Scan for available updates

$ci = New-CimInstance -Namespace root/Microsoft/Windows/WindowsUpdate -ClassName MSFT_WUOperationsSession  
$result = $ci | Invoke-CimMethod -MethodName ScanForUpdates -Arguments @{SearchCriteria="IsInstalled=0";OnlineScan=$true}
$result.Updates

• Install all available updates

$ci = New-CimInstance -Namespace root/Microsoft/Windows/WindowsUpdate -ClassName MSFT_WUOperationsSession
Invoke-CimMethod -InputObject $ci -MethodName ApplyApplicableUpdates
Restart-Computer; exit

• Get a list of installed updates

$ci = New-CimInstance -Namespace root/Microsoft/Windows/WindowsUpdate -ClassName MSFT_WUOperationsSession
$result = $ci | Invoke-CimMethod -MethodName ScanForUpdates -Arguments @{SearchCriteria="IsInstalled=1";OnlineScan=$true}
$result.Updates

Feedback Welcome

Windows Store Client          >>>          Windows Store for Business

Microsoft Edge                    >>>          Internet Explorer 11

Modern Calculator App       >>>          Classic Calculator

• Windows Store for Business, https://www.microsoft.com/business-store
• Windows Servicing Options, https://technet.microsoft.com/en-us/itpro/windows/manage/introduction-to-windows-10-servicing
• Microsoft Edge, https://technet.microsoft.com/en-us/itpro/microsoft-edge/hardware-and-software-requirements

Event tracing and Performance Counters in Windows are powerful mechanisms to debug failures, understand system behavior and improve performance. Nano Server fully supports the Event Tracing for Windows (ETW) framework, but some familiar tools used to manage tracing and performance counters may not yet be available on Nano Server. Happily, Nano Server has inbox tools and cmdlets to accomplish most common performance analysis scenarios. It just may entail using different commands and workflows than you may be used to.

Note that the high-level workflow remains the same as before — low-overhead tracing is performed on the Target (Nano Server) machine, and the resulting trace files and/or logs are post-processed offline on a separate machine using tools like the Windows Performance Analyzer, Message Analyzer, or others. This post primarily focuses on methods to record performance data without requiring any additional tools that are not part of the Nano image.

Refer to the how to copy files to and from Nano Server guide for a refresher on how to transfer files using PowerShell remoting

While it doesn’t cover every scenario, the table below lists the most common performance data collection activities along with a supported way to accomplish them on Nano Server. Click the links in the 2nd column to jump to the section with additional notes on usage.

Query available Event Providers

The Windows Performance Recorder is an inbox tool that be used to get this information as follows:

wpr.exe -providers

Output can be filtered on the type of events that are of interest. Example:

PS C:\> wpr.exe -providers | select-string "Storage"

 595f33ea-d4af-4f4d-b4dd-9dacdd17fc6e : Microsoft-Windows-StorageManagement-WSP-Host
 595f7f52-c90a-4026-a125-8eb5e083f15e : Microsoft-Windows-StorageSpaces-Driver
 69c8ca7e-1adf-472b-ba4c-a0485986b9f6 : Microsoft-Windows-StorageSpaces-SpaceManager
 7e58e69a-e361-4f06-b880-ad2f4b64c944 : Microsoft-Windows-StorageManagement
 88c09888-118d-48fc-8863-e1c6d39ca4df : Microsoft-Windows-StorageManagement-WSP-Spaces

Record traces from a single ETW Provider

The new Event Tracing Management cmdlets can used for this. Below is an example workflow.

Create and start the trace, specifying a file name for storing the events.

PS C:\> New-EtwTraceSession -Name "ExampleTrace" -LocalFilePath c:\etrace.etl

Add a provider GUID to the trace. Use wpr.exe -providers for Provider Name to GUID translation.

PS C:\> wpr.exe -providers | select-string "Kernel-Memory"

d1d93ef7-e1f2-4f45-9943-03d245fe6c00 : Microsoft-Windows-Kernel-Memory

PS C:\> Add-EtwTraceProvider -Guid "{d1d93ef7-e1f2-4f45-9943-03d245fe6c00}" -SessionName "ExampleTrace"

Remove the trace — this stops the trace session, flushing events to the associated log file.

PS C:\> Remove-EtwTraceSession -Name "ExampleTrace"

PS C:\> dir .\etrace.etl

    Directory: C:\

Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        9/14/2016  11:17 AM       16515072 etrace.etl

Note that while the example above shows adding a single trace provider to the session, the Add-EtwTraceProvider cmdlet can be executed multiple times on a trace session with different provider GUIDs to enable tracing from multiple sources. Another alternative is to use wpr.exe profiles described below.

Record traces from multiple ETW Providers

Windows Performance Recorder’s -profiles option enables tracing from multiple providers at the same time. You can choose from a number of builtin profiles like CPU, Network, DiskIO etc.

PS C:\Users\Administrator\Documents> wpr.exe -profiles

Microsoft Windows Performance Recorder Version 10.0.14393 (CoreSystem)
Copyright (c) 2015 Microsoft Corporation. All rights reserved.

        GeneralProfile              First level triage
        CPU                         CPU usage
        DiskIO                      Disk I/O activity
        FileIO                      File I/O activity
        Registry                    Registry I/O activity
        Network                     Networking I/O activity
        Heap                        Heap usage
        Pool                        Pool usage
        VirtualAllocation           VirtualAlloc usage
        Audio                       Audio glitches
        Video                       Video glitches
        Power                       Power usage
        InternetExplorer            Internet Explorer
        EdgeBrowser                 Edge Browser
        Minifilter                  Minifilter I/O activity
        GPU                         GPU activity
        Handle                      Handle usage
        XAMLActivity                XAML activity
        HTMLActivity                HTML activity
        DesktopComposition          Desktop composition activity
        XAMLAppResponsiveness       XAML App Responsiveness analysis
        HTMLResponsiveness          HTML Responsiveness analysis
        ReferenceSet                Reference Set analysis
        ResidentSet                 Resident Set analysis
        XAMLHTMLAppMemoryAnalysis   XAML/HTML application memory analysis
        UTC                         UTC Scenarios
        DotNET                      .NET Activity
        WdfTraceLoggingProvider     WDF Driver Activity

You can also author your own custom profiling configuration to record performance data from exactly the sources you desire. While the process of creating a custom profile is a little involved, it does provide a lot of flexibility and reusability. Detailed guidance on creating custom profiles is at the WPR.exe documentation

Record ETW traces during OS boot

Sometimes there is a need to record performance events early during boot, this is when the cmdlet New-AutologgerConfig comes in handy. Usage is very similar to New-EtwTraceSession cmdlet, just that providers added to the Autologger’s config will only enabled early at next boot. The overall workflow looks like this:

First, create a new Autologger config.

PS C:\> New-AutologgerConfig -Name "BootPnpLog" -LocalFilePath c:\bootpnp.etl

Add a ETW provider to it. In the example below we use the Kernel PnP provider. You invoke Add-EtwTraceProvider again, specifying the same Autologger name but a different GUID to enable boot trace collection from multiple sources.

Add-EtwTraceProvider -Guid "{9c205a39-1250-487d-abd7-e831c6290539}" -AutologgerName BootPnpLog

Note that this does not start an ETW session immediately, but rather configures one to start at next boot. After rebooting, a new ETW session with the Autologger config name is automatically started with the added trace providers enabled. After Nano Server boots up, you can stop the trace session with following command. This will stop the trace session after flushing the logged events to the associated trace file.

PS C:\> Remove-EtwTraceSession -Name BootPnpLog

If you don’t want another trace session to be auto-created at next boot, the Autologger config can be removed.

PS C:\> Remove-AutologgerConfig -Name BootPnpLog

If you need to collect boot and setup traces across a fleet of systems or on a diskless system, consider using Setup and Boot Event Collection — a new feature in Windows Server 2016 that also supports Nano Server targets.

Capture Performance Counter data

Another popular way to gauge how well the OS, application or driver is performing is to use Performance Counters. Usually, this data is consumed via the perfmon GUI. Typeperf.exe is its command-line equivalent that is supported on Nano Server. Below is simple example to illustrate its usage.

Query available Counters; output can be filtered to easily find the ones of interest.

PS C:\> typeperf.exe -q | Select-String "UDPv6"

\UDPv6\Datagrams/sec
\UDPv6\Datagrams Received/sec
\UDPv6\Datagrams No Port/sec
\UDPv6\Datagrams Received Errors
\UDPv6\Datagrams Sent/sec

You can specify the number of times and the interval at which Counter values are snapped. In the example below, Processor Idle Time is snapped 5 times every 3 seconds.

PS C:\> typeperf.exe "\Processor Information(0,0)\% Idle Time" -si 3 -sc 5

"(PDH-CSV 4.0)","\\venkat-ns-g2\Processor Information(0,0)\% Idle Time"
"09/15/2016 09:20:56.002","99.982990"
"09/15/2016 09:20:59.002","99.469634"
"09/15/2016 09:21:02.003","99.990081"
"09/15/2016 09:21:05.003","99.990454"
"09/15/2016 09:21:08.003","99.998577"
Exiting, please wait...
The command completed successfully.

Other command line options allow specifying Counter names of interest in a config file, redirecting output to a log file etc. Refer to the typeperf.exe documentation for details.

If you prefer using the Perfmon GUI for visualization, you can use it remotely with Nano Server targets. When adding Counters to the view, specify the Nano Server target in the computer name instead of the default .

Interact with the Windows Event Log

Nano Server supports the Get-WinEvent cmdlet, which provides powerful Windows Event Log filtering and querying capabilities, both locally as well as on a remote machine. Detailed options and examples are available at the Get-WinEvent documentation page. In the simple example below, we retrieve the Errors noted in the System log during the past two days.

PS C:\> $StartTime = (Get-Date) - (New-TimeSpan -Day 2)
PS C:\> Get-WinEvent -FilterHashTable @{LogName='System'; Level=2; StartTime=$StartTime} | select TimeCreated, Message

TimeCreated Message
----------- -------
9/15/2016 11:31:19 AM Task Scheduler service failed to start Task Compatibility module. Tasks may not be able to reg...
9/15/2016 11:31:16 AM The Virtualization Based Security enablement policy check at phase 6 failed with status: {File...
9/15/2016 11:31:16 AM The Virtualization Based Security enablement policy check at phase 0 failed with status: {File...

Nano Server also supports wevtutil.exe which allows you to retrieve information about event logs and publishers. Refer to wevtutil.exe documentation for more details.

If you love GUIs, we’ve got you covered as well. Web-based Server management tools can be used to remotely manage Nano Server targets and present a Nano Server Event Log via a web browser. Finally, if familiarity trumps all, you can still use the trusty old Event Viewer (eventvwr.msc) to view logs — just open it on a machine with a desktop and point it to a remote Nano Server machine!

Feedback appreciated

That’s it for this post, hope you found it useful. As always, please be generous with your feedback and let us know if you would like to see any scenario or favorite perf tool enabled to make Nano Server even better!

Diskpart.exe

Select disk 0

Clean

Convert GPT

Create partition efi size=100

Format quick FS=FAT32 label="System"

Assign letter="s"

Create partition msr size=128

Create partition primary

Format quick FS=NTFS label="NanoServer"

Assign letter="n"

List volume

Exit

Dism.exe /apply-image /imagefile:.\ServerDatacenterNano.wim /index:1 /applydir:n:\ 

Bcdboot.exe n:\Windows /s s:

Wpeutil.exe reboot