diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 6f137351a51c5..cf8305c80456f 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -86,7 +86,7 @@ | Playwright | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Developer.Playwright/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Developer.Playwright-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.Playwright_1.0.0-beta.1/sdk/loadtestservice/Azure.Developer.Playwright/) | | Playwright NUnit | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Developer.Playwright.NUnit/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Developer.Playwright.NUnit-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.Playwright.NUnit_1.0.0-beta.1/sdk/loadtestservice/Azure.Developer.Playwright.NUnit/) | | Programmable Connectivity | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.ProgrammableConnectivity/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.ProgrammableConnectivity-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.ProgrammableConnectivity_1.0.0-beta.1/sdk/communication/Azure.Communication.ProgrammableConnectivity/) | -| Provisioning | NuGet [1.2.1](https://www.nuget.org/packages/Azure.Provisioning/1.2.1) | [docs](/dotnet/api/overview/azure/Provisioning-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_1.2.1/sdk/provisioning/Azure.Provisioning/) | +| Provisioning | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Provisioning/1.3.0) | [docs](/dotnet/api/overview/azure/Provisioning-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_1.3.0/sdk/provisioning/Azure.Provisioning/) | | Provisioning - Resources | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.Resources/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.Resources-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Resources_0.2.0/sdk/provisioning/Azure.Provisioning.Resources/) | | Purview Account | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Account/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Account-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Account_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Account/) | | Purview Administration | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Administration/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Administration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Administration_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Administration/) | @@ -364,7 +364,7 @@ | Resource Management - Sitemanager | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.SiteManager/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.SiteManager-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SiteManager_1.0.0-beta.1/sdk/sitemanager/Azure.ResourceManager.SiteManager/) | | Resource Management - Sphere | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.Sphere/1.0.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Sphere-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sphere_1.0.1/sdk/sphere/Azure.ResourceManager.Sphere/) | | Resource Management - Spring App Discovery | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.SpringAppDiscovery/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.SpringAppDiscovery-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SpringAppDiscovery_1.0.0-beta.2/sdk/springappdiscovery/Azure.ResourceManager.SpringAppDiscovery/) | -| Resource Management - SQL | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.3.0)
NuGet [1.4.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.4.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Sql-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.3.0/sdk/sqlmanagement/Azure.ResourceManager.Sql/)
GitHub [1.4.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.4.0-beta.2/sdk/sqlmanagement/Azure.ResourceManager.Sql/) | +| Resource Management - SQL | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.3.0)
NuGet [1.4.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.4.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.Sql-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.3.0/sdk/sqlmanagement/Azure.ResourceManager.Sql/)
GitHub [1.4.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.4.0-beta.3/sdk/sqlmanagement/Azure.ResourceManager.Sql/) | | Resource Management - SQL Virtual Machine | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.SqlVirtualMachine/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.SqlVirtualMachine-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SqlVirtualMachine_1.1.1/sdk/sqlvirtualmachine/Azure.ResourceManager.SqlVirtualMachine/) | | Resource Management - Standby Pool | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.StandbyPool/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StandbyPool-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StandbyPool_1.1.0/sdk/standbypool/Azure.ResourceManager.StandbyPool/) | | Resource Management - Storage | NuGet [1.4.4](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.4.4) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme) | GitHub [1.4.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.4.4/sdk/storage/Azure.ResourceManager.Storage/) | @@ -373,6 +373,7 @@ | Resource Management - Storage Mover | NuGet [1.2.1](https://www.nuget.org/packages/Azure.ResourceManager.StorageMover/1.2.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageMover-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageMover_1.2.1/sdk/storagemover/Azure.ResourceManager.StorageMover/) | | Resource Management - Storage Pool | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.StoragePool/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StoragePool-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StoragePool_1.1.1/sdk/storagepool/Azure.ResourceManager.StoragePool/) | | Resource Management - Storage Sync | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageSync/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageSync-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageSync_1.3.0/sdk/storagesync/Azure.ResourceManager.StorageSync/) | +| Resource Management - Storagediscovery | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.StorageDiscovery/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageDiscovery_1.0.0-beta.1/sdk/storagediscovery/Azure.ResourceManager.StorageDiscovery/) | | Resource Management - Stream Analytics | NuGet [1.2.1](https://www.nuget.org/packages/Azure.ResourceManager.StreamAnalytics/1.2.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StreamAnalytics-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StreamAnalytics_1.2.1/sdk/streamanalytics/Azure.ResourceManager.StreamAnalytics/) | | Resource Management - Subscriptions | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Subscription/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Subscription-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Subscription_1.1.1/sdk/subscription/Azure.ResourceManager.Subscription/) | | Resource Management - Support | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Support/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Support-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Support_1.1.1/sdk/support/Azure.ResourceManager.Support/) | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 3ff06cfcc567a..3400f160d20f3 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -89,7 +89,7 @@ | Playwright | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Developer.Playwright/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Developer.Playwright-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.Playwright_1.0.0-beta.1/sdk/loadtestservice/Azure.Developer.Playwright/) | | Playwright NUnit | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Developer.Playwright.NUnit/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Developer.Playwright.NUnit-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Developer.Playwright.NUnit_1.0.0-beta.1/sdk/loadtestservice/Azure.Developer.Playwright.NUnit/) | | Programmable Connectivity | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.ProgrammableConnectivity/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.ProgrammableConnectivity-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.ProgrammableConnectivity_1.0.0-beta.1/sdk/communication/Azure.Communication.ProgrammableConnectivity/) | -| Provisioning | NuGet [1.2.1](https://www.nuget.org/packages/Azure.Provisioning/1.2.1) | [docs](/dotnet/api/overview/azure/Provisioning-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_1.2.1/sdk/provisioning/Azure.Provisioning/) | +| Provisioning | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Provisioning/1.3.0) | [docs](/dotnet/api/overview/azure/Provisioning-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_1.3.0/sdk/provisioning/Azure.Provisioning/) | | Provisioning - Resources | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.Resources/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.Resources-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Resources_0.2.0/sdk/provisioning/Azure.Provisioning.Resources/) | | Purview Account | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Account/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Account-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Account_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Account/) | | Purview Administration | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.Administration/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Administration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Administration_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.Administration/) | @@ -375,7 +375,7 @@ | Resource Management - Sitemanager | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.SiteManager/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/ResourceManager.SiteManager-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SiteManager_1.0.0-beta.1/sdk/sitemanager/Azure.ResourceManager.SiteManager/) | | Resource Management - Sphere | NuGet [1.0.1](https://www.nuget.org/packages/Azure.ResourceManager.Sphere/1.0.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Sphere-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sphere_1.0.1/sdk/sphere/Azure.ResourceManager.Sphere/) | | Resource Management - Spring App Discovery | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.SpringAppDiscovery/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.SpringAppDiscovery-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SpringAppDiscovery_1.0.0-beta.2/sdk/springappdiscovery/Azure.ResourceManager.SpringAppDiscovery/) | -| Resource Management - SQL | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.3.0)
NuGet [1.4.0-beta.2](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.4.0-beta.2) | [docs](/dotnet/api/overview/azure/ResourceManager.Sql-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.3.0/sdk/sqlmanagement/Azure.ResourceManager.Sql/)
GitHub [1.4.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.4.0-beta.2/sdk/sqlmanagement/Azure.ResourceManager.Sql/) | +| Resource Management - SQL | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.3.0)
NuGet [1.4.0-beta.3](https://www.nuget.org/packages/Azure.ResourceManager.Sql/1.4.0-beta.3) | [docs](/dotnet/api/overview/azure/ResourceManager.Sql-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.3.0/sdk/sqlmanagement/Azure.ResourceManager.Sql/)
GitHub [1.4.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Sql_1.4.0-beta.3/sdk/sqlmanagement/Azure.ResourceManager.Sql/) | | Resource Management - SQL Virtual Machine | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.SqlVirtualMachine/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.SqlVirtualMachine-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.SqlVirtualMachine_1.1.1/sdk/sqlvirtualmachine/Azure.ResourceManager.SqlVirtualMachine/) | | Resource Management - Standby Pool | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.StandbyPool/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StandbyPool-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StandbyPool_1.1.0/sdk/standbypool/Azure.ResourceManager.StandbyPool/) | | Resource Management - Storage | NuGet [1.4.4](https://www.nuget.org/packages/Azure.ResourceManager.Storage/1.4.4) | [docs](/dotnet/api/overview/azure/ResourceManager.Storage-readme) | GitHub [1.4.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Storage_1.4.4/sdk/storage/Azure.ResourceManager.Storage/) | @@ -384,6 +384,7 @@ | Resource Management - Storage Mover | NuGet [1.2.1](https://www.nuget.org/packages/Azure.ResourceManager.StorageMover/1.2.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageMover-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageMover_1.2.1/sdk/storagemover/Azure.ResourceManager.StorageMover/) | | Resource Management - Storage Pool | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.StoragePool/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StoragePool-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StoragePool_1.1.1/sdk/storagepool/Azure.ResourceManager.StoragePool/) | | Resource Management - Storage Sync | NuGet [1.3.0](https://www.nuget.org/packages/Azure.ResourceManager.StorageSync/1.3.0) | [docs](/dotnet/api/overview/azure/ResourceManager.StorageSync-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageSync_1.3.0/sdk/storagesync/Azure.ResourceManager.StorageSync/) | +| Resource Management - Storagediscovery | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.ResourceManager.StorageDiscovery/1.0.0-beta.1) | | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StorageDiscovery_1.0.0-beta.1/sdk/storagediscovery/Azure.ResourceManager.StorageDiscovery/) | | Resource Management - Stream Analytics | NuGet [1.2.1](https://www.nuget.org/packages/Azure.ResourceManager.StreamAnalytics/1.2.1) | [docs](/dotnet/api/overview/azure/ResourceManager.StreamAnalytics-readme) | GitHub [1.2.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.StreamAnalytics_1.2.1/sdk/streamanalytics/Azure.ResourceManager.StreamAnalytics/) | | Resource Management - Subscriptions | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Subscription/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Subscription-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Subscription_1.1.1/sdk/subscription/Azure.ResourceManager.Subscription/) | | Resource Management - Support | NuGet [1.1.1](https://www.nuget.org/packages/Azure.ResourceManager.Support/1.1.1) | [docs](/dotnet/api/overview/azure/ResourceManager.Support-readme) | GitHub [1.1.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Support_1.1.1/sdk/support/Azure.ResourceManager.Support/) | diff --git a/docs/csharp/language-reference/compiler-messages/constructor-errors.md b/docs/csharp/language-reference/compiler-messages/constructor-errors.md index 15747bd50e2fd..83fddeb272192 100644 --- a/docs/csharp/language-reference/compiler-messages/constructor-errors.md +++ b/docs/csharp/language-reference/compiler-messages/constructor-errors.md @@ -257,6 +257,8 @@ The compiler emits the following errors when a primary constructor violates one - **CS9124**: *Parameter is captured into the state of the enclosing type and its value is also used to initialize a field, property, or event.* - **CS9136**: *Cannot use primary constructor parameter of type inside an instance member.* +When using a primary constructor in a class or struct, every explicitly declared constructor must call the primary constructor using `: this(...)` with an appropriate argument list. This ensures that the primary constructor is always invoked. For more information on primary constructors, see the article on [instance constructors](../../programming-guide/classes-and-structs/instance-constructors.md#primary-constructors) in the programming guide. + Primary constructor parameters are in scope in the body of that type. The compiler can synthesize a field that stores the parameter for use in members or in field initializers. Because a primary constructor parameter may be copied to a field, the following restrictions apply: - Primary constructors can be declared on `struct` and `class` types, but not on `interface` types. diff --git a/docs/csharp/programming-guide/classes-and-structs/knowing-when-to-use-override-and-new-keywords.md b/docs/csharp/programming-guide/classes-and-structs/knowing-when-to-use-override-and-new-keywords.md index b52cd0f8a3e32..ebc06ba199ee5 100644 --- a/docs/csharp/programming-guide/classes-and-structs/knowing-when-to-use-override-and-new-keywords.md +++ b/docs/csharp/programming-guide/classes-and-structs/knowing-when-to-use-override-and-new-keywords.md @@ -83,8 +83,10 @@ dc.Method2(); bcdc.Method1(); bcdc.Method2(); ``` - - When you build the project, you see that the addition of the `Method2` method in `BaseClass` causes a warning. The warning says that the `Method2` method in `DerivedClass` hides the `Method2` method in `BaseClass`. You are advised to use the `new` keyword in the `Method2` definition if you intend to cause that result. Alternatively, you could rename one of the `Method2` methods to resolve the warning, but that is not always practical. + +## The New Keyword + +When you build the project, you see that the addition of the `Method2` method in `BaseClass` causes a warning. The warning says that the `Method2` method in `DerivedClass` hides the `Method2` method in `BaseClass`. You are advised to use the `new` keyword in the `Method2` definition if you intend to cause that result. Alternatively, you could rename one of the `Method2` methods to resolve the warning, but that is not always practical. Before adding `new`, run the program to see the output produced by the additional calling statements. The following results are displayed. @@ -111,7 +113,9 @@ public new void Method2() Run the program again to verify that the output has not changed. Also verify that the warning no longer appears. By using `new`, you are asserting that you are aware that the member that it modifies hides a member that is inherited from the base class. For more information about name hiding through inheritance, see [new Modifier](../../language-reference/keywords/new-modifier.md). - To contrast this behavior to the effects of using `override`, add the following method to `DerivedClass`. The `override` modifier can be added before or after `public`. +## Virtual and Override Keywords + +To contrast this behavior to the effects of using `override`, add the following method to `DerivedClass`. The `override` modifier can be added before or after `public`. ```csharp public override void Method1() @@ -212,8 +216,10 @@ namespace OverrideAndNew } } ``` - - The following example illustrates similar behavior in a different context. The example defines three classes: a base class named `Car` and two classes that are derived from it, `ConvertibleCar` and `Minivan`. The base class contains a `DescribeCar` method. The method displays a basic description of a car, and then calls `ShowDetails` to provide additional information. Each of the three classes defines a `ShowDetails` method. The `new` modifier is used to define `ShowDetails` in the `ConvertibleCar` class. The `override` modifier is used to define `ShowDetails` in the `Minivan` class. + +## Override and New in Derived Classes + +The following example illustrates similar behavior in a different context. The example defines three classes: a base class named `Car` and two classes that are derived from it, `ConvertibleCar` and `Minivan`. The base class contains a `DescribeCar` method. The method displays a basic description of a car, and then calls `ShowDetails` to provide additional information. Each of the three classes defines a `ShowDetails` method. The `new` modifier is used to define `ShowDetails` in the `ConvertibleCar` class. The `override` modifier is used to define `ShowDetails` in the `Minivan` class. ```csharp // Define the base class, Car. The class defines two methods, diff --git a/docs/standard/commandline/design-guidance.md b/docs/standard/commandline/design-guidance.md index d285e62680133..f174862091263 100644 --- a/docs/standard/commandline/design-guidance.md +++ b/docs/standard/commandline/design-guidance.md @@ -11,9 +11,9 @@ ms.topic: conceptual # Design guidance -The following sections present guidance that we recommend you follow when designing a CLI. Think of what your app expects on the command line as similar to what a REST API server expects in the URL. Consistent rules for REST APIs are what make them readily usable to client app developers. In the same way, users of your command-line apps will have a better experience if the CLI design follows common patterns. +The following sections present guidance for designing a CLI. Think of what your app expects on the command line as similar to what a REST API server expects in the URL. Consistent rules for REST APIs are what make them readily usable to client app developers. In the same way, users of your command-line apps will have a better experience if the CLI design follows common patterns. -Once you create a CLI, it is hard to change, especially if your users have used your CLI in scripts they expect to keep running. The guidelines here were developed after the .NET CLI, and it doesn't always follow these guidelines. We are updating the .NET CLI where we can do so without introducing breaking changes. An example of this work is the new design for `dotnet new` in .NET 7. +Once you create a CLI, it is hard to change it, especially if your users have used your CLI in scripts they expect to keep running. ## Symbols @@ -39,7 +39,7 @@ In particular, avoid using any of the following aliases differently than their c * `-i` for `--interactive`. - This option signals to the user that they may be prompted for inputs to questions that the command needs answered. For example, prompting for a username. Your CLI may be used in scripts, so use caution in prompting users who have not specified this switch. + This option signals to the user that they might be prompted for inputs to questions that the command needs answered. For example, prompting for a username. Your CLI might be used in scripts, so use caution in prompting users who haven't specified this switch. * `-o` for `--output`. diff --git a/docs/standard/commandline/get-started-tutorial.md b/docs/standard/commandline/get-started-tutorial.md index b994889339ad7..0621c07245f7a 100644 --- a/docs/standard/commandline/get-started-tutorial.md +++ b/docs/standard/commandline/get-started-tutorial.md @@ -11,7 +11,7 @@ helpviewer_keywords: --- # Tutorial: Get started with System.CommandLine -[!INCLUDE [scl-preview](../../../includes/scl-preview.md)] +[!INCLUDE [scl-preview](./includes/preview.md)] This tutorial shows how to create a .NET command-line app that uses the [`System.CommandLine` library](index.md). You'll begin by creating a simple root command that has one option. Then you'll build on that base, creating a more complex app that contains multiple subcommands and different options for each command. @@ -166,7 +166,7 @@ Options: --file The file to read and display on the conso ``` -`System.CommandLine.RootCommand` by default provides [Help option](how-to-customize-help.md#customize-help-output), [Version option](syntax.md#version-option) and [Suggest directive](syntax.md#suggest-directive). `ParseResult.Invoke` method is responsible for invoking the action of parsed symbol. It could be the action explicitly defined for our command, or the help action defined by `System.CommandLine` for `System.CommandLine.Help.HelpOption`. Moreover, when it detects any parse errors, it prints them to the standard error, prints help to standard output and returns `1` exit code: + by default provides [Help option](how-to-customize-help.md#customize-help-output), [Version option](syntax.md#version-option), and [Suggest directive](syntax.md#suggest-directive). The method is responsible for invoking the action of parsed symbol. It could be the action explicitly defined for the command, or the help action defined by `System.CommandLine` for `System.CommandLine.Help.HelpOption`. Moreover, when it detects any parse errors, it prints them to the standard error, prints help to standard output, and returns `1` as the exit code: ```console scl --invalid bla diff --git a/docs/standard/commandline/how-to-configure-the-parser.md b/docs/standard/commandline/how-to-configure-the-parser.md index cc7ecff94aa90..2d82fc3f87edd 100644 --- a/docs/standard/commandline/how-to-configure-the-parser.md +++ b/docs/standard/commandline/how-to-configure-the-parser.md @@ -12,21 +12,21 @@ ms.topic: how-to # How to configure the parser in System.CommandLine -[!INCLUDE [scl-preview](../../../includes/scl-preview.md)] +[!INCLUDE [scl-preview](./includes/preview.md)] -`System.CommandLine.CommandLineConfiguration` is a class that provides properties to configure the parser. It is an optional argument for every `Parse` method, such as `System.CommandLine.Command.Parse` or `System.CommandLine.Parsing.CommandLineParser.Parse`. When it is not provided, the default configuration is used. + is a class that provides properties to configure the parser. It is an optional argument for every `Parse` method, such as and . When it isn't provided, the default configuration is used. -Every `System.CommandLine.ParseResult` instance has a `System.CommandLine.ParseResult.Configuration` property that returns the configuration used for parsing. + has a property that returns the configuration used for parsing. ## Standard output and error -`System.CommandLine.CommandLineConfiguration` makes testing, as well as many extensibility scenarios, easier than using `System.Console`. It exposes two `TextWriter` properties: `Output` and `Error`. These can be set to any `TextWriter` instance, such as a `StringWriter`, which can be used to capture output for testing. +`CommandLineConfiguration` makes testing, as well as many extensibility scenarios, easier than using `System.Console`. It exposes two `TextWriter` properties: `Output` and `Error`. These can be set to any `TextWriter` instance, such as a `StringWriter`, which can be used to capture output for testing. -Let's define a simple command that writes to standard output: +Define a simple command that writes to standard output: :::code language="csharp" source="snippets/configuration/csharp/Program.cs" id="rootcommand"::: -Now, let's use `CommandLineConfiguration` to capture the output: +Now, use `CommandLineConfiguration` to capture the output: :::code language="csharp" source="snippets/configuration/csharp/Program.cs" id="captureoutput"::: diff --git a/docs/standard/commandline/how-to-customize-help.md b/docs/standard/commandline/how-to-customize-help.md index 3fb6483363260..c9fa4be3d3eb5 100644 --- a/docs/standard/commandline/how-to-customize-help.md +++ b/docs/standard/commandline/how-to-customize-help.md @@ -12,7 +12,7 @@ ms.topic: how-to # Customize help output -Command-line apps typically provide an option to display a brief description of the available commands, options, and arguments. `System.CommandLine` provides `System.CommandLine.Help.HelpOption` that is by default included in the [RootCommand](syntax.md#root-command) options. System.CommandLine.Help.HelpOption generates help output for defined symbols by using the information exposed by `System.CommandLine.Symbol.Name`, `System.CommandLine.Symbol.HelpName`, `System.CommandLine.Symbol.Description`, and other properties like default value or completion sources. +Command-line apps typically provide an option to display a brief description of the available commands, options, and arguments. `System.CommandLine` provides , which is included in the [RootCommand](syntax.md#root-command) options by default. `HelpOption` generates help output for defined symbols by using the information exposed by , , , and other properties like default value or completion sources. :::code language="csharp" source="snippets/customize-help/csharp/Program.cs" id="original" ::: @@ -45,11 +45,11 @@ dotnet -? dotnet /? ``` -Help output doesn't necessarily show all available commands, arguments, and options. Some of them might be *hidden* via the `System.CommandLine.Symbol.Hidden` property, which means they don't show up in help output (and completions) but can be specified on the command line. +Help output doesn't necessarily show all available commands, arguments, and options. Some of them might be *hidden* via the property, which means they don't show up in help output (and completions) but can be specified on the command line. ## Help customization - You can customize help output for commands by defining specific help text for each symbol, providing further clarity to users regarding their usage. +You can customize help output for commands by defining specific help text for each symbol, providing further clarity to users regarding their usage. To customize the name of an option's argument, use the option's `System.CommandLine.Option.HelpName` property. diff --git a/docs/standard/commandline/how-to-customize-parsing-and-validation.md b/docs/standard/commandline/how-to-customize-parsing-and-validation.md index ef80bee94e997..1cd817908a51a 100644 --- a/docs/standard/commandline/how-to-customize-parsing-and-validation.md +++ b/docs/standard/commandline/how-to-customize-parsing-and-validation.md @@ -12,7 +12,7 @@ ms.topic: how-to # How to customize parsing and validation in System.CommandLine -[!INCLUDE [scl-preview](../../../includes/scl-preview.md)] +[!INCLUDE [scl-preview](./includes/preview.md)] By default, System.CommandLine provides a set of built-in parsers that can parse many common types: @@ -36,7 +36,7 @@ Other types are not supported, but you can create custom parsers for them. You c Every option, argument, and command can have one or more validators. Validators are used to ensure that the parsed value meets certain criteria. For example, you can validate that a number is positive, or that a string is not empty. You can also create complex validators that check against multiple conditions. -Every symbol type in System.CommandLine has a `Validators` property that contains a list of validators. The validators are executed after the input is parsed, and they can report an error if the validation fails. +Every symbol type in System.CommandLine has a property that contains a list of validators. The validators are executed after the input is parsed, and they can report an error if the validation fails. To provide custom validation code, call `System.CommandLine.Option.Validators.Add` on your option or argument (or command), as shown in the following example: @@ -44,13 +44,13 @@ To provide custom validation code, call `System.CommandLine.Option.Validators.Ad System.CommandLine provides a set of built-in validators that can be used to validate common types: -- `AcceptExistingOnly` - configures given option or argument to accept only values corresponding to an existing file or directory. -- `AcceptLegalFileNamesOnly` - configures given option or argument to accept only values representing legal file names. -- `AcceptOnlyFromAmong` - configures given option or argument to accept only values from a specified set of values. +* `AcceptExistingOnly` - configures given option or argument to accept only values corresponding to an existing file or directory. +* `AcceptLegalFileNamesOnly` - configures given option or argument to accept only values representing legal file names. +* `AcceptOnlyFromAmong` - configures given option or argument to accept only values from a specified set of values. ## Custom parsers -Custom parsers are required to parse types with no default parser, such as complex types. They can also be used to parse supported types in a different way than the built-in parsers. +To parse types with no default parser, such as complex types, you need a custom parser. Custom parsers can also be used to parse supported types in a different way than the built-in parsers. Suppose you have a `Person` type: @@ -75,5 +75,5 @@ Here are some examples of what you can do with `CustomParser` that you can't do ## See also -- [How to parse and invoke the result](how-to-parse-and-invoke.md) -- [System.CommandLine overview](index.md) +* [How to parse and invoke the result](how-to-parse-and-invoke.md) +* [System.CommandLine overview](index.md) diff --git a/docs/standard/commandline/how-to-enable-tab-completion.md b/docs/standard/commandline/how-to-enable-tab-completion.md index 4ad50497ee67f..b3963ff4a04f4 100644 --- a/docs/standard/commandline/how-to-enable-tab-completion.md +++ b/docs/standard/commandline/how-to-enable-tab-completion.md @@ -12,9 +12,9 @@ ms.topic: how-to # Tab completion for System.CommandLine -[!INCLUDE [scl-preview](../../../includes/scl-preview.md)] +[!INCLUDE [scl-preview](./includes/preview.md)] -Apps that use `System.CommandLine` have built-in support for tab completion in certain shells. To enable it, the end user must take a few steps once per shell. Once this is done, tab completion is automatic for static values in your app, such as enum values or values defined by calling `System.CommandLine.Option.AcceptOnlyFromAmong`. You can also customize tab completion by providing values dynamically at runtime. +Apps that use `System.CommandLine` have built-in support for tab completion in certain shells. To enable it, the end user must take a few steps once per shell. Once this is done, tab completion is automatic for static values in your app, such as enum values or values defined by calling . You can also customize tab completion by providing values dynamically at runtime. ## Enable tab completion @@ -59,7 +59,7 @@ The values shown when the Tab key is pressed are provided as `CompletionItem` in The following `CompletionItem` properties are set: * `Label` is the completion value to be shown. -* `SortText` ensures that the values in the list are presented in the correct order. It is set by converting `i` to a two-digit string, so that sorting is based on 01, 02, 03, and so on, through 14. If you do not set this parameter, sorting is based on the `Label`, which in this example is in short date format and will not sort correctly. +* `SortText` ensures that the values in the list are presented in the correct order. It is set by converting `i` to a two-digit string, so that sorting is based on 01, 02, 03, and so on, through 14. If you don't set this parameter, sorting is based on the `Label`, which in this example is in short date format and will not sort correctly. There are other `CompletionItem` properties, such as `Documentation` and `Detail`, but they are not yet used in `System.CommandLine`. diff --git a/docs/standard/commandline/how-to-parse-and-invoke.md b/docs/standard/commandline/how-to-parse-and-invoke.md index dec6407682406..8992e22c7df3d 100644 --- a/docs/standard/commandline/how-to-parse-and-invoke.md +++ b/docs/standard/commandline/how-to-parse-and-invoke.md @@ -11,29 +11,29 @@ helpviewer_keywords: # Parsing and invocation in System.CommandLine -[!INCLUDE [scl-preview](../../../includes/scl-preview.md)] +[!INCLUDE [scl-preview](./includes/preview.md)] -System.CommandLine provides a clear separation between command-line parsing and action invocation. The parsing process is responsible for parsing command-line input and creating a `System.CommandLine.ParseResult` object that contains the parsed values (and parse errors). The action invocation process is responsible for invoking the action associated with the parsed command, option, or directive (arguments can't have actions). +System.CommandLine provides a clear separation between command-line parsing and action invocation. The *parsing process* is responsible for parsing command-line input and creating a object that contains the parsed values (and parse errors). The *action invocation process* is responsible for invoking the action associated with the parsed command, option, or directive (arguments can't have actions). -In the following example from our [Get started with System.CommandLine](get-started-tutorial.md) tutorial, the `ParseResult` is created by parsing the command-line input. No actions are defined or invoked: +In the following example from the [Get started with System.CommandLine](get-started-tutorial.md) tutorial, the `ParseResult` is created by parsing the command-line input. No actions are defined or invoked: :::code language="csharp" source="snippets/get-started-tutorial/csharp/Stage0/Program.cs" id="all" ::: -An action is invoked when a given command (or directive, or option) is parsed successfully. The action is a delegate that takes a `System.CommandLine.ParseResult` parameter and returns an `int` exit code (async actions are also [available](#asynchronous-actions))). The exit code is returned by the `System.CommandLine.Parsing.ParseResult.Invoke` method and can be used to indicate whether the command was executed successfully or not. +An action is invoked when a given command (or directive, or option) is parsed successfully. The action is a delegate that takes a `ParseResult` argument and returns an `int` exit code ([async actions](#asynchronous-actions) are also available). The exit code is returned by the `System.CommandLine.Parsing.ParseResult.Invoke` method and can be used to indicate whether the command was executed successfully or not. -In the following example from our [Get started with System.CommandLine](get-started-tutorial.md) tutorial, the action is defined for the root command and invoked after parsing the command-line input: +In the following example from the [Get started with System.CommandLine](get-started-tutorial.md) tutorial, the action is defined for the root command and invoked after parsing the command-line input: :::code language="csharp" source="snippets/get-started-tutorial/csharp/Stage1/Program.cs" id="all" ::: -Some built-in symbols, such as `System.CommandLine.Help.HelpOption`, `System.CommandLine.VersionOption`, or `System.CommandLine.Completions.SuggestDirective`, come with predefined actions. These symbols are automatically added to the root command when you create it, and when you invoke the `System.CommandLine.Parsing.ParseResult`, they "just work." Using actions allows you to focus on your app logic, while the library takes care of parsing and invoking actions for built-in symbols. If you prefer, you can stick to the parsing process and not define any actions (as in the first example above). +Some built-in symbols, such as `System.CommandLine.Help.HelpOption`, `System.CommandLine.VersionOption`, and `System.CommandLine.Completions.SuggestDirective`, come with predefined actions. These symbols are automatically added to the root command when you create it, and when you invoke the `System.CommandLine.Parsing.ParseResult`, they "just work." Using actions allows you to focus on your app logic, while the library takes care of parsing and invoking actions for built-in symbols. If you prefer, you can stick to the parsing process and not define any actions (as in the first example above). ## ParseResult -The `System.CommandLine.Parsing.ParseResult` type is a class that represents the results of parsing the command-line input. You need to use it to get the parsed values for options and arguments (no matter if you are using actions or not). You can also check if there were any parse errors or unmatched [tokens](syntax.md#tokens). +The class represents the results of parsing the command-line input. You need to use it to get the parsed values for options and arguments (no matter if you're using actions or not). You can also check if there were any parse errors or unmatched [tokens](syntax.md#tokens). ### GetValue -The `System.CommandLine.Parsing.ParseResult.GetValue` method allows you to retrieve the values of options and arguments: +The method lets you retrieve the values of options and arguments: :::code language="csharp" source="snippets/model-binding/csharp/Program.cs" id="getvalue" ::: @@ -51,51 +51,49 @@ This overload of `GetValue` gets the parsed or default value for the specified s ### Parse errors -The `System.CommandLine.Parsing.ParseResult.Errors` property contains a list of parse errors that occurred during the parsing process. Each error is represented by a `System.CommandLine.Parsing.ParseError` object, which contains information about the error, such as the error message and the token that caused the error. +The property contains a list of parse errors that occurred during the parsing process. Each error is represented by a object, which contains information about the error, such as the error message and the token that caused the error. -When you call the `System.CommandLine.Parsing.ParseResult.Invoke` method, it returns an exit code that indicates whether the parsing was successful or not. If there were any parse errors, the exit code is non-zero, and all the parse errors are printed to the standard error. +When you call the method, it returns an exit code that indicates whether the parsing was successful or not. If there were any parse errors, the exit code is non-zero, and all the parse errors are printed to the standard error. -If you are not invoking the `System.CommandLine.Parsing.ParseResult.Invoke` method, you need to handle the errors on your own, for example, by printing them: +If you don't call the `ParseResult.Invoke` method, you need to handle the errors on your own, for example, by printing them: :::code language="csharp" source="snippets/get-started-tutorial/csharp/Stage0/Program.cs" id="errors" ::: ### Unmatched tokens -The `System.CommandLine.Parsing.ParseResult.UnmatchedTokens` property contains a list of the tokens that were parsed but didn't match any configured command, option, or argument. +The property contains a list of the tokens that were parsed but didn't match any configured command, option, or argument. -The list of unmatched tokens is useful in commands that behave like wrappers. A wrapper command takes a set of [tokens](syntax.md#tokens) and forwards them to another command or app. The `sudo` command in Linux is an example. It takes the name of a user to impersonate followed by a command to run. For example: +The list of unmatched tokens is useful in commands that behave like wrappers. A wrapper command takes a set of [tokens](syntax.md#tokens) and forwards them to another command or app. The `sudo` command in Linux is an example. It takes the name of a user to impersonate followed by a command to run. For example, the following command runs the `apt update` command as the user `admin`: ```console sudo -u admin apt update ``` -This command line would run the `apt update` command as the user `admin`. - To implement a wrapper command like this one, set the command property `System.CommandLine.Command.TreatUnmatchedTokensAsErrors` to `false`. Then the `System.CommandLine.Parsing.ParseResult.UnmatchedTokens` property will contain all of the arguments that don't explicitly belong to the command. In the preceding example, `ParseResult.UnmatchedTokens` would contain the `apt` and `update` tokens. ## Actions -Actions are delegates that are invoked when a command (or an option or a directive) is parsed successfully. They take a `System.CommandLine.ParseResult` parameter and return an `int` (or `Task`) exit code. The exit code is used to indicate whether the action was executed successfully or not. +Actions are delegates that are invoked when a command (or an option or a directive) is parsed successfully. They take a argument and return an `int` (or `Task`) exit code. The exit code is used to indicate whether the action was executed successfully or not. -System.CommandLine provides an abstract base class `System.CommandLine.CommandLineAction` and two derived classes: `System.CommandLine.SynchronousCommandLineAction` and `System.CommandLine.AsynchronousCommandLineAction`. The former is used for synchronous actions that return an `int` exit code, while the latter is used for asynchronous actions that return a `Task` exit code. +System.CommandLine provides an abstract base class and two derived classes: and . The former is used for synchronous actions that return an `int` exit code, while the latter is used for asynchronous actions that return a `Task` exit code. -You don't need to create a derived type to define an action. You can use the `System.CommandLine.Command.SetAction` method to set an action for a command. The synchronous action can be a delegate that takes a `System.CommandLine.ParseResult` parameter and returns an `int` exit code. The asynchronous action can be a delegate that takes a `System.CommandLine.ParseResult` and parameters and returns a `Task`. +You don't need to create a derived type to define an action. You can use the method to set an action for a command. The synchronous action can be a delegate that takes a `ParseResult` argument and returns an `int` exit code. The asynchronous action can be a delegate that takes `ParseResult` and arguments and returns a `Task`. :::code language="csharp" source="snippets/get-started-tutorial/csharp/Stage1/Program.cs" id="setaction" ::: ### Asynchronous actions -Synchronous and asynchronous actions should not be mixed in the same application. If you want to use asynchronous actions, your application needs to be asynchronous from the top to the bottom. This means that all actions should be asynchronous, and you should use the `System.CommandLine.Command.SetAction` method that accepts a delegate returning a `Task` exit code. Moreover, the that is passed to the action delegate needs to be passed further to all the methods that can be canceled, such as file I/O operations or network requests. +Synchronous and asynchronous actions should not be mixed in the same application. If you want to use asynchronous actions, your application needs to be asynchronous throughout. This means that all actions should be asynchronous, and you should use the `System.CommandLine.Command.SetAction` method that accepts a delegate returning a `Task` exit code. Moreover, the that's passed to the action delegate needs to be passed further to all the methods that can be canceled, such as file I/O operations or network requests. -On top of that, you need to ensure that the `System.CommandLine.Parsing.ParseResult.InvokeAsync` method is used instead of `System.CommandLine.Parsing.ParseResult.Invoke`. This method is asynchronous and returns a `Task` exit code. It also accepts an optional parameter that can be used to cancel the action. +You also need to ensure that the method is used instead of `Invoke`. This method is asynchronous and returns a `Task` exit code. It also accepts an optional parameter that can be used to cancel the action. -The preceding code uses a `SetAction` overload that gets a [ParseResult](#parseresult) and a rather than just `ParseResult`: +The following code uses a `SetAction` overload that gets a [ParseResult](#parseresult) and a rather than just `ParseResult`: :::code language="csharp" source="snippets/handle-termination/csharp/Program.cs" id="asyncaction" ::: #### Process termination timeout -`System.CommandLine.CommandLineConfiguration.ProcessTerminationTimeout` enables signaling and handling of process termination (Ctrl+C, `SIGINT`, `SIGTERM`) via a that is passed to every async action during invocation. It's enabled by default (2 seconds), but you can set it to `null` to disable it. + enables signaling and handling of process termination (Ctrl+C, `SIGINT`, `SIGTERM`) via a that's passed to every async action during invocation. It's enabled by default (2 seconds), but you can set it to `null` to disable it. When enabled, if the action doesn't complete within the specified timeout, the process will be terminated. This is useful for handling the termination gracefully, for example, by saving the state before the process is terminated. @@ -119,5 +117,5 @@ Every `SetAction` method has an overload that accepts a delegate returning an `i ## See also -[How to customize parsing and validation in System.CommandLine](how-to-customize-parsing-and-validation.md) -[System.CommandLine overview](index.md) +- [How to customize parsing and validation in System.CommandLine](how-to-customize-parsing-and-validation.md) +- [System.CommandLine overview](index.md) diff --git a/docs/standard/commandline/includes/preview.md b/docs/standard/commandline/includes/preview.md new file mode 100644 index 0000000000000..c659ec643076e --- /dev/null +++ b/docs/standard/commandline/includes/preview.md @@ -0,0 +1,7 @@ +--- +ms.date: 07/31/2025 +ms.topic: include +--- +> [!IMPORTANT] +> `System.CommandLine` is currently in preview. This documentation is for version 2.0 beta 5. +> Some information relates to prerelease product that might be substantially modified before it's released. Microsoft makes no warranties, express or implied, with respect to the information provided here. diff --git a/docs/standard/commandline/index.md b/docs/standard/commandline/index.md index 6a251e645818f..3ca349aa188c6 100644 --- a/docs/standard/commandline/index.md +++ b/docs/standard/commandline/index.md @@ -12,7 +12,7 @@ ms.topic: overview # System.CommandLine overview -[!INCLUDE [scl-preview](../../../includes/scl-preview.md)] +[!INCLUDE [scl-preview](./includes/preview.md)] The `System.CommandLine` library provides functionality commonly needed by command-line apps, such as parsing command-line input and displaying help text. @@ -31,9 +31,7 @@ Use of the library also benefits app users: ## NuGet package -The library is available as a NuGet package: - -- [System.CommandLine](https://www.nuget.org/packages/System.CommandLine) +The library is available as a NuGet package: [System.CommandLine](https://www.nuget.org/packages/System.CommandLine). ## Next steps diff --git a/docs/standard/commandline/migration-guide-2.0.0-beta5.md b/docs/standard/commandline/migration-guide-2.0.0-beta5.md index 140ea67de6604..0b1b07ae07052 100644 --- a/docs/standard/commandline/migration-guide-2.0.0-beta5.md +++ b/docs/standard/commandline/migration-guide-2.0.0-beta5.md @@ -11,7 +11,7 @@ helpviewer_keywords: # System.CommandLine 2.0.0-beta5 migration guide -[!INCLUDE [scl-preview](../../../includes/scl-preview.md)] +[!INCLUDE [scl-preview](./includes/preview.md)] The main focus for the 2.0.0-beta5 release was to improve the APIs and take a step toward releasing a stable version of System.CommandLine. The APIs have been simplified and made more coherent and consistent with the [Framework design guidelines](../design-guidelines/index.md). This article describes the breaking changes that were made in 2.0.0-beta5 and the reasoning behind them. @@ -19,38 +19,38 @@ The main focus for the 2.0.0-beta5 release was to improve the APIs and take a st In 2.0.0-beta4, not all types and members followed the [naming guidelines](../design-guidelines/naming-guidelines.md). Some were not consistent with the naming conventions, such as using the `Is` prefix for Boolean properties. In 2.0.0-beta5, some types and members have been renamed. The following table shows the old and new names: -| Old name | New name | -|-------------------------------------------------------------|----------------------------------------------------------------| -| `System.CommandLine.Parsing.Parser` | `System.CommandLine.Parsing.CommandLineParser` | -| `System.CommandLine.Parsing.OptionResult.IsImplicit` | `System.CommandLine.Parsing.OptionResult.Implicit` | -| `System.CommandLine.Option.IsRequired` | `System.CommandLine.Option.Required` | -| `System.CommandLine.Symbol.IsHidden` | `System.CommandLine.Symbol.Hidden` | -| `System.CommandLine.Option.ArgumentHelpName` | `System.CommandLine.Option.HelpName` | -| `System.CommandLine.Parsing.OptionResult.Token` | `System.CommandLine.Parsing.OptionResult.IdentifierToken` | -| `System.CommandLine.Parsing.ParseResult.FindResultFor` | `System.CommandLine.Parsing.ParseResult.GetResult` | -| `System.CommandLine.Parsing.SymbolResult.ErrorMessage` | `System.CommandLine.Parsing.SymbolResult.AddError` | +| Old name | New name | +|--------------------------------------------------------|----------------------------------------------------------------| +| `System.CommandLine.Parsing.Parser` | | +| `System.CommandLine.Parsing.OptionResult.IsImplicit` | | +| `System.CommandLine.Option.IsRequired` | | +| `System.CommandLine.Symbol.IsHidden` | | +| `System.CommandLine.Option.ArgumentHelpName` | | +| `System.CommandLine.Parsing.OptionResult.Token` | | +| `System.CommandLine.Parsing.ParseResult.FindResultFor` | | +| `System.CommandLine.Parsing.SymbolResult.ErrorMessage` | † | -To allow multiple errors for the same symbol to be reported, the `ErrorMessage` property was converted to a method and renamed to `AddError`. +†To allow multiple errors for the same symbol to be reported, the `ErrorMessage` property was converted to a method and renamed to `AddError`. -## Exposing mutable collections +## Mutable collections of options and validators Version 2.0.0-beta4 had numerous `Add` methods that were used to add items to collections, such as arguments, options, subcommands, validators, and completions. Some of these collections were exposed via properties as read-only collections. Because of that, it was impossible to remove items from those collections. -In 2.0.0-beta5, we changed the APIs to expose mutable collections instead of `Add` methods and (sometimes) read-only collections. This allows you to not only add items or enumerate them, but also remove them. The following table shows the old method and new property names: - -| Old method name | New property | -|-------------------------------------------------------------|----------------------------------------------------------------| -| `System.CommandLine.Command.AddArgument` | `System.CommandLine.Command.Arguments.Add` | -| `System.CommandLine.Command.AddOption` | `System.CommandLine.Command.Options.Add` | -| `System.CommandLine.Command.AddCommand` | `System.CommandLine.Command.Subcommands.Add` | -| `System.CommandLine.Command.AddValidator` | `System.CommandLine.Command.Validators.Add` | -| `System.CommandLine.Option.AddValidator` | `System.CommandLine.Option.Validators.Add` | -| `System.CommandLine.Argument.AddValidator` | `System.CommandLine.Argument.Validators.Add` | -| `System.CommandLine.Command.AddCompletions` | `System.CommandLine.Command.CompletionSources.Add` | -| `System.CommandLine.Option.AddCompletions` | `System.CommandLine.Option.CompletionSources.Add` | -| `System.CommandLine.Argument.AddCompletions` | `System.CommandLine.Argument.CompletionSources.Add` | -| `System.CommandLine.Command.AddAlias` | `System.CommandLine.Command.Aliases.Add` | -| `System.CommandLine.Option.AddAlias` | `System.CommandLine.Option.Aliases.Add` | +In 2.0.0-beta5, the APIs were changed to expose mutable collections instead of `Add` methods and (sometimes) read-only collections. This allows you to not only add items or enumerate them, but also remove them. The following table shows the old method and new property names: + +| Old method name | New property | +|---------------------------|----------------------------------| +| `Command.AddArgument` | `Command.Arguments.Add` | +| `Command.AddOption` | `Command.Options.Add` | +| `Command.AddCommand` | `Command.Subcommands.Add` | +| `Command.AddValidator` | `Command.Validators.Add` | +| `Option.AddValidator` | `Option.Validators.Add` | +| `Argument.AddValidator` | `Argument.Validators.Add` | +| `Command.AddCompletions` | `Command.CompletionSources.Add` | +| `Option.AddCompletions` | `Option.CompletionSources.Add` | +| `Argument.AddCompletions` | `Argument.CompletionSources.Add` | +| `Command.AddAlias` | `Command.Aliases.Add` | +| `Option.AddAlias` | `Option.Aliases.Add` | The `RemoveAlias` and `HasAlias` methods were also removed, as the `Aliases` property is now a mutable collection. You can use the `Remove` method to remove an alias from the collection. Use the `Contains` method to check if an alias exists. @@ -60,14 +60,14 @@ Before 2.0.0-beta5, there was no clear separation between the name and [aliases] Moreover, to get the parsed value, users had to store a reference to an option or an argument and then use it to get the value from `ParseResult`. -To promote simplicity and explicitness, the name of a symbol is now a mandatory parameter for every symbol constructor (including `Argument`). We also separated the concept of a name and aliases; now aliases are just aliases and don't include the name of the symbol. Of course, they are optional. As a result, the following changes were made: +To promote simplicity and explicitness, the name of a symbol is now a mandatory parameter for every symbol constructor (including `Argument`). The concept of a name and aliases is now separate: aliases are just aliases and don't include the name of the symbol. Of course, they're optional. As a result, the following changes were made: -- `name` is now a mandatory argument for every public constructor of `Argument`, `Option`, and `Command`. In the case of `Argument`, it is not used for parsing, but to generate the help. In the case of `Option` and `Command`, it is used to identify the symbol during parsing and also for help and completions. +- `name` is now a mandatory argument for every public constructor of , , and . In the case of `Argument`, it isn't used for parsing, but to generate the help. In the case of `Option` and `Command`, it's used to identify the symbol during parsing and also for help and completions. - The `Symbol.Name` property is no longer `virtual`; it's now read-only and returns the name as it was provided when the symbol was created. Because of that, `Symbol.DefaultName` was removed and `Option.Name` no longer removes the `--`, `-`, or `/` or any other prefix from the longest alias. -- The `Aliases` property exposed by `Option` and `Command` is now a mutable collection. This collection no longer includes the name of the symbol. +- The `Aliases` property exposed by [`Option`](xref:System.CommandLine.Option.Aliases) and [`Command`](xref:System.CommandLine.Command.Aliases) is now a mutable collection. This collection no longer includes the name of the symbol. - `System.CommandLine.Parsing.IdentifierSymbol` was removed (it was a base type for both `Command` and `Option`). -Having the name always present allows for [getting the parsed value by name](how-to-parse-and-invoke.md#getvalue): +Having the name always present lets you [get the parsed value by name](how-to-parse-and-invoke.md#getvalue): ```csharp RootCommand command = new("The description.") @@ -81,9 +81,9 @@ int number = parseResult.GetValue("--number"); ### Creating options with aliases -In the past, `Option` exposed many constructors, some of which accepted the name. Since the name is now mandatory and we expect aliases to be frequently provided for `Option`, there's only a single constructor. It accepts the name and a `params` array of aliases. +In the past, `Option` exposed many constructors, some of which accepted the name. Since the name is now mandatory and aliases will frequently be provided for `Option`, there's only a single constructor. It accepts the name and a `params` array of aliases. -Before 2.0.0-beta5, `Option` had a constructor that took a name and a description. Because of that, the second argument might now be treated as an alias rather than a description. It's the only known breaking change in the API that is not going to cause a compiler error. +Before 2.0.0-beta5, `Option` had a constructor that took a name and a description. Because of that, the second argument might now be treated as an alias rather than a description. It's the only known breaking change in the API that doesn't cause a compiler error. Old code that used the constructor with a description should be updated to use the new constructor that takes a name and aliases, and then set the `Description` property separately. For example: @@ -100,16 +100,16 @@ Option beta5 = new("--help", "-h", "/h") ## Default values and custom parsing -In 2.0.0-beta4, users could set default values for options and arguments by using the `SetDefaultValue` methods. Those methods accepted an `object` value, which was not type-safe and could lead to run-time errors if the value was not compatible with the option or argument type: +In 2.0.0-beta4, you could set default values for options and arguments by using the `SetDefaultValue` methods. Those methods accepted an `object` value, which wasn't type-safe and could lead to run-time errors if the value was not compatible with the option or argument type: ```csharp Option option = new("--number"); option.SetDefaultValue("text"); // This is not type-safe, as the value is a string, not an int. ``` -Moreover, some of the `Option` and `Argument` constructors accepted a parse delegate and a boolean indicating whether the delegate was a custom parser or a default value provider. This was confusing. +Moreover, some of the `Option` and `Argument` constructors accepted a parse delegate and a Boolean indicating whether the delegate was a custom parser or a default value provider. This was confusing. -`Option` and `Argument` classes now have a `DefaultValueFactory` property that can be used to set a delegate that can be called to get the default value for the option or argument. This delegate is invoked when the option or argument is not found in the parsed command line input. +`Option` and `Argument` classes now have a property that can be used to set a delegate that can be called to get the default value for the option or argument. This delegate is invoked when the option or argument is not found in the parsed command line input. ```csharp Option number = new("--number") @@ -118,7 +118,7 @@ Option number = new("--number") }; ``` -`Argument` and `Option` also come with a `CustomParser` property that can be used to set a custom parser for the symbol: +`Argument` and `Option` also come with a property that can be used to set a custom parser for the symbol: ```csharp Argument uri = new("arg") @@ -136,13 +136,13 @@ Argument uri = new("arg") }; ``` -Moreover, `CustomParser` accepts a delegate of type `Func`, rather than the previous `ParseArgument` delegate. This and a few other custom delegates were removed to simplify the API and reduce the number of types exposed by the API, which reduces startup time spent during JIT compilation. +Moreover, `CustomParser` accepts a delegate of type `Func`, rather than the previous `ParseArgument` delegate. This and a few other custom delegates were removed to simplify the API and reduce the number of types exposed by the API, which reduces startup time spent during JIT compilation. For more examples of how to use `DefaultValueFactory` and `CustomParser`, see [How to customize parsing and validation in System.CommandLine](how-to-customize-parsing-and-validation.md). ## The separation of parsing and invocation -In 2.0.0-beta4, it was possible to separate the parsing and invoking of commands, but it was quite unclear how to do it. `Command` did not expose a `Parse` method, but `CommandExtensions` provided `Parse`, `Invoke`, and `InvokeAsync` extension methods for `Command`. This was confusing, as it was not clear which method to use and when. The following changes were made to simplify the API: +In 2.0.0-beta4, it was possible to separate the parsing and invoking of commands, but it wasn't clear how to do it. `Command` did not expose a `Parse` method, but `CommandExtensions` provided `Parse`, `Invoke`, and `InvokeAsync` extension methods for `Command`. This was confusing, as it was not clear which method to use and when. The following changes were made to simplify the API: - `Command` now exposes a `Parse` method that returns a `ParseResult` object. This method is used to parse the command line input and return the result of the parse operation. Moreover, it makes it clear that the command is not invoked, but only parsed and only in synchronous manner. - `ParseResult` now exposes both `Invoke` and `InvokeAsync` methods that can be used to invoke the command. This makes it clear that the command is invoked after parsing, and allows for both synchronous and asynchronous invocation. @@ -167,7 +167,7 @@ Before 2.0.0-beta5, it was possible to customize the parsing, but only with some - `UseHelp` and `UseVersion` were removed. The help and version are now exposed by the [HelpOption](how-to-customize-help.md#customize-help-output) and [VersionOption](syntax.md#version-option) public types. They are both included by default in the options defined by [RootCommand](syntax.md#root-command). - `UseHelpBuilder` was removed. For more information on how to customize the help output, see [How to customize help in System.CommandLine](how-to-customize-help.md). - `AddMiddleware` was removed. It slowed down the application startup, and features can be expressed without it. -- `UseParseErrorReporting` and `UseTypoCorrections` were removed. The parse errors are now reported by default when invoking `ParseResult`. You can configure it by using the `ParseErrorAction` exposed by `ParseResult.Action` property. +- `UseParseErrorReporting` and `UseTypoCorrections` were removed. The parse errors are now reported by default when invoking `ParseResult`. You can configure it by using the action exposed by `ParseResult.Action` property. ```csharp ParseResult result = rootCommand.Parse("myArgs", config); @@ -178,18 +178,18 @@ Before 2.0.0-beta5, it was possible to customize the parsing, but only with some } ``` -- `UseLocalizationResources` and `LocalizationResources` were removed. This feature was used mostly by the `dotnet` CLI to add missing translations to `System.CommandLine`. All those translations were moved to the System.CommandLine itself, so this feature is no longer needed. If we are missing support for your language, please [report an issue](https://github.com/dotnet/command-line-api/issues/new/choose). -- `UseTokenReplacer` was removed. [Response files](syntax.md#response-files) are enabled by default, but you can disable them by setting the `System.CommandLine.CommandLineConfiguration.ResponseFileTokenReplacer` property to `null`. You can also provide a custom implementation to customize how response files are processed. +- `UseLocalizationResources` and `LocalizationResources` were removed. This feature was used mostly by the `dotnet` CLI to add missing translations to `System.CommandLine`. All those translations were moved to the System.CommandLine itself, so this feature is no longer needed. If support for your language is missing, please [report an issue](https://github.com/dotnet/command-line-api/issues/new/choose). +- `UseTokenReplacer` was removed. [Response files](syntax.md#response-files) are enabled by default, but you can disable them by setting the property to `null`. You can also provide a custom implementation to customize how response files are processed. -Last but not least, the `IConsole` and all related interfaces (`IStandardOut`, `IStandardError`, `IStandardIn`) were removed. `System.CommandLine.CommandLineConfiguration` exposes two `TextWriter` properties: `Output` and `Error`. These can be set to any `TextWriter` instance, such as a `StringWriter`, which can be used to capture output for testing. Our motivation was to expose fewer types and reuse existing abstractions. +Last but not least, the `IConsole` and all related interfaces (`IStandardOut`, `IStandardError`, `IStandardIn`) were removed. exposes two `TextWriter` properties: and . You can set these properties to any instance, such as a `StringWriter`, which can be used to capture output for testing. The motivation for this change was to expose fewer types and reuse existing abstractions. ### Invocation In 2.0.0-beta4, the `ICommandHandler` interface exposed `Invoke` and `InvokeAsync` methods that were used to invoke the parsed command. This made it easy to mix synchronous and asynchronous code, for example by defining a synchronous handler for a command and then invoking it asynchronously (which could lead to a [deadlock](../../csharp/asynchronous-programming/index.md#dont-block-await-instead)). Moreover, it was possible to define a handler only for a command, but not for an option (like help, which displays help) or a directive. -A new abstract base class `System.CommandLine.CommandLineAction`and two derived classes: `System.CommandLine.SynchronousCommandLineAction` and `System.CommandLine.AsynchronousCommandLineAction` have been introduced. The former is used for synchronous actions that return an `int` exit code, while the latter is used for asynchronous actions that return a `Task` exit code. +A new abstract base class and two derived classes, `SynchronousCommandLineAction` and `AsynchronousCommandLineAction`, have been introduced. The former is used for synchronous actions that return an `int` exit code, while the latter is used for asynchronous actions that return a `Task` exit code. -You don't need to create a derived type to define an action. You can use the `System.CommandLine.Command.SetAction` method to set an action for a command. The synchronous action can be a delegate that takes a `System.CommandLine.ParseResult` parameter and returns an `int` exit code (or nothing, and then a default `0` exit code is returned). The asynchronous action can be a delegate that takes a `System.CommandLine.ParseResult` and parameters and returns a `Task` (or `Task` to get default exit code returned). +You don't need to create a derived type to define an action. You can use the method to set an action for a command. The synchronous action can be a delegate that takes a `System.CommandLine.ParseResult` parameter and returns an `int` exit code (or nothing, and then a default `0` exit code is returned). The asynchronous action can be a delegate that takes a `System.CommandLine.ParseResult` and parameters and returns a `Task` (or `Task` to get default exit code returned). ```csharp rootCommand.SetAction(ParseResult parseResult => @@ -210,7 +210,7 @@ rootCommand.SetHandler(async (InvocationContext context) => }); ``` -Majority of our users were not obtaining this token and passing it further. We made `CancellationToken` mandatory argument for asynchronous actions, in order for the compiler to produce a warning when it's not passed further ([CA2016](../../fundamentals/code-analysis/quality-rules/ca2016.md)). +Most users weren't obtaining this token and passing it further. `CancellationToken` is now a mandatory argument for asynchronous actions, such that the compiler produces a warning when it's not passed further (see [CA2016](../../fundamentals/code-analysis/quality-rules/ca2016.md)). ```csharp rootCommand.SetAction((ParseResult parseResult, CancellationToken token) => @@ -220,7 +220,7 @@ rootCommand.SetAction((ParseResult parseResult, CancellationToken token) => }); ``` -As a result of these and other forementioned changes, the `InvocationContext` class got also removed. The `ParseResult` is now passed directly to the action, so you can access the parsed values and options directly from it. +As a result of these and other aforementioned changes, the `InvocationContext` class got also removed. The `ParseResult` is now passed directly to the action, so you can access the parsed values and options directly from it. To summarize these changes: @@ -233,7 +233,7 @@ For more details about how to use actions, see [How to parse and invoke commands ## The benefits of the simplified API -We hope that the changes made in 2.0.0-beta5 will make the API more consistent, futureproof and easier to use for existing and new users. +The changes made in 2.0.0-beta5 make the API more consistent, future-proof, and easier to use for existing and new users. New users need to learn fewer concepts and types, as the number of public interfaces decreased from 11 to 0, and public classes (and structs) decreased from 56 to 38. The public method count dropped from 378 to 235, and public properties from 118 to 99. @@ -300,7 +300,7 @@ static void Run(bool boolean, string text) Simplicity has also improved the performance of the library (it's a side effect of the work, not the main goal of it). The [benchmarks](https://github.com/adamsitnik/commandline-perf/tree/update) show that the parsing and invoking of commands is now faster than in 2.0.0-beta4, especially for large commands with many options and arguments. The performance improvements are visible in both synchronous and asynchronous scenarios. -For the simplest app presented previously, we got the following results: +The simplest app, presented previously, produces the following results: ```ini BenchmarkDotNet v0.15.0, Windows 11 (10.0.26100.4061/24H2/2024Update/HudsonValley) @@ -322,7 +322,7 @@ IterationCount=100 UnrollFactor=1 WarmupCount=3 | SystemCommandLineNowAOT | --bool -s test | 17.35 ms | 0.487 ms | 0.23 | ``` -As you can see, the startup time (the benchmarks report the time required to run given executable) has improved by 12% compared to 2.0.0-beta4. If we compile the app with NativeAOT, it is just 3 ms slower than a NativeAOT app that does not parse the args at all (EmptyAOT in the table above). Also, when we exclude the overhead of an empty app (63.58 ms), the parsing is 40% faster than in 2.0.0-beta4 (22.22 ms vs 13.66 ms). +As you can see, the startup time (the benchmarks report the time required to run given executable) has improved by 12% compared to 2.0.0-beta4. If you compile the app with NativeAOT, it's just 3 ms slower than a NativeAOT app that does not parse the args at all (EmptyAOT in the table above). Also, if you exclude the overhead of an empty app (63.58 ms), the parsing is 40% faster than in 2.0.0-beta4 (22.22 ms vs 13.66 ms). ## See also diff --git a/docs/standard/commandline/snippets/customize-help/csharp/Program.cs b/docs/standard/commandline/snippets/customize-help/csharp/Program.cs index 206364be04ae6..ed9b07779dace 100644 --- a/docs/standard/commandline/snippets/customize-help/csharp/Program.cs +++ b/docs/standard/commandline/snippets/customize-help/csharp/Program.cs @@ -121,7 +121,7 @@ static void Sections(string[] args) // for (int i = 0; i < rootCommand.Options.Count; i++) { - // RootCommand has a default HelpOption, we need to update its Action. + // RootCommand has a default HelpOption; update its Action. if (rootCommand.Options[i] is HelpOption defaultHelpOption) { defaultHelpOption.Action = new CustomHelpAction((HelpAction)defaultHelpOption.Action!); diff --git a/docs/standard/commandline/syntax.md b/docs/standard/commandline/syntax.md index b313b0281df50..652eae52866ca 100644 --- a/docs/standard/commandline/syntax.md +++ b/docs/standard/commandline/syntax.md @@ -12,7 +12,7 @@ ms.topic: concept-article # Syntax overview: Commands, options, and arguments -[!INCLUDE [scl-preview](../../../includes/scl-preview.md)] +[!INCLUDE [scl-preview](./includes/preview.md)] This article explains the command-line syntax that `System.CommandLine` recognizes. The information is useful to both users and developers of .NET command-line apps, including the [.NET CLI](../../core/tools/index.md). @@ -54,7 +54,7 @@ A *command* in command-line input is a token that specifies an action or defines The *root command* is the one that specifies the name of the app's executable. For example, the `dotnet` command specifies the *dotnet.exe* executable. -`System.CommandLine.Command` is the general-purpose class for any command or subcommand, while `System.CommandLine.RootCommand` is a specialized version intended for the application's root entry point, inheriting all features of `System.CommandLine.Command` but adding root-specific behavior and defaults, such as [Help option](how-to-customize-help.md#customize-help-output), [Version option](#version-option) and [Suggest directive](#suggest-directive). + is the general-purpose class for any command or subcommand, while is a specialized version intended for the application's root entry point. `RootCommand` inherits all features of `Command` but adds root-specific behavior and defaults, such as [Help option](how-to-customize-help.md#customize-help-output), [Version option](#version-option), and [Suggest directive](#suggest-directive). ### Subcommands @@ -81,7 +81,7 @@ dotnet tool update dotnet-suggest --verbosity quiet --global ^---------^ ^------^ ``` -As this example illustrates, the value of the option may be explicit (`quiet` for `--verbosity`) or implicit (nothing follows `--global`). Options that have no value specified are typically Boolean parameters that default to `true` if the option is specified on the command line. +As this example illustrates, the value of the option can be explicit (`quiet` for `--verbosity`) or implicit (nothing follows `--global`). Options that have no value specified are typically Boolean parameters that default to `true` if the option is specified on the command line. For some Windows command-line apps, you identify an option by using a leading slash (`/`) with the option name. For example: @@ -100,11 +100,11 @@ To add an option to a command and recursively to all of its subcommands, use the ### Required Options -Some options have required arguments. For example in the .NET CLI, `--output` requires a folder name argument. If the argument is not provided, the command fails. To make an option required, set its `System.CommandLine.Symbol.Required` property to `true`, as shown in the following example: +Some options have required arguments. For example in the .NET CLI, `--output` requires a folder name argument. If the argument is not provided, the command fails. To make an option required, set its property to `true`, as shown in the following example: :::code language="csharp" source="snippets/define-symbols/csharp/Program.cs" id="requiredoption" ::: -If a required option has a default value (specified via `DefaultValueFactory` property), the option doesn't have to be specified on the command line. In that case, the default value provides the required option value. +If a required option has a default value (specified via the property), the option doesn't have to be specified on the command line. In that case, the default value provides the required option value. ## Arguments @@ -278,15 +278,15 @@ Arity is expressed with a minimum value and a maximum value, as the following ta | | | Valid: | --file a.json b.json | | | | Invalid: | --file | -`System.CommandLine` has an `System.CommandLine.ArgumentArity` struct for defining arity, with the following values: +`System.CommandLine` has an struct for defining arity, with the following values: -* `System.CommandLine.ArgumentArity.Zero` - No values allowed. -* `System.CommandLine.ArgumentArity.ZeroOrOne` - May have one value, may have no values. -* `System.CommandLine.ArgumentArity.ExactlyOne` - Must have one value. -* `System.CommandLine.ArgumentArity.ZeroOrMore` - May have one value, multiple values, or no values. -* `System.CommandLine.ArgumentArity.OneOrMore` - May have multiple values, must have at least one value. +* - No values allowed. +* - Can have one value or no value. +* - Must have one value. +* - Can have one value, multiple values, or no values. +* - Can have multiple values; must have at least one value. -You can explicitly set arity by using the `Arity` property, but in most cases that is not necessary. `System.CommandLine` automatically determines the argument arity based on the argument type: +You can explicitly set arity by using the `Arity` property, but in most cases that isn't necessary. `System.CommandLine` automatically determines the argument arity based on the argument type: | Argument type | Default arity | |------------------|----------------------------| @@ -310,7 +310,7 @@ By default, when you call a command, you can repeat an option name to specify mu myapp --items one --items two --items three ``` -To allow multiple arguments without repeating the option name, set `System.CommandLine.Option.AllowMultipleArgumentsPerToken` to `true`. This setting lets you enter the following command line. +To allow multiple arguments without repeating the option name, set to `true`. This setting lets you enter the following command line. ```console myapp --items one two three @@ -342,7 +342,7 @@ In both variants in this example, the argument `arg` would apply only to the opt ## Boolean options (flags) -If `true` or `false` is passed for an option having a `bool` argument, it's parsed as expected. But an option whose argument type is `bool` typically doesn't require an argument to be specified. Boolean options, sometimes called "flags", typically have an [arity](#argument-arity) of `System.CommandLine.ArgumentArity.ZeroOrOne`. The presence of the option name on the command line, with no argument following it, results in a default value of `true`. The absence of the option name in command-line input results in a value of `false`. If the `myapp` command prints out the value of a Boolean option named `--interactive`, the following input creates the following output: +If `true` or `false` is passed for an option having a `bool` argument, it's parsed as expected. But an option whose argument type is `bool` typically doesn't require an argument to be specified. Boolean options, sometimes called "flags", typically have an [arity](#argument-arity) of . The presence of the option name on the command line, with no argument following it, results in a default value of `true`. The absence of the option name in command-line input results in a value of `false`. If the `myapp` command prints out the value of a Boolean option named `--interactive`, the following input creates the following output: ```console myapp @@ -412,7 +412,7 @@ Here are syntax rules that determine how the text in a response file is interpre ## Directives -`System.CommandLine` introduces a syntactic element called a *directive* represented by `System.CommandLine.Directive` type. The `[diagram]` directive is an example. When you include `[diagram]` after the app's name, `System.CommandLine` displays a diagram of the parse result instead of invoking the command-line app: +`System.CommandLine` introduces a syntactic element called a *directive* represented by the type. For example, the [`[diagram]` directive](#the-diagram-directive) is a built-in directive. When you include `[diagram]` after the app's name, `System.CommandLine` displays a diagram of the parse result instead of invoking the command-line app: ```dotnetcli dotnet [diagram] build --no-restore --output ./build-output/ diff --git a/includes/scl-preview.md b/includes/scl-preview.md deleted file mode 100644 index 6c26d2ff678ce..0000000000000 --- a/includes/scl-preview.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -author: tdykstra -ms.author: tdykstra -ms.date: 05/22/2022 -ms.topic: include ---- -> [!IMPORTANT] -> `System.CommandLine` is currently in PREVIEW, and this documentation is for version 2.0 beta 5. -> Some information relates to prerelease product that may be substantially modified before it's released. Microsoft makes no warranties, express or implied, with respect to the information provided here.