From b1e8eb2a7bddc29fe62f37e58e41dec00691c616 Mon Sep 17 00:00:00 2001 From: Kathleen Dollard Date: Wed, 16 Jun 2021 12:56:20 -0700 Subject: [PATCH 1/5] Added proposal for dotnet run -p --- accepted/2021/dotnet-run-resolve-p.md | 43 +++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) create mode 100644 accepted/2021/dotnet-run-resolve-p.md diff --git a/accepted/2021/dotnet-run-resolve-p.md b/accepted/2021/dotnet-run-resolve-p.md new file mode 100644 index 000000000..45a414b66 --- /dev/null +++ b/accepted/2021/dotnet-run-resolve-p.md @@ -0,0 +1,43 @@ +# Syntax for passing properties 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 `--`. +* 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:. + +**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 identify usage as `--property` when the argument is legal MSBuild syntax. Legal MSBuild syntax will be defined as: + +* A comma or semi-colon delimited strings of values in the format = or : + +## 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`. +* `-p:` will be passed to MSBuild so the an MSBuild error is displayed when the argument is illegal +* Any other usage will be treated as `--project` and will receive a warning that this use is deprecated. +* Usage in the form `-p:` will be allowed but not encouraged or documented. +* In .NET 7, we will add `-p` as an abbreviation equivalent to `p:` +* At some future point, we will remove `-p` for `--project` + +Implementation note +For System.CommandLine, it is expected that `-p` will be treated as `--property` and removed as an abbreviation for `--project`. Special handling will be needed in the `dotnet run` handler. +Warning text +When -p is used (with no colon) in .NET 6, the following warning will be displayed: +“The abbreviation of -p for --project is deprecated. Please use --project.” +Q & A + From 6a183ec189ad94a7ce82fa87068a0ffe82a28efa Mon Sep 17 00:00:00 2001 From: Kathleen Dollard Date: Wed, 16 Jun 2021 13:04:13 -0700 Subject: [PATCH 2/5] Removed file --- accepted/2021/dotnet-run-resolve-p.md | 43 --------------------------- 1 file changed, 43 deletions(-) delete mode 100644 accepted/2021/dotnet-run-resolve-p.md diff --git a/accepted/2021/dotnet-run-resolve-p.md b/accepted/2021/dotnet-run-resolve-p.md deleted file mode 100644 index 45a414b66..000000000 --- a/accepted/2021/dotnet-run-resolve-p.md +++ /dev/null @@ -1,43 +0,0 @@ -# Syntax for passing properties 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 `--`. -* 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:. - -**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 identify usage as `--property` when the argument is legal MSBuild syntax. Legal MSBuild syntax will be defined as: - -* A comma or semi-colon delimited strings of values in the format = or : - -## 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`. -* `-p:` will be passed to MSBuild so the an MSBuild error is displayed when the argument is illegal -* Any other usage will be treated as `--project` and will receive a warning that this use is deprecated. -* Usage in the form `-p:` will be allowed but not encouraged or documented. -* In .NET 7, we will add `-p` as an abbreviation equivalent to `p:` -* At some future point, we will remove `-p` for `--project` - -Implementation note -For System.CommandLine, it is expected that `-p` will be treated as `--property` and removed as an abbreviation for `--project`. Special handling will be needed in the `dotnet run` handler. -Warning text -When -p is used (with no colon) in .NET 6, the following warning will be displayed: -“The abbreviation of -p for --project is deprecated. Please use --project.” -Q & A - From 2f8c3cfa8893df91e57c8aa276963d0e3fedfc3f Mon Sep 17 00:00:00 2001 From: Kathleen Dollard Date: Wed, 16 Jun 2021 13:06:12 -0700 Subject: [PATCH 3/5] Add proposal for resolving -p in dotnet run --- accepted/2021/dotnet-run-resolve-p.md | 49 +++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 accepted/2021/dotnet-run-resolve-p.md diff --git a/accepted/2021/dotnet-run-resolve-p.md b/accepted/2021/dotnet-run-resolve-p.md new file mode 100644 index 000000000..4718eed0e --- /dev/null +++ b/accepted/2021/dotnet-run-resolve-p.md @@ -0,0 +1,49 @@ +# Syntax for passing properties 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 `--`. +* 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:. + +**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 identify usage as `--property` when the argument is legal MSBuild syntax. Legal MSBuild syntax will be defined as: + +* A comma or semi-colon delimited strings of values in the format = or : + +## 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`. +* `-p:` will be passed to MSBuild so the an MSBuild error is displayed when the argument is illegal. +* Any other usage will be treated as `--project` and will receive a warning that this use is deprecated. +* Usage in the form `-p:` will be allowed but not encouraged or documented. +* At some future point, we will remove `-p` for `--project`. + +### Warning text + +When -p is used (with no colon) in .NET 6, the following warning will be displayed: + +*“The abbreviation of -p for --project is deprecated. Please use --project.”* + +### Implementation notes + +We are displaying a deprecation warning for `-p` in .NET 6 and hope to do the additional work to support `-p`. However, once the deprecation is in place, we can add the abbreviation in a feature band (quarterly) release. + + +## Q & A + From 6b0fdb3357830184bf2cf4c5ec3ad72e23959135 Mon Sep 17 00:00:00 2001 From: Kathleen Dollard Date: Thu, 17 Jun 2021 13:38:05 -0700 Subject: [PATCH 4/5] Responded to PR comments --- accepted/2021/dotnet-run-resolve-p.md | 35 ++++++++++++++++++--------- 1 file changed, 23 insertions(+), 12 deletions(-) diff --git a/accepted/2021/dotnet-run-resolve-p.md b/accepted/2021/dotnet-run-resolve-p.md index 4718eed0e..b89fb4847 100644 --- a/accepted/2021/dotnet-run-resolve-p.md +++ b/accepted/2021/dotnet-run-resolve-p.md @@ -1,24 +1,35 @@ -# Syntax for passing properties to MSBuild in `dotnet run` +# 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 `--`. +* 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:. +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:`. -**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). +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. -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. +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 identify usage as `--property` when the argument is legal MSBuild syntax. Legal MSBuild syntax will be defined as: +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 = or : +* A comma or semi-colon delimited strings of values in the format = or :. We may simplify this to only checking for the equals - the simplest sufficient check will be used. ## Goals @@ -29,20 +40,20 @@ We believe that in the long term `-p` should be used consistently across `dotnet The basic design is described in the opening: * `-p` with syntax that is valid for MSBuild properties will be treated as `--property`. -* `-p:` will be passed to MSBuild so the an MSBuild error is displayed when the argument is illegal. * Any other usage will be treated as `--project` and will receive a warning that this use is deprecated. -* Usage in the form `-p:` will be allowed but not encouraged or documented. -* At some future point, we will remove `-p` for `--project`. +* 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: -*“The abbreviation of -p for --project is deprecated. Please use --project.”* +> 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 are displaying a deprecation warning for `-p` in .NET 6 and hope to do the additional work to support `-p`. However, once the deprecation is in place, we can add the abbreviation in a feature band (quarterly) release. +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 From 87489475b376c22ebc4d4fc04d91eb57bd47db5f Mon Sep 17 00:00:00 2001 From: Kathleen Dollard Date: Thu, 17 Jun 2021 13:54:08 -0700 Subject: [PATCH 5/5] More PR response --- accepted/2021/dotnet-run-resolve-p.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/accepted/2021/dotnet-run-resolve-p.md b/accepted/2021/dotnet-run-resolve-p.md index b89fb4847..228fcc69f 100644 --- a/accepted/2021/dotnet-run-resolve-p.md +++ b/accepted/2021/dotnet-run-resolve-p.md @@ -31,6 +31,10 @@ We will interpret `-p` as `--property` when the argument value is legal MSBuild * A comma or semi-colon delimited strings of values in the format = or :. 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.