Spec for resolving '-p' in 'dotnet run'

accepted/2021/dotnet-run-resolve-p.md

@@ -0,0 +1,64 @@
+# Syntax for passing `--property` to MSBuild in `dotnet run`
+
+Kathleen Dollard | Status: Draft
+
+The .NET CLI passes all command line arguments that are not explicitly handled through to MSBuild for `dotnet build` and `dotnet publish`. This does not work for `dotnet run` because there are three sets of arguments: 
+
+* CLI arguments for `dotnet run` itself.
+* Arguments for the resulting application, identified by `--` or because they are unrecognized
+* MSBuild arguments, which are not currently supported. 
+
+To support the Xamarin/Maui workloads, we need to pass a property to MSBuild that specifies the device to target. This is being solved by adding a `--property` option to `dotnet run`. This will route to MSBuild as `-p:<delimited list>`.
+
+If an application has `--property` option today, and the option is passed without the `--` indicator, there will be a breaking change because `--property` would not be passed to the application. 
+
+The first syntax would behave differently - the `--property` would pass the `--property` option and argument only to MSBuild, while the second syntax would pass it only to the app: 
+
+```
+dotnet run --property device=deviceName
+dotnet run -- --property device=deviceName
+```
+
+We recommend using -- for clarity and to protect against issues arising if we add additional options to `dotnet run`.
+
+**Note:** A long term approach to managing "device" selection is planned for a later release. In .NET 6 CLI usage of these workloads is expected to just be CI, so this is not considered critical, and the design work is expected to include adjacent problems of specifying containers, and x64 emulation). 
+
+A problem arises in the abbreviation `-p`. It is currently used to specify the `--project` for `dotnet run`. This proposal is a course to change `-p` from meaning `--project` to `--property` in order to be consistent with the similar commands - `dotnet build` and ` dotnet publish`. This proposal balances backward compatibility and consistency with other commands, which we can do because the usages can be distinguished syntactically. 
+
+During a deprecation phase, which will be at least the length of .NET 6, older usage of `-p` as `--project` will be recognized as when there is no trailing colon (`-p:`) and the argument is not legal for MSBuild. Users will receive a warning that the abbreviation is deprecated. 
+
+We will interpret `-p` as `--property` when the argument value is legal MSBuild syntax. Legal MSBuild syntax will be defined as: 
+
+* A comma or semi-colon delimited strings of values in the format <name>=<value> or <name>:<value>. We may simplify this to only checking for the equals - the simplest sufficient check will be used.
+
+If you have any scripts that are using “dotnet run” and process the output you could encounter a break. dotnet run typically doesn’t output anything of its own if there are no errors, so you only get the output of the program that is being run. If you have a script or other program wrapping “dotnet run” and parsing the output, the warning would be unexpected text and may cause a failure.
+
+If you have a project argument that includes an `=` and use the `-p` abbreviation, it will be interpreted as `--property` and passed to MSBuild. 
+
+## Goals
+
+We believe that in the long term `-p` should be used consistently across `dotnet build`, `dotnet publish` and `dotnet run`  because of similarity between these commands. 
+
+### Design
+
+The basic design is described in the opening: 
+
+* `-p` with syntax that is valid for MSBuild properties will be treated as `--property`.
+* Any other usage will be treated as `--project` and will receive a warning that this use is deprecated.
+* At some future point, we may remove `-p` for `--project`.
+
+### Warning text
+
+When -p is used (with no colon) in .NET 6, the following warning will be displayed: 
+
+> Warning NETSDKNNNN: The abbreviation of -p for --project is deprecated. Please use --project.
+
+Where `NNNN` will be replaced with an SDK error code.  In contrast to many other errors and warnings generated by the .NET SDK, this warning will be generated by the .NET CLI parsing code instead of flowing through MSBuild.  So it will not be affected by "warn as error" or "ignore warning" MSBuild settings.
+
+### Implementation notes
+
+We plan to display a deprecation warning for `-p` in .NET 6 and hope to do the additional work to support `-p` as `--property`. However, once the deprecation is in place, we can add the abbreviation in a feature band (quarterly) release. 
+
+
+## Q & A
+