From 7d71017cd7e4d0b270a94b55d65ae265597e35e9 Mon Sep 17 00:00:00 2001
From: SpaceIm <30052553+SpaceIm@users.noreply.github.com>
Date: Sun, 1 Jan 2023 17:47:59 +0100
Subject: [PATCH] document new feature of MSBuild

MSBuild is now able to automatically consume root props files generated by MSBuildToolchain and MSBuildDeps.
Moreover toolset attribute has been added.
---
 reference/conanfile/tools/microsoft.rst | 28 +++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/reference/conanfile/tools/microsoft.rst b/reference/conanfile/tools/microsoft.rst
index 1d8d6cf2ee2..d2e3045a802 100644
--- a/reference/conanfile/tools/microsoft.rst
+++ b/reference/conanfile/tools/microsoft.rst
@@ -289,16 +289,28 @@ Available since: `1.32.0 <https://github.com/conan-io/conan/releases/tag/1.32.0>
 
 The ``MSBuild`` build helper is a wrapper around the command line invocation of MSBuild. It will abstract the
 calls like ``msbuild "MyProject.sln" /p:Configuration=<conf> /p:Platform=<platform>`` into Python method calls.
+This helper externally injects root props files eventually generated by ``MSBuildToolchain`` and ``MSBuildDeps``.
+Therefore manual edition of Visual Studio solutions is not required when you use this helper.
 
-The ``MSBuild`` helper can be used like:
+This helper is intended to be used in the ``build()`` method, to call msbuild command automatically
+when a package is being built directly by Conan (create, install):
 
-.. code:: python
+.. code-block:: python
 
     from conan import ConanFile
-    from conan.tools.microsoft import MSBuild
+    from conan.tools.microsoft import MSBuild, MSBuildDeps, MSBuildToolchain
 
     class App(ConanFile):
         settings = "os", "arch", "compiler", "build_type"
+        requires = "hello/0.1"
+        options = {"shared": [True, False], "fPIC": [True, False]}
+        default_options = {"shared": False, "fPIC": True}
+
+        def generate(self):
+            tc = MSBuildToolchain(self)
+            tc.generate()
+            deps = MSBuildDeps(self)
+            deps.generate()
 
         def build(self):
             msbuild = MSBuild(self)
@@ -308,7 +320,7 @@ The ``MSBuild.build()`` method internally implements a call to ``msbuild`` like:
 
 .. code:: bash
 
-    $ <vcvars-cmd> && msbuild "MyProject.sln" /p:Configuration=<configuration> /p:Platform=<platform> /target=mytarget
+    $ <vcvars-cmd> && msbuild "MyProject.sln" /p:Configuration=<configuration> /p:Platform=<platform> /p:PlatformToolset=<toolset> /p:ForceImportBeforeCppTargets="<props_files>" /target=mytarget
 
 Where:
 
@@ -317,6 +329,11 @@ Where:
   but this will be configurable with ``msbuild.build_type``.
 - ``platform`` is the architecture, a mapping from the ``settings.arch`` to the common 'x86', 'x64', 'ARM', 'ARM64'.
   This is configurable with ``msbuild.platform``.
+- ``toolset`` (since `1.57.0 <https://github.com/conan-io/conan/releases/tag/1.57.0>`_) is the platform toolset.
+  It's ``settings.compiler.toolset`` if defined, otherwise a mapping from ``settings.compiler.version`` to default
+  values like 'v142' or 'v143' etc. This is configurable with ``msbuild.toolset``.
+- ``props_files`` (since `1.57.0 <https://github.com/conan-io/conan/releases/tag/1.57.0>`_) is a semi colon separated
+  list of root props files eventually generated by ``MSBuildToolchain`` and ``MSBuildDeps``.
 - ``targets`` (since `1.52.0 <https://github.com/conan-io/conan/releases/tag/1.52.0>`_) is an optional argument,
   defaults to ``None``, and otherwise it is a list of targets to build
 
@@ -329,6 +346,8 @@ You can customize the following attributes in case you need to change them:
 - **build_type** (default ``settings.build_type``): Value for the ``/p:Configuration``.
 - **platform** (default based on ``settings.arch`` to select one of these values: (``'x86', 'x64', 'ARM', 'ARM64'``):
   Value for the ``/p:Platform``.
+- **toolset** (since `1.57.0 <https://github.com/conan-io/conan/releases/tag/1.57.0>`_) (default ``settings.compiler.toolset``
+  if defined, otherwise based on ``settings.compiler.version``): Value for the ``/p:PlaftormToolset``.
 
 Example:
 
@@ -344,6 +363,7 @@ Example:
             msbuild = MSBuild(self)
             msbuild.build_type = "MyRelease"
             msbuild.platform = "MyPlatform"
+            msbuild.toolset = "MyToolset"
             msbuild.build("MyProject.sln")