Windows Setup doc; offer 10x perf improvement (#58259)

* Windows Setup; document 10x perf improvement

docs/docsite/rst/user_guide/windows.rst

@@ -17,4 +17,5 @@ some of the differences between Linux/Unix hosts and hosts running Windows.
    windows_winrm
    windows_usage
    windows_dsc
+   windows_performance
    windows_faq

docs/docsite/rst/user_guide/windows_performance.rst

@@ -0,0 +1,61 @@
+.. _windows_performance:
+
+Windows performance
+===================
+This document offers some performance optimizations you might like to apply to
+your Windows hosts to speed them up specifically in the context of using Ansible
+with them, and generally.
+
+Optimise PowerShell performance to reduce Ansible task overhead
+---------------------------------------------------------------
+To speed up the startup of PowerShell by around 10x, run the following
+PowerShell snippet in an Administrator session. Expect it to take tens of
+seconds.
+
+.. note::
+
+    If native images have already been created by the ngen task or service, you
+    will observe no difference in performance (but this snippet will at that
+    point execute faster than otherwise).
+
+.. code-block:: powershell
+
+    function Optimize-PowershellAssemblies {
+      # NGEN powershell assembly, improves startup time of powershell by 10x
+      $old_path = $env:path
+      try {
+        $env:path = [Runtime.InteropServices.RuntimeEnvironment]::GetRuntimeDirectory()
+        [AppDomain]::CurrentDomain.GetAssemblies() | % {
+          if (! $_.location) {continue}
+          $Name = Split-Path $_.location -leaf
+          if ($Name.startswith("Microsoft.PowerShell.")) {
+            Write-Progress -Activity "Native Image Installation" -Status "$name"
+            ngen install $_.location | % {"`t$_"}
+          }
+        }
+      } finally {
+        $env:path = $old_path
+      }
+    }
+    Optimize-PowershellAssemblies
+
+PowerShell is used by every Windows Ansible module. This optimisation reduces
+the time PowerShell takes to start up, removing that overhead from every invocation.
+
+This snippet uses `the native image generator, ngen <https://docs.microsoft.com/en-us/dotnet/framework/tools/ngen-exe-native-image-generator#WhenToUse>`_
+to pre-emptively create native images for the assemblies that PowerShell relies on.
+
+Fix high-CPU-on-boot for VMs/cloud instances
+--------------------------------------------
+If you are creating golden images to spawn instances from, you can avoid a disruptive
+high CPU task near startup via `processing the ngen queue <https://docs.microsoft.com/en-us/dotnet/framework/tools/ngen-exe-native-image-generator#native-image-service>`_
+within your golden image creation, if you know the CPU types won't change between
+golden image build process and runtime.
+
+Place the following near the end of your playbook, bearing in mind the factors that can cause native images to be invalidated (`see MSDN <https://docs.microsoft.com/en-us/dotnet/framework/tools/ngen-exe-native-image-generator#native-images-and-jit-compilation>`_).
+
+.. code-block:: yaml
+
+    - name: generate native .NET images for CPU
+      win_dotnet_ngen:
+

lib/ansible/modules/windows/win_dotnet_ngen.py

@@ -20,6 +20,7 @@ description:
     - After .NET framework is installed/updated, Windows will probably want to recompile things to optimise for the host.
     - This happens via scheduled task, usually at some inopportune time.
     - This module allows you to run this task on your own schedule, so you incur the CPU hit at some more convenient and controlled time.
+    - U(https://docs.microsoft.com/en-us/dotnet/framework/tools/ngen-exe-native-image-generator#native-image-service)
     - U(http://blogs.msdn.com/b/dotnet/archive/2013/08/06/wondering-why-mscorsvw-exe-has-high-cpu-usage-you-can-speed-it-up.aspx)
 options: {}
 notes: