diff --git a/.openpublishing.redirection.core.json b/.openpublishing.redirection.core.json index 8a5f108311fca..59326135fce50 100644 --- a/.openpublishing.redirection.core.json +++ b/.openpublishing.redirection.core.json @@ -1267,6 +1267,26 @@ "source_path_from_root": "/docs/core/tutorials/vb-with-visual-studio.md", "redirect_url": "/dotnet/core/tutorials/with-visual-studio" }, + { + "source_path_from_root": "/docs/core/tutorials/debugging-with-visual-studio-mac.md", + "redirect_url": "/dotnet/core/tutorials/debugging-with-visual-studio-code" + }, + { + "source_path_from_root": "/docs/core/tutorials/library-with-visual-studio-mac.md", + "redirect_url": "/dotnet/core/tutorials/library-with-visual-studio-code" + }, + { + "source_path_from_root": "/docs/core/tutorials/publishing-with-visual-studio-mac.md", + "redirect_url": "/dotnet/core/tutorials/publishing-with-visual-studio-code" + }, + { + "source_path_from_root": "/docs/core/tutorials/testing-library-with-visual-studio-mac.md", + "redirect_url": "/dotnet/core/tutorials/testing-library-with-visual-studio-code" + }, + { + "source_path_from_root": "/docs/core/tutorials/with-visual-studio-mac.md", + "redirect_url": "/dotnet/core/tutorials/with-visual-studio-code" + }, { "source_path_from_root": "/docs/core/versions/install-management.md", "redirect_url": "/dotnet/core/install/remove-runtime-sdk-versions" diff --git a/.openpublishing.redirection.fsharp.json b/.openpublishing.redirection.fsharp.json index 2dfaba3efc978..957b1a2f2c70b 100644 --- a/.openpublishing.redirection.fsharp.json +++ b/.openpublishing.redirection.fsharp.json @@ -8,6 +8,10 @@ "source_path_from_root": "/docs/fsharp/getting-started-netcore.md", "redirect_url": "/dotnet/fsharp/get-started/get-started-command-line" }, + { + "source_path_from_root": "/docs/fsharp/get-started/get-started-with-visual-studio-for-mac.md", + "redirect_url": "/dotnet/fsharp/get-started/get-started-vscode" + }, { "source_path_from_root": "/docs/fsharp/introduction-to-functional-programming/first-class-functions.md", "redirect_url": "/dotnet/fsharp/tutorials/using-functions" diff --git a/docs/architecture/microservices/docker-application-development-process/index.md b/docs/architecture/microservices/docker-application-development-process/index.md index 906ba3ca8444b..3b613ad67d71b 100644 --- a/docs/architecture/microservices/docker-application-development-process/index.md +++ b/docs/architecture/microservices/docker-application-development-process/index.md @@ -1,6 +1,6 @@ --- title: Development process for Docker-based applications -description: Get a high-level overview of the options for developing Docker-based applications. Using your choice of Visual Studio for Windows, Visual Studio for Mac, or Visual Studio Code for multiplatform support (Windows, macOS, and Linux). +description: Get a high-level overview of the options for developing Docker-based applications. Using your choice of Visual Studio for Windows or Visual Studio Code for multiplatform support (Windows, macOS, and Linux). ms.date: 11/19/2021 --- # Development process for Docker-based applications @@ -17,8 +17,6 @@ Whether you prefer a full and powerful IDE or a lightweight and agile editor, Mi **Visual Studio (for Windows).** Docker-based .NET 8 application development with Visual Studio requires Visual Studio 2022 version 17.0 or later. Visual Studio 2022 comes with tools for Docker already built in. The tools for Docker let you develop, run, and validate your applications directly in the target Docker environment. You can press F5 to run and debug your application (single container or multiple containers) directly into a Docker host, or press CTRL + F5 to edit and refresh your application without having to rebuild the container. This IDE is the most powerful development choice for Docker-based apps. -**Visual Studio for Mac.** It's an IDE, evolution of Xamarin Studio, running in macOS. This tool should be the preferred choice for developers working in macOS machines who also want to use a powerful IDE. - **Visual Studio Code and Docker CLI**. If you prefer a lightweight and cross-platform editor that supports any development language, you can use Visual Studio Code and the Docker CLI. This IDE is a cross-platform development approach for macOS, Linux, and Windows. Additionally, Visual Studio Code supports extensions for Docker such as IntelliSense for Dockerfiles and shortcut tasks to run Docker commands from the editor. By installing [Docker Desktop](https://hub.docker.com/search/?type=edition&offering=community), you can use a single Docker CLI to build apps for both Windows and Linux. diff --git a/docs/architecture/microservices/net-core-net-framework-containers/net-core-container-scenarios.md b/docs/architecture/microservices/net-core-net-framework-containers/net-core-container-scenarios.md index d25d9e53be694..58ea34998df98 100644 --- a/docs/architecture/microservices/net-core-net-framework-containers/net-core-container-scenarios.md +++ b/docs/architecture/microservices/net-core-net-framework-containers/net-core-container-scenarios.md @@ -21,8 +21,6 @@ Clearly, if your goal is to have an application (web app or service) that can ru [Visual Studio](https://www.visualstudio.com/vs/) provides an integrated development environment (IDE) for Windows and supports Docker development. -[Visual Studio for Mac](https://www.visualstudio.com/vs/visual-studio-mac/) is an IDE, evolution of Xamarin Studio, that runs on macOS and supports Docker-based application development. This tool should be the preferred choice for developers working in Mac machines who also want to use a powerful IDE. - You can also use [Visual Studio Code](https://code.visualstudio.com/) on macOS, Linux, and Windows. Visual Studio Code fully supports .NET 8, including IntelliSense and debugging. Because VS Code is a lightweight editor, you can use it to develop containerized apps on the machine in conjunction with the Docker CLI and the [.NET CLI](../../../core/tools/index.md). You can also target .NET 8 with most third-party editors like Sublime, Emacs, vi, and the open-source OmniSharp project, which also provides IntelliSense support. In addition to the IDEs and editors, you can use the [.NET CLI](../../../core/tools/index.md) for all supported platforms. diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 662b3ac7822af..ac5df54aaecdf 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -80,23 +80,8 @@ | OpenTelemetry Exporter | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.3.0)
NuGet [1.4.0-beta.1](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.Exporter/1.4.0-beta.1) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.Exporter-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.3.0/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/)
GitHub [1.4.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.Exporter_1.4.0-beta.1/sdk/monitor/Azure.Monitor.OpenTelemetry.Exporter/) | | Personalizer | NuGet [2.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Personalizer/2.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Personalizer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [2.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Personalizer_2.0.0-beta.2/sdk/personalizer/Azure.AI.Personalizer/) | | 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 [0.3.0](https://www.nuget.org/packages/Azure.Provisioning/0.3.0) | [docs](/dotnet/api/overview/azure/Provisioning-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_0.3.0/sdk/provisioning/Azure.Provisioning/) | -| Provisioning - App Configuration | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppConfiguration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppConfiguration_0.2.0/sdk/provisioning/Azure.Provisioning.AppConfiguration/) | -| Provisioning - Application Insights | NuGet [0.1.0](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/0.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.ApplicationInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ApplicationInsights_0.1.0/sdk/provisioning/Azure.Provisioning.ApplicationInsights/) | -| Provisioning - Cognitive Services | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_0.2.0/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | -| Provisioning - CosmosDB | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.CosmosDB-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CosmosDB_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.CosmosDB/) | -| Provisioning - Event Hubs | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.EventHubs/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.EventHubs-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.EventHubs_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.EventHubs/) | -| Provisioning - Key Vault | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.KeyVault/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.KeyVault-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.KeyVault_0.2.0/sdk/provisioning/Azure.Provisioning.KeyVault/) | -| Provisioning - Operational Insights | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.OperationalInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.OperationalInsights_0.2.0/sdk/provisioning/Azure.Provisioning.OperationalInsights/) | -| Provisioning - PostgreSQL | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.PostgreSql-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PostgreSql_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.PostgreSql/) | -| Provisioning - Redis | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.Redis/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.Redis-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Redis_0.2.0/sdk/provisioning/Azure.Provisioning.Redis/) | +| Provisioning | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_1.0.0-beta.1/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/) | -| Provisioning - Search | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Search/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Search-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Search_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.Search/) | -| Provisioning - Service Bus | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ServiceBus/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ServiceBus-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ServiceBus_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.ServiceBus/) | -| Provisioning - SignalR | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.SignalR/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.SignalR-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.SignalR_0.2.0/sdk/provisioning/Azure.Provisioning.SignalR/) | -| Provisioning - SQL | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Sql/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Sql-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Sql_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.Sql/) | -| Provisioning - Storage | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.Storage/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.Storage-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Storage_0.2.0/sdk/provisioning/Azure.Provisioning.Storage/) | -| Provisioning - WebPubSub | NuGet [0.1.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.WebPubSub/0.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.WebPubSub-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.WebPubSub_0.1.0-beta.1/sdk/provisioning/Azure.Provisioning.WebPubSub/) | | 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/) | | Purview Data Map | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Analytics.Purview.DataMap/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Analytics.Purview.DataMap-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.DataMap_1.0.0-beta.1/sdk/purview/Azure.Analytics.Purview.DataMap/) | @@ -130,7 +115,7 @@ | WCF Storage Queues | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.WCF.Azure.StorageQueues/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.WCF.Azure.StorageQueues-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.WCF.Azure.StorageQueues_1.0.0-beta.1/sdk/extension-wcf/Microsoft.WCF.Azure.StorageQueues/) | | Web PubSub | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Messaging.WebPubSub/1.4.0) | [docs](/dotnet/api/overview/azure/Messaging.WebPubSub-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.WebPubSub_1.4.0/sdk/webpubsub/Azure.Messaging.WebPubSub/) | | Web PubSub Client | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Messaging.WebPubSub.Client/1.0.0) | [docs](/dotnet/api/overview/azure/Messaging.WebPubSub.Client-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.WebPubSub.Client_1.0.0/sdk/webpubsub/Azure.Messaging.WebPubSub.Client/) | -| Azure client library integration for ASP.NET Core | NuGet [1.7.5](https://www.nuget.org/packages/Microsoft.Extensions.Azure/1.7.5) | [docs](/dotnet/api/overview/azure/Microsoft.Extensions.Azure-readme) | GitHub [1.7.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Extensions.Azure_1.7.5/sdk/extensions/Microsoft.Extensions.Azure/) | +| Azure client library integration for ASP.NET Core | NuGet [1.7.6](https://www.nuget.org/packages/Microsoft.Extensions.Azure/1.7.6) | [docs](/dotnet/api/overview/azure/Microsoft.Extensions.Azure-readme) | GitHub [1.7.6](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Extensions.Azure_1.7.6/sdk/extensions/Microsoft.Extensions.Azure/) | | Blob Storage Key Store for .NET Data Protection | NuGet [1.3.4](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.3.4) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.3.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.3.4/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | | CloudNative CloudEvents with Event Grid | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/1.0.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents_1.0.0/sdk/eventgrid/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/) | | Core - Client - Spatial | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Core.Spatial-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial_1.1.0/sdk/core/Microsoft.Azure.Core.Spatial/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial_1.2.0-beta.1/sdk/core/Microsoft.Azure.Core.Spatial/) | @@ -148,6 +133,30 @@ | Functions extension for Blob Storage | NuGet [5.3.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/5.3.2) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs-readme) | GitHub [5.3.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs_5.3.2/sdk/storage/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/) | | Functions extension for Storage Queues | NuGet [5.3.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Queues/5.3.2) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Queues-readme) | GitHub [5.3.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Storage.Queues_5.3.2/sdk/storage/Microsoft.Azure.WebJobs.Extensions.Storage.Queues/) | | unknown | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO_1.0.0-beta.4/sdk/webpubsub/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO/) | +| Provisioning - App Configuration | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppConfiguration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppConfiguration_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.AppConfiguration/) | +| Provisioning - Appcontainers | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppContainers/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppContainers-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppContainers_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.AppContainers/) | +| Provisioning - Application Insights | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ApplicationInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ApplicationInsights_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.ApplicationInsights/) | +| Provisioning - Appservice | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppService-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.AppService/) | +| Provisioning - Cognitive Services | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | +| Provisioning - Communication | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Communication/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Communication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Communication_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Communication/) | +| Provisioning - Containerregistry | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ContainerRegistry/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ContainerRegistry-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ContainerRegistry_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.ContainerRegistry/) | +| Provisioning - Containerservice | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ContainerService/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ContainerService-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ContainerService_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.ContainerService/) | +| Provisioning - CosmosDB | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.CosmosDB-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CosmosDB_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.CosmosDB/) | +| Provisioning - Deployment | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Deployment/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Deployment-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Deployment_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Deployment/) | +| Provisioning - Event Hubs | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.EventHubs/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.EventHubs-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.EventHubs_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.EventHubs/) | +| Provisioning - Eventgrid | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.EventGrid/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.EventGrid-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.EventGrid_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.EventGrid/) | +| Provisioning - Key Vault | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.KeyVault/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.KeyVault-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.KeyVault_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.KeyVault/) | +| Provisioning - Kubernetes | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Kubernetes/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Kubernetes-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Kubernetes_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Kubernetes/) | +| Provisioning - Kubernetesconfiguration | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.KubernetesConfiguration/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.KubernetesConfiguration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.KubernetesConfiguration_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.KubernetesConfiguration/) | +| Provisioning - Operational Insights | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.OperationalInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.OperationalInsights_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.OperationalInsights/) | +| Provisioning - PostgreSQL | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.PostgreSql-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PostgreSql_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.PostgreSql/) | +| Provisioning - Redis | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Redis/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Redis-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Redis_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Redis/) | +| Provisioning - Search | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Search/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Search-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Search_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Search/) | +| Provisioning - Service Bus | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ServiceBus/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ServiceBus-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ServiceBus_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.ServiceBus/) | +| Provisioning - SignalR | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.SignalR/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.SignalR-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.SignalR_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.SignalR/) | +| Provisioning - SQL | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Sql/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Sql-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Sql_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Sql/) | +| Provisioning - Storage | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Storage/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Storage-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Storage_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Storage/) | +| Provisioning - WebPubSub | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.WebPubSub/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.WebPubSub-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.WebPubSub_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.WebPubSub/) | | Resource Management - Advisor | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.Advisor/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.Advisor-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Advisor_1.0.0-beta.4/sdk/advisor/Azure.ResourceManager.Advisor/) | | Resource Management - Agrifood | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.AgFoodPlatform/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.AgFoodPlatform-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AgFoodPlatform_1.0.0-beta.4/sdk/agrifood/Azure.ResourceManager.AgFoodPlatform/) | | Resource Management - Alerts Management | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.AlertsManagement/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.AlertsManagement-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AlertsManagement_1.1.0/sdk/alertsmanagement/Azure.ResourceManager.AlertsManagement/) | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 817394753dbd2..1b63d0600482b 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -82,23 +82,8 @@ | OpenTelemetry LiveMetrics | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Monitor.OpenTelemetry.LiveMetrics/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Monitor.OpenTelemetry.LiveMetrics-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Monitor.OpenTelemetry.LiveMetrics_1.0.0-beta.3/sdk/monitor/Azure.Monitor.OpenTelemetry.LiveMetrics/) | | Personalizer | NuGet [2.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Personalizer/2.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Personalizer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [2.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Personalizer_2.0.0-beta.2/sdk/personalizer/Azure.AI.Personalizer/) | | 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 [0.3.0](https://www.nuget.org/packages/Azure.Provisioning/0.3.0) | [docs](/dotnet/api/overview/azure/Provisioning-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_0.3.0/sdk/provisioning/Azure.Provisioning/) | -| Provisioning - App Configuration | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.AppConfiguration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppConfiguration_0.2.0/sdk/provisioning/Azure.Provisioning.AppConfiguration/) | -| Provisioning - Application Insights | NuGet [0.1.0](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/0.1.0) | [docs](/dotnet/api/overview/azure/Provisioning.ApplicationInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ApplicationInsights_0.1.0/sdk/provisioning/Azure.Provisioning.ApplicationInsights/) | -| Provisioning - Cognitive Services | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_0.2.0/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | -| Provisioning - CosmosDB | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.CosmosDB-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CosmosDB_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.CosmosDB/) | -| Provisioning - Event Hubs | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.EventHubs/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.EventHubs-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.EventHubs_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.EventHubs/) | -| Provisioning - Key Vault | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.KeyVault/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.KeyVault-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.KeyVault_0.2.0/sdk/provisioning/Azure.Provisioning.KeyVault/) | -| Provisioning - Operational Insights | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.OperationalInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.OperationalInsights_0.2.0/sdk/provisioning/Azure.Provisioning.OperationalInsights/) | -| Provisioning - PostgreSQL | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.PostgreSql-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PostgreSql_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.PostgreSql/) | -| Provisioning - Redis | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.Redis/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.Redis-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Redis_0.2.0/sdk/provisioning/Azure.Provisioning.Redis/) | +| Provisioning | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning_1.0.0-beta.1/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/) | -| Provisioning - Search | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Search/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Search-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Search_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.Search/) | -| Provisioning - Service Bus | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ServiceBus/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ServiceBus-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ServiceBus_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.ServiceBus/) | -| Provisioning - SignalR | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.SignalR/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.SignalR-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.SignalR_0.2.0/sdk/provisioning/Azure.Provisioning.SignalR/) | -| Provisioning - SQL | NuGet [0.2.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Sql/0.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Sql-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Sql_0.2.0-beta.1/sdk/provisioning/Azure.Provisioning.Sql/) | -| Provisioning - Storage | NuGet [0.2.0](https://www.nuget.org/packages/Azure.Provisioning.Storage/0.2.0) | [docs](/dotnet/api/overview/azure/Provisioning.Storage-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Storage_0.2.0/sdk/provisioning/Azure.Provisioning.Storage/) | -| Provisioning - WebPubSub | NuGet [0.1.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.WebPubSub/0.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.WebPubSub-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [0.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.WebPubSub_0.1.0-beta.1/sdk/provisioning/Azure.Provisioning.WebPubSub/) | | 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/) | | Purview Catalog | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.Analytics.Purview.Catalog/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Analytics.Purview.Catalog-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Analytics.Purview.Catalog_1.0.0-beta.4/sdk/purview/Azure.Analytics.Purview.Catalog/) | @@ -134,7 +119,7 @@ | WCF Storage Queues | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Microsoft.WCF.Azure.StorageQueues/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.WCF.Azure.StorageQueues-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.WCF.Azure.StorageQueues_1.0.0-beta.1/sdk/extension-wcf/Microsoft.WCF.Azure.StorageQueues/) | | Web PubSub | NuGet [1.4.0](https://www.nuget.org/packages/Azure.Messaging.WebPubSub/1.4.0) | [docs](/dotnet/api/overview/azure/Messaging.WebPubSub-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.WebPubSub_1.4.0/sdk/webpubsub/Azure.Messaging.WebPubSub/) | | Web PubSub Client | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Messaging.WebPubSub.Client/1.0.0) | [docs](/dotnet/api/overview/azure/Messaging.WebPubSub.Client-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.WebPubSub.Client_1.0.0/sdk/webpubsub/Azure.Messaging.WebPubSub.Client/) | -| Azure client library integration for ASP.NET Core | NuGet [1.7.5](https://www.nuget.org/packages/Microsoft.Extensions.Azure/1.7.5) | [docs](/dotnet/api/overview/azure/Microsoft.Extensions.Azure-readme) | GitHub [1.7.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Extensions.Azure_1.7.5/sdk/extensions/Microsoft.Extensions.Azure/) | +| Azure client library integration for ASP.NET Core | NuGet [1.7.6](https://www.nuget.org/packages/Microsoft.Extensions.Azure/1.7.6) | [docs](/dotnet/api/overview/azure/Microsoft.Extensions.Azure-readme) | GitHub [1.7.6](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Extensions.Azure_1.7.6/sdk/extensions/Microsoft.Extensions.Azure/) | | Blob Storage Key Store for .NET Data Protection | NuGet [1.3.4](https://www.nuget.org/packages/Azure.Extensions.AspNetCore.DataProtection.Blobs/1.3.4) | [docs](/dotnet/api/overview/azure/Extensions.AspNetCore.DataProtection.Blobs-readme) | GitHub [1.3.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Extensions.AspNetCore.DataProtection.Blobs_1.3.4/sdk/extensions/Azure.Extensions.AspNetCore.DataProtection.Blobs/) | | CloudNative CloudEvents with Event Grid | NuGet [1.0.0](https://www.nuget.org/packages/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/1.0.0) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents_1.0.0/sdk/eventgrid/Microsoft.Azure.Messaging.EventGrid.CloudNativeCloudEvents/) | | Core - Client - Spatial | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.1.0)
NuGet [1.2.0-beta.1](https://www.nuget.org/packages/Microsoft.Azure.Core.Spatial/1.2.0-beta.1) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.Core.Spatial-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial_1.1.0/sdk/core/Microsoft.Azure.Core.Spatial/)
GitHub [1.2.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Core.Spatial_1.2.0-beta.1/sdk/core/Microsoft.Azure.Core.Spatial/) | @@ -152,6 +137,30 @@ | Functions extension for Blob Storage | NuGet [5.3.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/5.3.2) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs-readme) | GitHub [5.3.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs_5.3.2/sdk/storage/Microsoft.Azure.WebJobs.Extensions.Storage.Blobs/) | | Functions extension for Storage Queues | NuGet [5.3.2](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.Storage.Queues/5.3.2) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.Storage.Queues-readme) | GitHub [5.3.2](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.Storage.Queues_5.3.2/sdk/storage/Microsoft.Azure.WebJobs.Extensions.Storage.Queues/) | | unknown | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO_1.0.0-beta.4/sdk/webpubsub/Microsoft.Azure.WebJobs.Extensions.WebPubSubForSocketIO/) | +| Provisioning - App Configuration | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppConfiguration/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppConfiguration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppConfiguration_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.AppConfiguration/) | +| Provisioning - Appcontainers | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppContainers/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppContainers-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppContainers_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.AppContainers/) | +| Provisioning - Application Insights | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ApplicationInsights/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ApplicationInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ApplicationInsights_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.ApplicationInsights/) | +| Provisioning - Appservice | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.AppService/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.AppService-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.AppService_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.AppService/) | +| Provisioning - Cognitive Services | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.CognitiveServices/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.CognitiveServices-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CognitiveServices_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.CognitiveServices/) | +| Provisioning - Communication | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Communication/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Communication-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Communication_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Communication/) | +| Provisioning - Containerregistry | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ContainerRegistry/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ContainerRegistry-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ContainerRegistry_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.ContainerRegistry/) | +| Provisioning - Containerservice | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ContainerService/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ContainerService-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ContainerService_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.ContainerService/) | +| Provisioning - CosmosDB | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.CosmosDB/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.CosmosDB-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.CosmosDB_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.CosmosDB/) | +| Provisioning - Deployment | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Deployment/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Deployment-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Deployment_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Deployment/) | +| Provisioning - Event Hubs | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.EventHubs/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.EventHubs-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.EventHubs_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.EventHubs/) | +| Provisioning - Eventgrid | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.EventGrid/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.EventGrid-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.EventGrid_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.EventGrid/) | +| Provisioning - Key Vault | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.KeyVault/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.KeyVault-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.KeyVault_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.KeyVault/) | +| Provisioning - Kubernetes | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Kubernetes/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Kubernetes-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Kubernetes_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Kubernetes/) | +| Provisioning - Kubernetesconfiguration | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.KubernetesConfiguration/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.KubernetesConfiguration-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.KubernetesConfiguration_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.KubernetesConfiguration/) | +| Provisioning - Operational Insights | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.OperationalInsights/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.OperationalInsights-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.OperationalInsights_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.OperationalInsights/) | +| Provisioning - PostgreSQL | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.PostgreSql/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.PostgreSql-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.PostgreSql_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.PostgreSql/) | +| Provisioning - Redis | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Redis/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Redis-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Redis_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Redis/) | +| Provisioning - Search | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Search/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Search-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Search_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Search/) | +| Provisioning - Service Bus | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.ServiceBus/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.ServiceBus-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.ServiceBus_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.ServiceBus/) | +| Provisioning - SignalR | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.SignalR/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.SignalR-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.SignalR_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.SignalR/) | +| Provisioning - SQL | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Sql/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Sql-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Sql_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Sql/) | +| Provisioning - Storage | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.Storage/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.Storage-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.Storage_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.Storage/) | +| Provisioning - WebPubSub | NuGet [1.0.0-beta.1](https://www.nuget.org/packages/Azure.Provisioning.WebPubSub/1.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Provisioning.WebPubSub-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Provisioning.WebPubSub_1.0.0-beta.1/sdk/provisioning/Azure.Provisioning.WebPubSub/) | | Resource Management - Advisor | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.Advisor/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.Advisor-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.Advisor_1.0.0-beta.4/sdk/advisor/Azure.ResourceManager.Advisor/) | | Resource Management - Agrifood | NuGet [1.0.0-beta.4](https://www.nuget.org/packages/Azure.ResourceManager.AgFoodPlatform/1.0.0-beta.4) | [docs](/dotnet/api/overview/azure/ResourceManager.AgFoodPlatform-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.4](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AgFoodPlatform_1.0.0-beta.4/sdk/agrifood/Azure.ResourceManager.AgFoodPlatform/) | | Resource Management - Alerts Management | NuGet [1.1.0](https://www.nuget.org/packages/Azure.ResourceManager.AlertsManagement/1.1.0) | [docs](/dotnet/api/overview/azure/ResourceManager.AlertsManagement-readme) | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.ResourceManager.AlertsManagement_1.1.0/sdk/alertsmanagement/Azure.ResourceManager.AlertsManagement/) | diff --git a/docs/core/compatibility/9.0.md b/docs/core/compatibility/9.0.md index 8259933d2ca6c..5e7da4f416aea 100644 --- a/docs/core/compatibility/9.0.md +++ b/docs/core/compatibility/9.0.md @@ -60,7 +60,13 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff | Title | Type of change | Introduced version | |-----------------------------------------------------------------------------------|---------------------|--------------------| -| [Deprecated desktop Windows/macOS/Linux MonoVM runtime packages](deployment/9.0/monovm-packages.md) | Source incompatible | Preview 7 | +| [Deprecated desktop Windows/macOS/Linux MonoVM runtime packages](deployment/9.0/monovm-packages.md) | Source incompatible | Preview 7 | + +## Interop + +| Title | Type of change | Introduced version | +|--------------------------------------------------------|---------------------|--------------------| +| [CET supported by default](interop/9.0/cet-support.md) | Binary incompatible | Preview 6 | ## JIT compiler @@ -73,7 +79,7 @@ If you're migrating an app to .NET 9, the breaking changes listed here might aff | Title | Type of change | Introduced version | |-----------------------------------------------------------------------------------|---------------------|--------------------| -| [HttpClientFactory logging redacts header values by default](networking/9.0/redact-headers.md) | Behavioral change | RC 1 | +| [HttpClientFactory logging redacts header values by default](networking/9.0/redact-headers.md) | Behavioral change | RC 1 | | [HttpListenerRequest.UserAgent is nullable](networking/9.0/useragent-nullable.md) | Source incompatible | Preview 1 | ## SDK and MSBuild diff --git a/docs/core/compatibility/interop/9.0/cet-support.md b/docs/core/compatibility/interop/9.0/cet-support.md new file mode 100644 index 0000000000000..5cf8301fa65e6 --- /dev/null +++ b/docs/core/compatibility/interop/9.0/cet-support.md @@ -0,0 +1,44 @@ +--- +title: "Breaking change: CET supported by default" +description: Learn about the breaking change in interop in .NET 9 where CET is supported by default. +ms.date: 10/04/2024 +--- +# CET supported by default + +`apphost` and `singlefilehost` are now marked as Intel CET—compatible (they're compiled with the `/CETCOMPAT` option). This change was made to enhance security of .NET applications. However, it imposes a limitation on the shared libraries that .NET apps can load and interop with. Libraries aren't allowed to set thread context to a location with an instruction pointer that's not present on the shadow stack or in a table of allowed continuation addresses for exception handling. + +## Previous behavior + +Previously, shared libraries loaded into the .NET process were able to set thread context using [SetThreadContext](/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadcontext), [RtlRestoreContext](/windows/win32/api/winnt/nf-winnt-rtlrestorecontext)/`NtContinue`, or their exception handlers to any location in the process address space. + +## New behavior + +Starting in .NET 9, shared libraries loaded into the .NET process are only allowed to set thread context using [SetThreadContext](/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreadcontext), [RtlRestoreContext](/windows/win32/api/winnt/nf-winnt-rtlrestorecontext)/`NtContinue`, or their exception handlers to locations that are either: + +- Present on the shadow stack. +- In a table of allowed continuation addresses for exception handling (generated by the `/EHCONT` compiler option or the `SetProcessDynamicEHContinuationTargets` API). + +If libraries try to change a thread context to any other location, the process is terminated. + +## Version introduced + +.NET 9 Preview 6 + +## Type of breaking change + +This change can affect [binary compatibility](../../categories.md#binary-compatibility). + +## Reason for change + +Enabling CET enhances the security of .NET applications by adding hardware-enforced stack protection that offers robust protection against ROP exploits (return-oriented programming). + +## Recommended action + +Workarounds: + +- You can opt out of CET by adding `false` to your app's project file (for example, *.csproj* file). +- Use the Windows Security app or a group policy to opt out of the hardware-supported stack enforcement for the specific .NET application. For more information, see [Enable exploit protection](/defender-endpoint/enable-exploit-protection). + +## Affected APIs + +- N/A diff --git a/docs/core/compatibility/toc.yml b/docs/core/compatibility/toc.yml index 353756c0f283e..6fd30bbce9f7b 100644 --- a/docs/core/compatibility/toc.yml +++ b/docs/core/compatibility/toc.yml @@ -60,6 +60,10 @@ items: items: - name: Deprecated desktop Windows/macOS/Linux MonoVM runtime packages href: deployment/9.0/monovm-packages.md + - name: Interop + items: + - name: CET supported by default + href: interop/9.0/cet-support.md - name: JIT compiler items: - name: Floating point to integer conversions are saturating @@ -1620,6 +1624,10 @@ items: href: globalization.md - name: Interop items: + - name: .NET 9 + items: + - name: CET supported by default + href: interop/9.0/cet-support.md - name: .NET 8 items: - name: CreateObjectFlags.Unwrap only unwraps on target instance diff --git a/docs/core/deploying/single-file/overview.md b/docs/core/deploying/single-file/overview.md index d0a910d209dca..bbeea52d230ef 100644 --- a/docs/core/deploying/single-file/overview.md +++ b/docs/core/deploying/single-file/overview.md @@ -108,10 +108,6 @@ Visual Studio creates reusable publishing profiles that control how your applica For more information, see [Publish .NET Core apps with Visual Studio](../deploy-with-vs.md). -# [Visual Studio for Mac](#tab/vsmac) - -Visual Studio for Mac doesn't provide options to publish your app as a single file. You'll need to publish manually by following the instructions from the CLI tab. For more information, see [Publish .NET apps with .NET CLI](../deploy-with-cli.md). - --- ## Exclude files from being embedded diff --git a/docs/core/deploying/trimming/trim-self-contained.md b/docs/core/deploying/trimming/trim-self-contained.md index fe053984c4792..fbe624d1974aa 100644 --- a/docs/core/deploying/trimming/trim-self-contained.md +++ b/docs/core/deploying/trimming/trim-self-contained.md @@ -79,10 +79,6 @@ For more information, see [Publish .NET apps with .NET CLI](../deploy-with-cli.m For more information, see [Publish .NET Core apps with Visual Studio](../deploy-with-vs.md). -### Publish with Visual Studio for Mac - -Visual Studio for Mac doesn't provide options to publish your app. You'll need to publish manually by following the instructions from the [Publishing with the CLI](#publish-with-the-cli) section. For more information, see [Publish .NET apps with .NET CLI](../deploy-with-cli.md). - ## See also - [.NET Core application deployment](../index.md). diff --git a/docs/core/install/macos.md b/docs/core/install/macos.md index e4d0f89f1f91e..319ac994b022e 100644 --- a/docs/core/install/macos.md +++ b/docs/core/install/macos.md @@ -192,22 +192,6 @@ The **x64** .NET SDK installs to its own directory, as described in the previous Environment variables that add .NET to system path, such as the `PATH` variable, might need to be changed if you have both the x64 and Arm64 versions of the .NET 6 SDK installed. Additionally, some tools rely on the `DOTNET_ROOT` environment variable, which would also need to be updated to point to the appropriate .NET 6 SDK installation folder. -## Install with Visual Studio for Mac - -Visual Studio for Mac installs the .NET SDK when the **.NET** workload is selected. To get started with .NET development on macOS, see [Install Visual Studio 2022 for Mac](/visualstudio/mac/installation). - -> [!IMPORTANT] -> Visual Studio for Mac is being retired. For more information, see [What's happening to Visual Studio for Mac?](/visualstudio/mac/what-happened-to-vs-for-mac?view=vsmac-2022&preserve-view=true). - -| .NET SDK version | Visual Studio version | -| --------------------- | ----------------------------------------------------------------------------------- | -| 8.0 | Visual Studio 2022 for Mac 17.6.1 or higher. (Available as a preview feature only.) | -| 6.0 | Visual Studio 2022 for Mac 17.0 or higher. | - -:::image type="content" source="media/install-sdk/mac-install-selection.png" alt-text="macOS Visual Studio 2022 for Mac with the .NET workload selected." lightbox="media/install-sdk/mac-install-selection.png"::: - -[!INCLUDE [](~/includes/vs-mac-eol.md)] - ## Install alongside Visual Studio Code Visual Studio Code is a powerful and lightweight source code editor that runs on your desktop. Visual Studio Code is available for Windows, macOS, and Linux. @@ -246,6 +230,5 @@ For more information about using .NET in a Docker container, see [Introduction t - [How to check if .NET is already installed](how-to-detect-installed-versions.md?pivots=os-macos). - [Working with macOS Catalina notarization](macos-notarization-issues.md). -- [Tutorial: Get started on macOS](../tutorials/with-visual-studio-mac.md). - [Tutorial: Create a new app with Visual Studio Code](../tutorials/with-visual-studio-code.md). - [Tutorial: Containerize a .NET app](../docker/build-container.md). diff --git a/docs/core/testing/media/icommandlineoptionsprovider-sequence-diagram.png b/docs/core/testing/media/icommandlineoptionsprovider-sequence-diagram.png new file mode 100644 index 0000000000000..6f69457b7aff6 Binary files /dev/null and b/docs/core/testing/media/icommandlineoptionsprovider-sequence-diagram.png differ diff --git a/docs/core/testing/media/message-bus.png b/docs/core/testing/media/message-bus.png new file mode 100644 index 0000000000000..d26a890eff3b6 Binary files /dev/null and b/docs/core/testing/media/message-bus.png differ diff --git a/docs/core/testing/media/platform-testhost.png b/docs/core/testing/media/platform-testhost.png new file mode 100644 index 0000000000000..3689178a84866 Binary files /dev/null and b/docs/core/testing/media/platform-testhost.png differ diff --git a/docs/core/testing/media/platform-testhostcontroller-testhost.png b/docs/core/testing/media/platform-testhostcontroller-testhost.png new file mode 100644 index 0000000000000..9a5f2302d91f5 Binary files /dev/null and b/docs/core/testing/media/platform-testhostcontroller-testhost.png differ diff --git a/docs/core/testing/media/test-framework-sequence-diagram.png b/docs/core/testing/media/test-framework-sequence-diagram.png new file mode 100644 index 0000000000000..41c5faa1411ed Binary files /dev/null and b/docs/core/testing/media/test-framework-sequence-diagram.png differ diff --git a/docs/core/testing/unit-testing-platform-architecture-capabilities.md b/docs/core/testing/unit-testing-platform-architecture-capabilities.md new file mode 100644 index 0000000000000..a0fc4629e45b7 --- /dev/null +++ b/docs/core/testing/unit-testing-platform-architecture-capabilities.md @@ -0,0 +1,126 @@ +--- +title: Microsoft.Testing.Platform capabilities overview +description: Learn about Microsoft.Testing.Platform capabilities concept. +author: MarcoRossignoli +ms.author: mrossignoli +ms.date: 07/11/2024 +--- + +# Microsoft.Testing.Platform capabilities + +In the context of the testing platform, a *capability* refers to the *potential to perform a specific action or provide specific information*. It's a means for the testing framework and extensions to *declare* their *ability* to *operate* in a certain manner or provide specific information to the *requesters*. + +The *requesters* can be any component involved in a test session, such as the platform, an extension, or the testing framework itself. + +The primary objective of the capability system is to facilitate effective communication among the components involved in a test session, enabling them to exchange information and meet their respective needs accurately. + +## Guided example + +Let's consider a hypothetical example to demonstrate the necessity of a capability system. + +> [!NOTE] +> This example is purely for illustrative purposes and isn't currently implemented within the testing platform or any testing framework. + +Imagine a situation where you have an extension that requires the testing framework to execute no more than one test at a time. Furthermore, after each test, the extension needs to know the CPU usage for that specific test. + +To accommodate the preceding scenario, you need to inquire from the testing framework if: + +1. It has the capability to execute only one test at a time. +2. It can provide information regarding the amount of CPU consumed by each test. + +How can the extension determine if the testing framework has the ability to operate in this mode and provide CPU usage information for a test session? In the testing platform, this capability is represented by an implementation the `Microsoft.Testing.Platform.Capabilities.ICapability` interface: + +```csharp +// Base capabilities contracts + +public interface ICapability +{ +} + +public interface ICapabilities + where TCapability : ICapability +{ + IReadOnlyCollection Capabilities { get; } +} + +// Specific testing framework capabilities + +public interface ITestFrameworkCapabilities : ICapabilities +{ +} + +public interface ITestFrameworkCapability : ICapability +{ +} +``` + +As you can see, the `ICapability` interface is a *marker* interface because it can represent *any capability*, and the actual implementation will be context dependent. You'll also observe the `ITestFrameworkCapability`, which inherits from `ICapability` to classify the capability. The capability system's generic nature allows for convenient grouping by context. The `ITestFrameworkCapability` groups all the capabilities implemented by the [testing framework](./unit-testing-platform-architecture-extensions.md#create-a-testing-framework). The `ICapabilities` interface reveals the *set* of all capabilities implemented by an extension. Similarly, for the base one, there's a context-specific testing framework called `ITestFrameworkCapabilities`. The `ITestFrameworkCapabilities` is provided to the platform during the [testing framework registration](./unit-testing-platform-architecture-extensions.md#register-a-testing-framework) process. + +To create a capability that addresses the aforementioned scenario, you define it as follows: + +```csharp +public interface IDisableParallelismCapability : ITestFrameworkCapability +{ + bool CanDisableParallelism { get; } + bool CanProvidePerTestCpuConsumption { get; } + void Enable(); +} +``` + +If the testing framework implements this interface, at runtime, the following can be queried: + +* Verify if the testing framework has the ability to turn off parallelism `CanDisableParallelism = true`. +* Determine if the testing framework can supply CPU usage data `CanProvidePerTestCPUConsumption = true`. +* Request the testing adapter to activate this mode by invoking the `Enable()` method before the test session commences. + +The hypothetical code fragment inside the extension could be something like: + +```csharp +IServiceProvider provider = null; // TODO: Get IServiceProvider. +var capabilities = serviceProvider.GetRequiredService(); + +// Utilize the `GetCapability` API to search for the specific capability to query. +var capability = capabilities.GetCapability(); +if (capability is null) +{ + // Capability not supported... +} +else +{ + capability.Enable(); + if (capability.CanDisableParallelism) + { + // Do something... + } + + if (capability.CanProvidePerTestCpuConsumption) + { + // Do something... + } +} +``` + +The preceding example illustrates how the capability infrastructure enables a powerful mechanism for communicating abilities between the components involved in a test session. While the sample demonstrates a capability specifically designed for the testing framework, any component can expose and implement extensions that inherit from `ICapability`. + +It's evident that not all details can be communicated through an interface. Considering the previous example, what should the extension expect if the `CanProvidePerTestCpuConsumption` is supported? What kind of custom information is expected to be transmitted via the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service) by the testing framework? The solution is **documentation of the capability**. It's the responsibility of the capability *owner* to design, ship, and document it as clearly as possible to assist implementors who want to effectively *collaborate* with the extension that requires the specific capability. + +For instance, the TRX report extension enables the testing framework to implement the necessary capability to accurately generate a TRX report. The extension to register is included in the NuGet package, but the capability to implement is found in the *contract only* NuGet package. + +In conclusion, let's summarize the primary aspects of the capability system: + +* It's essential for facilitating clear and stable communication between components. +* All capabilities should inherit from `ICapability` or an interface that inherits from it, and are exposed through a collection with the `ICapabilities` interface. +* It aids in the evolution of features without causing breaking changes. If a certain capability isn't supported, appropriate action can be taken. +* The responsibility of designing, shipping, and documenting the usage of a capability lies with the *capability owner*. The testing platform can also *own* a capability in the same way as any other extension. + +## Framework capabilities + +The platform exposes a specialized interface named `ITestFrameworkCapability` that is the base of all capabilities exposed for test frameworks. These capabilities are provided when [registering the test framework to the platform](./unit-testing-platform-architecture-extensions.md#register-a-testing-framework). + +### `IBannerMessageOwnerCapability` + +An optional [test framework capability](#framework-capabilities) that allows the test framework to provide the banner message to the platform. If the message is `null` or if the capability is n't present, the platform will use its default banner message. + +This capability implementation allows you to abstract away the various conditions that the test framework may need to consider when deciding whether or not the banner message should be displayed. + +The platform exposes the [`IPlatformInformation` service](./unit-testing-platform-architecture-services.md#the-iplatforminformation-service) to provide some information about the platform that could be useful when building your custom banner message. diff --git a/docs/core/testing/unit-testing-platform-architecture-extensions.md b/docs/core/testing/unit-testing-platform-architecture-extensions.md new file mode 100644 index 0000000000000..328124254dc0a --- /dev/null +++ b/docs/core/testing/unit-testing-platform-architecture-extensions.md @@ -0,0 +1,1351 @@ +--- +title: Microsoft.Testing.Platform extensions architecture overview +description: Learn about how to extend Microsoft.Testing.Platform. +author: MarcoRossignoli +ms.author: mrossignoli +ms.date: 07/11/2024 +--- + +# Microsoft.Testing.Platform extensibility + +The testing platform consists of a [testing framework](#test-framework-extension) and any number of [extensions](#other-extensibility-points) that can operate *in-process* or *out-of-process*. + +As outlined in the [architecture](./unit-testing-platform-architecture.md) section, the testing platform is designed to accommodate a variety of scenarios and extensibility points. The primary and essential extension is undoubtedly the [testing framework](#test-framework-extension) that your tests will utilize. Failing to register this results in startup error. **The [testing framework](#test-framework-extension) is the sole mandatory extension required to execute a testing session.** + +To support scenarios such as generating test reports, code coverage, retrying failed tests, and other potential features, you need to provide a mechanism that allows other extensions to work in conjunction with the [testing framework](#test-framework-extension) to deliver these features not inherently provided by the [testing framework](#test-framework-extension) itself. + +In essence, the [testing framework](#test-framework-extension) is the primary extension that supplies information about each test that makes up the test suite. It reports whether a specific test has succeeded, failed, skipped, and can provide additional information about each test, such as a human-readable name (referred to as the display name), the source file, and the line where our test begins, among other things. + +The extensibility point enables the utilization of information provided by the [testing framework](#test-framework-extension) to generate new artifacts or to enhance existing ones with additional features. A commonly used extension is the TRX report generator, which subscribes to the [TestNodeUpdateMessage](#the-testnodeupdatemessage-data) and generates an XML report file from it. + +As discussed in the [architecture](./unit-testing-platform-architecture.md), there are certain extension points that *cannot* operate within the same process as the [testing framework](#test-framework-extension). The reasons typically include: + +* The need to modify the *environment variables* of the *test host*. Acting within the test host process itself is *too late*. +* The requirement to *monitor* the process from the outside because the *test host*, where tests and user code run, might have some *user code bugs* that render the process itself *unstable*, leading to potential *hangs* or *crashes*. In such cases, the extension would crash or hang along with the *test host* process. + +Due to these reasons, the extension points are categorized into two types: + +1. *In-process extensions*: These extensions operate within the same process as the [testing framework](#test-framework-extension). + + You can register *in-process extensions* via the `ITestApplicationBuilder.TestHost` property: + + ```csharp + // ... + var builder = await TestApplication.CreateBuilderAsync(args); + builder.TestHost.AddXXX(...); + // ... + ``` + +1. *Out-of-process extensions*: These extensions function in a separate process, allowing them to monitor the test host without being influenced by the test host itself. + + You can register *out-of-process extensions* via the `ITestApplicationBuilder.TestHostControllers`. + + ```csharp + var builder = await TestApplication.CreateBuilderAsync(args); + builder.TestHostControllers.AddXXX(...); + ``` + + Lastly, some extensions are designed to function in both scenarios. These common extensions behave identically in both *hosts*. You can register these extensions either through the *TestHost* and *TestHostController* interfaces or directly at the `ITestApplicationBuilder` level. An example of such an extension is the [ICommandLineOptionsProvider](#the-icommandlineoptionsprovider-extensions). + +## The `IExtension` interface + +The `IExtension` interface serves as the foundational interface for all extensibility points within the testing platform. It's primarily used to obtain descriptive information about the extension and, most importantly, to enable or disable the extension itself. + +Consider the following `IExension` interface: + +```csharp +public interface IExtension +{ + string Uid { get; } + string Version { get; } + string DisplayName { get; } + string Description { get; + Task IsEnabledAsync(); +} +``` + +* `Uid`: Represents the unique identifier for the extension. It's crucial to choose a unique value for this string to avoid conflicts with other extensions. + +* `Version`: Represents the version of the interface. Requires [**semantic versioning**](https://semver.org/). + +* `DisplayName`: A user-friendly name representation that will appear in logs and when you request information using the `--info` command line option. + +* `Description`: The description of the extension, that appears when you request information using the `--info` command line option. + +* `IsEnabledAsync()`: This method is invoked by the testing platform when the extension is being instantiated. If the method returns `false`, the extension will be excluded. This method typically makes decisions based on the [configuration file](./unit-testing-platform-architecture-services.md#the-iconfiguration-service) or some [custom command line options](./unit-testing-platform-architecture-services.md#the-icommandlineoptions-service). Users often specify `--customExtensionOption` in the command line to opt into the extension itself. + +## Test Framework extension + +The test framework is the primary extension that provides the testing platform with the ability to discover and execute tests. The test framework is responsible for communicating the results of the tests back to the testing platform. The test framework is the only mandatory extension required to execute a testing session. + +### Register a testing framework + +This section explains how to register the test framework with the testing platform. You register only one testing framework per test application builder using the `TestApplication.RegisterTestFramework` API as shown in [the testing platform architecture](./unit-testing-platform-architecture.md) documentation. + +The registration API is defined as follows: + +```csharp +ITestApplicationBuilder RegisterTestFramework( + Func capabilitiesFactory, + Func adapterFactory); +``` + +The `RegisterTestFramework` API expects two factories: + +1. `Func`: This is a delegate that accepts an object implementing the [`IServiceProvider`](./unit-testing-platform-architecture-services.md) interface and returns an object implementing the [`ITestFrameworkCapabilities`](./unit-testing-platform-architecture-capabilities.md) interface. The [`IServiceProvider`](./unit-testing-platform-architecture-services.md#the-imessagebus-service) provides access to platform services such as configurations, loggers, and command line arguments. + + The [`ITestFrameworkCapabilities`](./unit-testing-platform-architecture-capabilities.md) interface is used to announce the capabilities supported by the testing framework to the platform and extensions. It allows the platform and extensions to interact correctly by implementing and supporting specific behaviors. For a better understanding of the [concept of capabilities](./unit-testing-platform-architecture-capabilities.md), refer to the respective section. + +1. `Func`: This is a delegate that takes in an [ITestFrameworkCapabilities](./unit-testing-platform-architecture-capabilities.md) object, which is the instance returned by the `Func`, and an [IServiceProvider](./unit-testing-platform-architecture-services.md#the-imessagebus-service) to provide access to platform services once more. The expected return object is one that implements the [ITestFramework](#test-framework-extension) interface. The `ITestFramework` serves as the execution engine that discovers and runs tests, and then communicates the results back to the testing platform. + +The need for the platform to separate the creation of the [`ITestFrameworkCapabilities`](./unit-testing-platform-architecture-capabilities.md) and the creation of the [ITestFramework](#test-framework-extension) is an optimization to avoid creating the test framework if the supported capabilities are not sufficient to execute the current testing session. + +Consider the following user code example, which demonstrates a test framework registration that returns an empty capability set: + +```csharp +internal class TestingFrameworkCapabilities : ITestFrameworkCapabilities +{ + public IReadOnlyCollection Capabilities => []; +} + +internal class TestingFramework : ITestFramework +{ + public TestingFramework(ITestFrameworkCapabilities capabilities, IServiceProvider serviceProvider) + { + // ... + } + // Omitted for brevity... +} + +public static class TestingFrameworkExtensions +{ + public static void AddTestingFramework(this ITestApplicationBuilder builder) + { + builder.RegisterTestFramework( + _ => new TestingFrameworkCapabilities(), + (capabilities, serviceProvider) => new TestingFramework(capabilities, serviceProvider)); + } +} + +// ... +``` + +Now, consider the corresponding entry point of this example with the registration code: + +```csharp +var testApplicationBuilder = await TestApplication.CreateBuilderAsync(args); +// Register the testing framework +testApplicationBuilder.AddTestingFramework(); +using var testApplication = await testApplicationBuilder.BuildAsync(); +return await testApplication.RunAsync(); +``` + +> [!NOTE] +> Returning empty [ITestFrameworkCapabilities](./unit-testing-platform-architecture-capabilities.md) shouldn't prevent the execution of the test session. All test frameworks should be capable of discovering and running tests. The impact should be limited to extensions that may opt-out if the test framework lacks a certain feature. + +### Create a testing framework + +The `Microsoft.Testing.Platform.Extensions.TestFramework.ITestFramework` is implemented by extensions that provide a test framework: + +```csharp +public interface ITestFramework : IExtension +{ + Task CreateTestSessionAsync(CreateTestSessionContext context); + Task ExecuteRequestAsync(ExecuteRequestContext context); + Task CloseTestSessionAsync(CloseTestSessionContext context); +} +``` + +The `ITestFramework` interface inherits from the [IExtension](#the-iextension-interface) interface, which is an interface that all extension points inherit from. `IExtension` is used to retrieve the name and description of the extension. The `IExtension` also provides a way to dynamically enable or disable the extension in setup, through `Task IsEnabledAsync()`. Please make sure that you return `true` from this method if you have no special needs. + +#### The `CreateTestSessionAsync` method + +The `CreateTestSessionAsync` method is called at the start of the test session and is used to initialize the test framework. The API accepts a `CloseTestSessionContext` object and returns a `CloseTestSessionResult`. + +```csharp +public sealed class CreateTestSessionContext : TestSessionContext +{ + public SessionUid SessionUid { get; } + public ClientInfo Client { get; } + public CancellationToken CancellationToken { get; } +} + +public readonly struct SessionUid +{ + public string Value { get; } +} + +public sealed class ClientInfo +{ + public string Id { get; } + public string Version { get; } +} +``` + +The `SessionUid` serves as the unique identifier for the current test session, providing a logical connection to the session's results. +The `ClientInfo` provides details about the entity invoking the test framework. This information can be utilized by the test framework to modify its behavior. For example, as of the time this document was written, a console execution would report a client name such as "testingplatform-console". +The `CancellationToken` is used to halt the execution of `CreateTestSessionAsync`. + +The return object is a `CloseTestSessionResult`: + +```csharp +public sealed class CreateTestSessionResult +{ + public string? WarningMessage { get; set; } + public string? ErrorMessage { get; set; } + public bool IsSuccess { get; set; } +} +``` + +The `IsSuccess` property is used to indicate whether the session creation was successful. When it returns `false`, the test execution is halted. + +#### The `CloseTestSessionAsync` method + +The `CloseTestSessionAsync` method is juxtaposed to the `CreateTestSessionAsync` in functionality, with the only difference being the object names. For more information, see the `CreateTestSessionAsync` section. + +#### The `ExecuteRequestAsync` method + +The `ExecuteRequestAsync` method accepts an object of type `ExecuteRequestContext`. This object, as suggested by its name, holds the specifics about the action that the test framework is expected to perform. +The `ExecuteRequestContext` definition is: + +```csharp +public sealed class ExecuteRequestContext +{ + public IRequest Request { get; } + public IMessageBus MessageBus { get; } + public CancellationToken CancellationToken { get; } + public void Complete(); +} +``` + +`IRequest`: This is the base interface for any type of request. You should think about the test framework as an **in-process stateful server** where the lifecycle is: + + +:::image type="content" source="./media/test-framework-sequence-diagram.png" lightbox="./media/test-framework-sequence-diagram.png" alt-text="A sequence diagram representing the lifecycle of the test framework."::: + +The preceding diagram illustrates that the testing platform issues three requests after creating the test framework instance. The test framework processes these requests and utilizes the `IMessageBus` service, which is included in the request itself, to deliver the result for each specific request. Once a particular request has been handled, the test framework invokes the `Complete()` method on it, indicating to the testing platform that the request has been fulfilled. +The testing platform monitors all dispatched requests. Once all requests have been fulfilled, it invokes `CloseTestSessionAsync` and disposes of the instance (if `IDisposable/IAsyncDisposable` is implemented). +It's evident that the requests and their completions can overlap, enabling concurrent and asynchronous execution of requests. + +> [!NOTE] +> Currently, the testing platform does not send overlapping requests and waits for the completion of a request >> before sending the next one. However, this behavior may change in the future. The support for concurrent requests will be determined through the [capabilities](./unit-testing-platform-architecture-capabilities.md) system. + +The `IRequest` implementation specifies the precise request that needs to be fulfilled. The test framework identifies the type of request and handles it accordingly. If the request type is unrecognized, an exception should be raised. + +You can find details about the available requests in the [IRequest](#handling-requests) section. + +`IMessageBus`: This service, linked with the request, allows the test framework to *asynchronously* to publish information about the ongoing request to the testing platform. +The message bus serves as the central hub for the platform, facilitating asynchronous communication among all platform components and extensions. +For a comprehensive list of information that can be published to the testing platform, refer to the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service) section. + +`CancellationToken`: This token is utilized to interrupt the processing of a particular request. + +`Complete()`: As depicted in the previous sequence, the `Complete` method notifies the platform that the request has been successfully processed and all relevant information has been transmitted to the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service). + +> [!WARNING] +> Neglecting to invoke `Complete()` on the request will result in the test application becoming unresponsive. + +To customize your test framework according to your requirements or those of your users, you can use a personalized section inside the [configuration](./unit-testing-platform-architecture-services.md#the-iconfiguration-service) file or with custom [command line options](#the-icommandlineoptionsprovider-extensions). + +### Handling requests + +The subsequent section provides a detailed description of the various requests that a test framework may receive and process. + +Before proceeding to the next section, it's crucial to thoroughly comprehend the concept of the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service), which is the essential service for conveying test execution information to the testing platform. + +#### TestSessionContext + +The `TestSessionContext` is a shared property across all requests, providing information about the ongoing test session: + +```csharp +public class TestSessionContext +{ + public SessionUid SessionUid { get; } + public ClientInfo Client { get; } +} + +public readonly struct SessionUid(string value) +{ + public string Value { get; } +} + +public sealed class ClientInfo +{ + public string Id { get; } + public string Version { get; } +} +``` + +The `TestSessionContext` consists of the `SessionUid`, a unique identifier for the ongoing test session that aids in logging and correlating test session data. It also includes the `ClientInfo` type, which provides details about the *initiator* of the test session. The test framework may choose different routes or publish varying information based on the identity of the test session's *initiator*. + +#### DiscoverTestExecutionRequest + +```csharp +public class DiscoverTestExecutionRequest +{ + // Detailed in the custom section below + public TestSessionContext Session { get; } + + // This is experimental and intended for future use, please disregard for now. + public ITestExecutionFilter Filter { get; } +} +``` + +The `DiscoverTestExecutionRequest` instructs the test framework **to discover** the tests and communicate this information thought to the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service). + +As outlined in the previous section, the property for a discovered test is `DiscoveredTestNodeStateProperty`. Here is a generic code snippet for reference: + +```csharp +var testNode = new TestNode +{ + Uid = GenerateUniqueStableId(), + DisplayName = GetDisplayName(), + Properties = new PropertyBag( + DiscoveredTestNodeStateProperty.CachedInstance), +}; + +await context.MessageBus.PublishAsync( + this, + new TestNodeUpdateMessage( + discoverTestExecutionRequest.Session.SessionUid, + testNode)); + +// ... +``` + +#### RunTestExecutionRequest + +```csharp +public class RunTestExecutionRequest +{ + // Detailed in the custom section below + public TestSessionContext Session { get; } + + // This is experimental and intended for future use, please disregard for now. + public ITestExecutionFilter Filter { get; } +} +``` + +The `RunTestExecutionRequest` instructs the test framework **to execute** the tests and communicate this information thought to the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service). + +Here is a generic code snippet for reference: + +```csharp +var skippedTestNode = new TestNode() +{ + Uid = GenerateUniqueStableId(), + DisplayName = GetDisplayName(), + Properties = new PropertyBag( + SkippedTestNodeStateProperty.CachedInstance), +}; + +await context.MessageBus.PublishAsync( + this, + new TestNodeUpdateMessage( + runTestExecutionRequest.Session.SessionUid, + skippedTestNode)); + +// ... + +var successfulTestNode = new TestNode() +{ + Uid = GenerateUniqueStableId(), + DisplayName = GetDisplayName(), + Properties = new PropertyBag( + PassedTestNodeStateProperty.CachedInstance), +}; + +await context.MessageBus.PublishAsync( + this, + new TestNodeUpdateMessage( + runTestExecutionRequest.Session.SessionUid, + successfulTestNode)); + +// ... + +var assertionFailedTestNode = new TestNode() +{ + Uid = GenerateUniqueStableId(), + DisplayName = GetDisplayName(), + Properties = new PropertyBag( + new FailedTestNodeStateProperty(assertionException)), +}; + +await context.MessageBus.PublishAsync( + this, + new TestNodeUpdateMessage( + runTestExecutionRequest.Session.SessionUid, + assertionFailedTestNode)); + +// ... + +var failedTestNode = new TestNode() +{ + Uid = GenerateUniqueStableId(), + DisplayName = GetDisplayName(), + Properties = new PropertyBag( + new ErrorTestNodeStateProperty(ex.InnerException!)), +}; + +await context.MessageBus.PublishAsync( + this, + new TestNodeUpdateMessage( + runTestExecutionRequest.Session.SessionUid, + failedTestNode)); +``` + +### The `TestNodeUpdateMessage` data + +As mentioned in the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service) section, before utilizing the message bus, you must specify the type of data you intend to supply. The testing platform has defined a well-known type, `TestNodeUpdateMessage`, to represent the concept of a *test update information*. + +This part of the document will explain how to utilize this payload data. Let's examine the surface: + +```csharp +public sealed class TestNodeUpdateMessage( + SessionUid sessionUid, + TestNode testNode, + TestNodeUid? parentTestNodeUid = null) +{ + public TestNode TestNode { get; } + public TestNodeUid? ParentTestNodeUid { get; } +} + +public class TestNode +{ + public required TestNodeUid Uid { get; init; } + public required string DisplayName { get; init; } + public PropertyBag Properties { get; init; } = new(); +} + +public sealed class TestNodeUid(string value) + +public sealed partial class PropertyBag +{ + public PropertyBag(); + public PropertyBag(params IProperty[] properties); + public PropertyBag(IEnumerable properties); + public int Count { get; } + public void Add(IProperty property); + public bool Any(); + public TProperty? SingleOrDefault(); + public TProperty Single(); + public TProperty[] OfType(); + public IEnumerable AsEnumerable(); + public IEnumerator GetEnumerator(); + ... +} + +public interface IProperty +{ +} +``` + +* `TestNodeUpdateMessage`: The `TestNodeUpdateMessage` consists of two properties: a `TestNode` and a `ParentTestNodeUid`. The `ParentTestNodeUid` indicates that a test may have a parent test, introducing the concept of a **test tree** where `TestNode`s can be arranged in relation to each other. This structure allows for future enhancements and features based on the *tree* relationship between the nodes. If your test framework doesn't require a test tree structure, you can opt not to use it and simply set it to null, resulting in a straightforward flat list of `TestNode`s. + +* `TestNode`: The `TestNode` is composed of three properties, one of which is the `Uid` of type `TestNodeUid`. This `Uid` serves as the **UNIQUE STABLE ID** for the node. The term **UNIQUE STABLE ID** implies that the same `TestNode` should maintain an **IDENTICAL** `Uid` across different runs and operating systems. The `TestNodeUid` is an **arbitrary opaque string** that the testing platform accepts as is. + +> [!IMPORTANT] +> The stability and uniqueness of the ID are crucial in the testing domain. They enable the precise targeting of a single test for execution and allow the ID to serve as a persistent identifier for a test, facilitating powerful extensions and features. + +The second property is `DisplayName`, which is the human-friendly name for the test. For example, this name is displayed when you execute the `--list-tests` command line. + +The third attribute is `Properties`, which is a `PropertyBag` type. As demonstrated in the code, this is a specialized property bag that holds generic properties about the `TestNodeUpdateMessage`. This implies that you can append any property to the node that implements the placeholder interface `IProperty`. + +***The testing platform identifies specific properties added to a `TestNode.Properties` to determine whether a test has passed, failed, or been skipped.*** + +You can find the current list of available properties with the relative description in the section [TestNodeUpdateMessage.TestNode](#the-testnodeupdatemessage-data) + +The `PropertyBag` type is typically accessible in every `IData` and is utilized to store miscellaneous properties that can be queried by the platform and extensions. This mechanism allows us to enhance the platform with new information without introducing breaking changes. If a component recognizes the property, it can query it; otherwise, it will disregard it. + +Finally this section makes clear that you test framework implementation needs to implement the `IDataProducer` that produces `TestNodeUpdateMessage`s like in the sample below: + +```csharp +internal sealed class TestingFramework + : ITestFramework, IDataProducer +{ + // ... + + public Type[] DataTypesProduced => + [ + typeof(TestNodeUpdateMessage) + ]; + + // ... +} +``` + +If your test adapter requires the publication of *files* during execution, you can find the recognized properties in this source file: . As you can see, you can provide file assets in a general manner or associate them with a specific `TestNode`. Remember, if you intend to push a `SessionFileArtifact`, you must declare it to the platform in advance, as shown below: + +```csharp +internal sealed class TestingFramework + : ITestFramework, IDataProducer +{ + // ... + + public Type[] DataTypesProduced => + [ + typeof(TestNodeUpdateMessage), + typeof(SessionFileArtifact) + ]; + + // ... +} +``` + +#### Well-known properties + +As detailed in the [requests section](#handling-requests), the testing platform identifies specific properties added to the `TestNodeUpdateMessage` to determine the status of a `TestNode` (e.g., successful, failed, skipped, etc.). This allows the runtime to accurately display a list of failed tests with their corresponding information in the console, and to set the appropriate exit code for the test process. + +In this segment, we'll elucidate the various well-known `IProperty` options and their respective implications. + +If you're looking for a comprehensive list of well-known properties, you can find it [here](https://github.com/microsoft/testfx/blob/main/src/Platform/Microsoft.Testing.Platform/Messages/TestNodeProperties.cs). If you notice that a property description is missing, please don't hesitate to file an issue. + +These properties can be divided in the following categories: + +1. [*Generic information*](#generic-information): Properties that can be included in any kind of request. +1. [*Discovery information*](#discovery-information): Properties that are supplied during a `DiscoverTestExecutionRequest` discovery request. +1. [*Execution information*](#execution-information): Properties that are supplied during a test execution request `RunTestExecutionRequest`. + +Certain properties are **required**, while others are optional. The mandatory properties are required to provide basic testing functionality, such as reporting failed tests and indicating whether the entire test session was successful or not. + +Optional properties, on the other hand, enhance the testing experience by providing additional information. They are particularly useful in IDE scenarios (like VS, VSCode, etc.), console runs, or when supporting specific extensions that require more detailed information to function correctly. However, these optional properties do not affect the execution of the tests. + +> [!NOTE] +> Extensions are tasked with alerting and managing exceptions when they require specific information to operate correctly. If an extension lacks the necessary information, it should not cause the test execution to fail, but rather, it should simply opt-out. + +##### Generic information + +```csharp +public record KeyValuePairStringProperty( + string Key, + string Value) + : IProperty; +``` + +The `KeyValuePairStringProperty` stands for a general key/value pair data. + +```csharp +public record struct LinePosition( + int Line, + int Column); + +public record struct LinePositionSpan( + LinePosition Start, + LinePosition End); + +public abstract record FileLocationProperty( + string FilePath, + LinePositionSpan LineSpan) + : IProperty; + +public sealed record TestFileLocationProperty( + string FilePath, + LinePositionSpan LineSpan) + : FileLocationProperty(FilePath, LineSpan); +``` + +`TestFileLocationProperty` is used to pinpoint the location of the test within the source file. This is particularly useful when the initiator is an IDE like Visual Studio or Visual Studio Code. + +```csharp +public sealed record TestMethodIdentifierProperty( + string AssemblyFullName, + string Namespace, + string TypeName, + string MethodName, + string[] ParameterTypeFullNames, + string ReturnTypeFullName) +``` + +`TestMethodIdentifierProperty` is a unique identifier for a test method, adhering to the ECMA-335 standard. + +> [!NOTE] +> The data needed to create this property can be conveniently obtained using the .NET reflection feature, using types from the `System.Reflection` namespace. + +```csharp +public sealed record TestMetadataProperty( + string Key, + string Value) +``` + +`TestMetadataProperty` is utilized to convey the characteristics or *traits* of a `TestNode`. + +##### Discovery information + +```csharp +public sealed record DiscoveredTestNodeStateProperty( + string? Explanation = null) +{ + public static DiscoveredTestNodeStateProperty CachedInstance { get; } +} +``` + +The `DiscoveredTestNodeStateProperty` indicates that this TestNode has been discovered. It is utilized when a `DiscoverTestExecutionRequest` is sent to the test framework. +Take note of the handy cached value offered by the `CachedInstance` property. +This property is **required**. + +##### Execution information + +```csharp +public sealed record InProgressTestNodeStateProperty( + string? Explanation = null) +{ + public static InProgressTestNodeStateProperty CachedInstance { get; } +} +``` + +The `InProgressTestNodeStateProperty` informs the testing platform that the `TestNode` has been scheduled for execution and is currently in progress. +Take note of the handy cached value offered by the `CachedInstance` property. + +```csharp +public readonly record struct TimingInfo( + DateTimeOffset StartTime, + DateTimeOffset EndTime, + TimeSpan Duration); + +public sealed record StepTimingInfo( + string Id, + string Description, + TimingInfo Timing); + +public sealed record TimingProperty : IProperty +{ + public TimingProperty(TimingInfo globalTiming) + : this(globalTiming, []) + { + } + + public TimingProperty( + TimingInfo globalTiming, + StepTimingInfo[] stepTimings) + { + GlobalTiming = globalTiming; + StepTimings = stepTimings; + } + + public TimingInfo GlobalTiming { get; } + + public StepTimingInfo[] StepTimings { get; } +} +``` + +The `TimingProperty` is utilized to relay timing details about the `TestNode` execution. It also allows for the timing of individual execution steps via `StepTimingInfo`. This is particularly useful when your test concept is divided into multiple phases such as initialization, execution, and cleanup. + +***One and only one*** of the following properties is **required** per `TestNode` and communicates the result of the `TestNode` to the testing platform. + +```csharp +public sealed record PassedTestNodeStateProperty( + string? Explanation = null) + : TestNodeStateProperty(Explanation) +{ + public static PassedTestNodeStateProperty CachedInstance + { get; } = new PassedTestNodeStateProperty(); +} +``` + +`PassedTestNodeStateProperty` informs the testing platform that this `TestNode` is passed. +Take note of the handy cached value offered by the `CachedInstance` property. + +```csharp +public sealed record SkippedTestNodeStateProperty( + string? Explanation = null) + : TestNodeStateProperty(Explanation) +{ + public static SkippedTestNodeStateProperty CachedInstance + { get; } = new SkippedTestNodeStateProperty(); +} +``` + +`SkippedTestNodeStateProperty` informs the testing platform that this `TestNode` was skipped. +Take note of the handy cached value offered by the `CachedInstance` property. + +```csharp +public sealed record FailedTestNodeStateProperty : TestNodeStateProperty +{ + public FailedTestNodeStateProperty() + : base(default(string)) + { + } + + public FailedTestNodeStateProperty(string explanation) + : base(explanation) + { + } + + public FailedTestNodeStateProperty( + Exception exception, + string? explanation = null) + : base(explanation ?? exception.Message) + { + Exception = exception; + } + + public Exception? Exception { get; } +} +``` + +`FailedTestNodeStateProperty` informs the testing platform that this `TestNode` is failed after an assertion. + +```csharp +public sealed record ErrorTestNodeStateProperty : TestNodeStateProperty +{ + public ErrorTestNodeStateProperty() + : base(default(string)) + { + } + + public ErrorTestNodeStateProperty(string explanation) + : base(explanation) + { + } + + public ErrorTestNodeStateProperty( + Exception exception, + string? explanation = null) + : base(explanation ?? exception.Message) + { + Exception = exception; + } + + public Exception? Exception { get; } +} +``` + +`ErrorTestNodeStateProperty` informs the testing platform that this `TestNode` has failed. This type of failure is different from the `FailedTestNodeStateProperty`, which is used for assertion failures. For example, you can report issues like test initialization errors with `ErrorTestNodeStateProperty`. + +```csharp +public sealed record TimeoutTestNodeStateProperty : TestNodeStateProperty +{ + public TimeoutTestNodeStateProperty() + : base(default(string)) + { + } + + public TimeoutTestNodeStateProperty(string explanation) + : base(explanation) + { + } + + public TimeoutTestNodeStateProperty( + Exception exception, + string? explanation = null) + : base(explanation ?? exception.Message) + { + Exception = exception; + } + + public Exception? Exception { get; } + + public TimeSpan? Timeout { get; init; } +} +``` + +`TimeoutTestNodeStateProperty` informs the testing platform that this `TestNode` is failed for a timeout reason. You can report the timeout using the `Timeout` property. + +```csharp +public sealed record CancelledTestNodeStateProperty : TestNodeStateProperty +{ + public CancelledTestNodeStateProperty() + : base(default(string)) + { + } + + public CancelledTestNodeStateProperty(string explanation) + : base(explanation) + { + } + + public CancelledTestNodeStateProperty( + Exception exception, + string? explanation = null) + : base(explanation ?? exception.Message) + { + Exception = exception; + } + + public Exception? Exception { get; } +} +``` + +`CancelledTestNodeStateProperty` informs the testing platform that this `TestNode` has failed due to cancellation. + +## Other extensibility points + +The testing platform provides additional extensibility points that allow you to customize the behavior of the platform and the test framework. These extensibility points are optional and can be used to enhance the testing experience. + +### The `ICommandLineOptionsProvider` extensions + +> [!NOTE] +> When extending this API, the custom extension will exists both in and out of the test host process. + +As discussed in the [architecture](./unit-testing-platform-architecture.md) section, the initial step involves creating the `ITestApplicationBuilder` to register the testing framework and extensions with it. + +```csharp +var builder = await TestApplication.CreateBuilderAsync(args); +``` + +The `CreateBuilderAsync` method accepts an array of strings (`string[]`) named `args`. These arguments can be used to pass command-line options to all components of the testing platform (including built-in components, testing frameworks, and extensions), allowing for customization of their behavior. + +Typically, the arguments passed are those received in the standard `Main(string[] args)` method. However, if the hosting environment differs, any list of arguments can be supplied. + +Arguments **must be prefixed** with a double dash `--`. For example, `--filter`. + +If a component such as a testing framework or an extension point wishes to offer custom command-line options, it can do so by implementing the `ICommandLineOptionsProvider` interface. This implementation can then be registered with the `ITestApplicationBuilder` via the registration factory of the `CommandLine` property, as shown: + +```csharp +builder.CommandLine.AddProvider( + static () => new CustomCommandLineOptions()); +``` + +In the example provided, `CustomCommandLineOptions` is an implementation of the `ICommandLineOptionsProvider` interface, This interface comprises the following members and data types: + +```csharp +public interface ICommandLineOptionsProvider : IExtension +{ + IReadOnlyCollection GetCommandLineOptions(); + + Task ValidateOptionArgumentsAsync( + CommandLineOption commandOption, + string[] arguments); + + Task ValidateCommandLineOptionsAsync( + ICommandLineOptions commandLineOptions); +} + +public sealed class CommandLineOption +{ + public string Name { get; } + public string Description { get; } + public ArgumentArity Arity { get; } + public bool IsHidden { get; } + + // ... +} + +public interface ICommandLineOptions +{ + bool IsOptionSet(string optionName); + + bool TryGetOptionArgumentList( + string optionName, + out string[]? arguments); +} +``` + +As observed, the `ICommandLineOptionsProvider` extends the [`IExtension`](#the-iextension-interface) interface. Therefore, like any other extension, you can choose to enable or disable it using the `IExtension.IsEnabledAsync` API. + +The order of execution of the `ICommandLineOptionsProvider` is: + + +:::image type="content" source="./media/icommandlineoptionsprovider-sequence-diagram.png" lightbox="./media/icommandlineoptionsprovider-sequence-diagram.png" alt-text="A diagram representing the order of execution of the 'ICommandLineOptionsProvider' interface."::: + +Let's examine the apis and their mean: + +`ICommandLineOptionsProvider.GetCommandLineOptions()`: This method is utilized to retrieve all the options offered by the component. Each `CommandLineOption` requires the following properties to be specified: + +`string name`: This is the option's name, presented without a dash. For example, *filter* would be used as `--filter` by users. + +`string description`: This is a description of the option. It will be displayed when users pass `--help` as an argument to the application builder. + +`ArgumentArity arity`: The arity of an option is the number of values that can be passed if that option or command is specified. Current available arities are: + +* `Zero`: Represents an argument arity of zero. +* `ZeroOrOne`: Represents an argument arity of zero or one. +* `ZeroOrMore`: Represents an argument arity of zero or more. +* `OneOrMore`: Represents an argument arity of one or more. +* `ExactlyOne`: Represents an argument arity of exactly one. + +For examples, refer to the [System.CommandLine arity table](https://learn.microsoft.com/dotnet/standard/commandline/syntax#argument-arity). + +`bool isHidden`: This property signifies that the option is available for use but will not be displayed in the description when `--help` is invoked. + +`ICommandLineOptionsProvider.ValidateOptionArgumentsAsync`: This method is employed to *validate* the argument provided by the user. + +For instance, if you have a parameter named `--dop` that represents the degree of parallelism for our custom testing framework, a user might input `--dop 0`. In this scenario, the value `0` would be invalid because it is expected to have a degree of parallelism of `1` or more. By using `ValidateOptionArgumentsAsync`, you can perform upfront validation and return an error message if necessary. + +A possible implementation for the sample above could be: + +```csharp +public Task ValidateOptionArgumentsAsync( + CommandLineOption commandOption, + string[] arguments) +{ + if (commandOption.Name == "dop") + { + if (!int.TryParse(arguments[0], out int dopValue) || dopValue <= 0) + { + return ValidationResult.InvalidTask("--dop must be a positive integer"); + } + } + + return ValidationResult.ValidTask; +} +``` + +`ICommandLineOptionsProvider.ValidateCommandLineOptionsAsync`: This method is called as last one and allows to do global coherency check. + +For example, let's say our testing framework has the capability to generate a test result report and save it to a file. This feature is accessed using the `--generatereport` option, and the filename is specified with `--reportfilename myfile.rep`. In this scenario, if a user only provides the `--generatereport` option without specifying a filename, the validation should fail because the report cannot be generated without a filename. +A possible implementation for the sample above could be: + +```csharp +public Task ValidateCommandLineOptionsAsync(ICommandLineOptions commandLineOptions) +{ + bool generateReportEnabled = commandLineOptions.IsOptionSet(GenerateReportOption); + bool reportFileName = commandLineOptions.TryGetOptionArgumentList(ReportFilenameOption, out string[]? _); + + return (generateReportEnabled || reportFileName) && !(generateReportEnabled && reportFileName) + ? ValidationResult.InvalidTask("Both `--generatereport` and `--reportfilename` need to be provided simultaneously.") + : ValidationResult.ValidTask; +} +``` + +Please note that the `ValidateCommandLineOptionsAsync` method provides the [`ICommandLineOptions`](./unit-testing-platform-architecture-services.md#the-icommandlineoptions-service) service, which is used to fetch the argument information parsed by the platform itself. + +### The `ITestSessionLifetimeHandler` extensions + +The `ITestSessionLifeTimeHandler` is an *in-process* extension that enables the execution of code *before* and *after* the test session. + +To register a custom `ITestSessionLifeTimeHandler`, utilize the following API: + +```csharp +var builder = await TestApplication.CreateBuilderAsync(args); + +// ... + +builder.TestHost.AddTestSessionLifetimeHandle( + static serviceProvider => new CustomTestSessionLifeTimeHandler()); +``` + +The factory utilizes the [IServiceProvider](./unit-testing-platform-architecture-services.md#the-imessagebus-service) to gain access to the suite of services offered by the testing platform. + +> [!IMPORTANT] +> The sequence of registration is significant, as the APIs are called in the order they were registered. + +The `ITestSessionLifeTimeHandler` interface includes the following methods: + +```csharp +public interface ITestSessionLifetimeHandler : ITestHostExtension +{ + Task OnTestSessionStartingAsync( + SessionUid sessionUid, + CancellationToken cancellationToken); + + Task OnTestSessionFinishingAsync( + SessionUid sessionUid, + CancellationToken cancellationToken); +} + +public readonly struct SessionUid(string value) +{ + public string Value { get; } = value; +} + +public interface ITestHostExtension : IExtension +{ +} +``` + +The `ITestSessionLifetimeHandler` is a type of `ITestHostExtension`, which serves as a base for all *test host* extensions. Like all other extension points, it also inherits from [IExtension](#the-iextension-interface). Therefore, like any other extension, you can choose to enable or disable it using the `IExtension.IsEnabledAsync` API. + +Consider the following details for this API: + +`OnTestSessionStartingAsync`: This method is invoked prior to the commencement of the test session and receives the `SessionUid` object, which provides an opaque identifier for the current test session. + +`OnTestSessionFinishingAsync`: This method is invoked after the completion of the test session, ensuring that the [testing framework](#test-framework-extension) has finished executing all tests and has reported all relevant data to the platform. Typically, in this method, the extension employs the [`IMessageBus`](./unit-testing-platform-architecture-services.md#the-imessagebus-service) to transmit custom assets or data to the shared platform bus. This method can also signal to any custom *out-of-process* extension that the test session has concluded. + +Finally, both APIs take a `CancellationToken` which the extension is expected to honor. + +If your extension requires intensive initialization and you need to use the async/await pattern, you can refer to the [`Async extension initialization and cleanup`](#asynchronous-initialization-and-cleanup-of-extensions). If you need to *share state* between extension points, you can refer to the [`CompositeExtensionFactory`](#the-compositeextensionfactoryt) section. + +### The `ITestApplicationLifecycleCallbacks` extensions + +The `ITestApplicationLifecycleCallbacks` is an *in-process* extension that enables the execution of code before everything, it's like to have access to the first line of the hypothetical *main* of the *test host*. + +To register a custom `ITestApplicationLifecycleCallbacks`, utilize the following api: + +```csharp +var builder = await TestApplication.CreateBuilderAsync(args); + +// ... + +builder.TestHost.AddTestApplicationLifecycleCallbacks( + static serviceProvider + => new CustomTestApplicationLifecycleCallbacks()); +``` + +The factory utilizes the [IServiceProvider](./unit-testing-platform-architecture-services.md#the-imessagebus-service) to gain access to the suite of services offered by the testing platform. + +> [!IMPORTANT] +> The sequence of registration is significant, as the APIs are called in the order they were registered. + +The `ITestApplicationLifecycleCallbacks` interface includes the following methods: + +```csharp +public interface ITestApplicationLifecycleCallbacks : ITestHostExtension +{ + Task BeforeRunAsync(CancellationToken cancellationToken); + + Task AfterRunAsync( + int exitCode, + CancellationToken cancellation); +} + +public interface ITestHostExtension : IExtension +{ +} +``` + +The `ITestApplicationLifecycleCallbacks` is a type of `ITestHostExtension`, which serves as a base for all *test host* extensions. Like all other extension points, it also inherits from [IExtension](#the-iextension-interface). Therefore, like any other extension, you can choose to enable or disable it using the `IExtension.IsEnabledAsync` API. + +`BeforeRunAsync`: This method serves as the initial point of contact for the *test host* and is the first opportunity for an *in-process* extension to execute a feature. It's typically used to establish a connection with any corresponding *out-of-process* extensions if a feature is designed to operate across both environments. + +*For example, the built-in hang dump feature is composed of both *in-process* and *out-of-process* extensions, and this method is used to exchange information with the *out-of-process* component of the extension.* + +`AfterRunAsync`: This method is the final call before exiting the [`int ITestApplication.RunAsync()`](./unit-testing-platform-architecture.md) and it provides the [`exit code`](./unit-testing-platform-exit-codes.md). It should be used solely for cleanup tasks and to notify any corresponding *out-of-process* extension that the *test host* is about to terminate. + +Finally, both APIs take a `CancellationToken` which the extension is expected to honor. + +### The `IDataConsumer` extensions + +The `IDataConsumer` is an *in-process* extension capable of subscribing to and receiving `IData` information that is pushed to the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service) by the [testing framework](#test-framework-extension) and its extensions. + +*This extension point is crucial as it enables developers to gather and process all the information generated during a test session.* + +To register a custom `IDataConsumer`, utilize the following api: + +```csharp +var builder = await TestApplication.CreateBuilderAsync(args); + +// ... + +builder.TestHost.AddDataConsumer( + static serviceProvider => new CustomDataConsumer()); +``` + +The factory utilizes the [IServiceProvider](./unit-testing-platform-architecture-services.md#the-imessagebus-service) to gain access to the suite of services offered by the testing platform. + +> [!IMPORTANT] +> The sequence of registration is significant, as the APIs are called in the order they were registered. + +The `IDataConsumer` interface includes the following methods: + +```csharp +public interface IDataConsumer : ITestHostExtension +{ + Type[] DataTypesConsumed { get; } + + Task ConsumeAsync( + IDataProducer dataProducer, + IData value, + CancellationToken cancellationToken); +} + +public interface IData +{ + string DisplayName { get; } + string? Description { get; } +} +``` + +The `IDataConsumer` is a type of `ITestHostExtension`, which serves as a base for all *test host* extensions. Like all other extension points, it also inherits from [IExtension](#the-iextension-interface). Therefore, like any other extension, you can choose to enable or disable it using the `IExtension.IsEnabledAsync` API. + +`DataTypesConsumed`: This property returns a list of `Type` that this extension plans to consume. It corresponds to `IDataProducer.DataTypesProduced`. Notably, an `IDataConsumer` can subscribe to multiple types originating from different `IDataProducer` instances without any issues. + +`ConsumeAsync`: This method is triggered whenever data of a type to which the current consumer is subscribed is pushed onto the [`IMessageBus`](./unit-testing-platform-architecture-services.md#the-imessagebus-service). It receives the `IDataProducer` to provide details about the data payload's producer, as well as the `IData` payload itself. As you can see, `IData` is a generic placeholder interface that contains general informative data. The ability to push different types of `IData` implies that the consumer needs to *switch* on the type itself to cast it to the correct type and access the specific information. + +A sample implementation of a consumer that wants to elaborate the [`TestNodeUpdateMessage`](#the-testnodeupdatemessage-data) produced by a [testing framework](#test-framework-extension) could be: + +```csharp +internal class CustomDataConsumer : IDataConsumer, IOutputDeviceDataProducer +{ + public Type[] DataTypesConsumed => new[] { typeof(TestNodeUpdateMessage) }; + ... + public Task ConsumeAsync( + IDataProducer dataProducer, + IData value, + CancellationToken cancellationToken) + { + var testNodeUpdateMessage = (TestNodeUpdateMessage)value; + + switch (testNodeUpdateMessage.TestNode.Properties.Single()) + { + case InProgressTestNodeStateProperty _: + { + ... + break; + } + case PassedTestNodeStateProperty _: + { + ... + break; + } + case FailedTestNodeStateProperty failedTestNodeStateProperty: + { + ... + break; + } + case SkippedTestNodeStateProperty _: + { + ... + break; + } + ... + } + + return Task.CompletedTask; + } +... +} +``` + +Finally, the API takes a `CancellationToken` which the extension is expected to honor. + +> [!IMPORTANT] +> It's crucial to process the payload directly within the `ConsumeAsync` method. The [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service) can manage both synchronous and asynchronous processing, coordinating the execution with the [testing framework](#test-framework-extension). Although the consumption process is entirely asynchronous and doesn't block the [IMessageBus.Push](./unit-testing-platform-architecture-services.md#the-imessagebus-service) at the time of writing, this is an implementation detail that may change in the future due to future requirements. However, the platform ensures that this method is always called once, eliminating the need for complex synchronization, as well as managing the scalability of the consumers. + + + +> [!WARNING] +> When using `IDataConsumer` in conjunction with [ITestHostProcessLifetimeHandler](#the-itestsessionlifetimehandler-extensions) within a [composite extension point](#the-compositeextensionfactoryt), **it's crucial to disregard any data received post the execution of [ITestSessionLifetimeHandler.OnTestSessionFinishingAsync](#the-itestsessionlifetimehandler-extensions)**. The `OnTestSessionFinishingAsync` is the final opportunity to process accumulated data and transmit new information to the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service), hence, any data consumed beyond this point will not be *utilizable* by the extension. + +If your extension requires intensive initialization and you need to use the async/await pattern, you can refer to the [`Async extension initialization and cleanup`](#asynchronous-initialization-and-cleanup-of-extensions). If you need to *share state* between extension points, you can refer to the [`CompositeExtensionFactory`](#the-compositeextensionfactoryt) section. + +### The `ITestHostEnvironmentVariableProvider` extensions + +The `ITestHostEnvironmentVariableProvider` is an *out-of-process* extension that enables you to establish custom environment variables for the test host. Utilizing this extension point ensures that the testing platform will initiate a new host with the appropriate environment variables, as detailed in the [architecture](./unit-testing-platform-architecture.md) section. + +To register a custom `ITestHostEnvironmentVariableProvider`, utilize the following API: + +```csharp +var builder = await TestApplication.CreateBuilderAsync(args); + +// ... + +builder.TestHostControllers.AddEnvironmentVariableProvider( + static serviceProvider => new CustomEnvironmentVariableForTestHost()); +``` + +The factory utilizes the [IServiceProvider](./unit-testing-platform-architecture-services.md#the-imessagebus-service) to gain access to the suite of services offered by the testing platform. + +> [!IMPORTANT] +> The sequence of registration is significant, as the APIs are called in the order they were registered. + +The `ITestHostEnvironmentVariableProvider` interface includes the following methods and types: + +```csharp +public interface ITestHostEnvironmentVariableProvider : ITestHostControllersExtension, IExtension +{ + Task UpdateAsync(IEnvironmentVariables environmentVariables); + + Task ValidateTestHostEnvironmentVariablesAsync( + IReadOnlyEnvironmentVariables environmentVariables); +} + +public interface IEnvironmentVariables : IReadOnlyEnvironmentVariables +{ + void SetVariable(EnvironmentVariable environmentVariable); + void RemoveVariable(string variable); +} + +public interface IReadOnlyEnvironmentVariables +{ + bool TryGetVariable( + string variable, + [NotNullWhen(true)] out OwnedEnvironmentVariable? environmentVariable); +} + +public sealed class OwnedEnvironmentVariable : EnvironmentVariable +{ + public IExtension Owner { get; } + + public OwnedEnvironmentVariable( + IExtension owner, + string variable, + string? value, + bool isSecret, + bool isLocked); +} + +public class EnvironmentVariable +{ + public string Variable { get; } + public string? Value { get; } + public bool IsSecret { get; } + public bool IsLocked { get; } +} +``` + +The `ITestHostEnvironmentVariableProvider` is a type of `ITestHostControllersExtension`, which serves as a base for all *test host controller* extensions. Like all other extension points, it also inherits from [IExtension](#the-iextension-interface). Therefore, like any other extension, you can choose to enable or disable it using the `IExtension.IsEnabledAsync` API. + +Consider the details for this API: + +`UpdateAsync`: This update API provides an instance of the `IEnvironmentVariables` object, from which you can call the `SetVariable` or `RemoveVariable` methods. When using `SetVariable`, you must pass an object of type `EnvironmentVariable`, which requires the following specifications: + +* `Variable`: The name of the environment variable. +* `Value`: The value of the environment variable. +* `IsSecret`: This indicates whether the environment variable contains sensitive information that should not be logged or accessible via the `TryGetVariable`. +* `IsLocked`: This determines whether other `ITestHostEnvironmentVariableProvider` extensions can modify this value. + +`ValidateTestHostEnvironmentVariablesAsync`: This method is invoked after all the `UpdateAsync` methods of the registered `ITestHostEnvironmentVariableProvider` instances have been called. It allows you to *verify* the correct setup of the environment variables. It takes an object that implements `IReadOnlyEnvironmentVariables`, which provides the `TryGetVariable` method to fetch specific environment variable information with the `OwnedEnvironmentVariable` object type. After validation, you return a `ValidationResult` containing any failure reasons. + +> [!NOTE] +> The testing platform, by default, implements and registers the `SystemEnvironmentVariableProvider`. This provider loads all the *current* environment variables. As the first registered provider, it executes first, granting access to the default environment variables for all other `ITestHostEnvironmentVariableProvider` user extensions. + +If your extension requires intensive initialization and you need to use the async/await pattern, you can refer to the [`Async extension initialization and cleanup`](#asynchronous-initialization-and-cleanup-of-extensions). If you need to *share state* between extension points, you can refer to the [`CompositeExtensionFactory`](#the-compositeextensionfactoryt) section. + +### The `ITestHostProcessLifetimeHandler` extensions + +The `ITestHostProcessLifetimeHandler` is an *out-of-process* extension that allows you to observe the test host process from an external standpoint. This ensures that your extension remains unaffected by potential crashes or hangs that could be induced by the code under test. Utilizing this extension point will prompt the testing platform to initiate a new host, as detailed in the [architecture](./unit-testing-platform-architecture.md) section. + +To register a custom `ITestHostProcessLifetimeHandler`, utilize the following API: + +```csharp +var builder = await TestApplication.CreateBuilderAsync(args); + +// ... + +builder.TestHostControllers.AddProcessLifetimeHandler( + static serviceProvider => new CustomMonitorTestHost()); +``` + +The factory utilizes the [IServiceProvider](./unit-testing-platform-architecture-services.md#the-imessagebus-service) to gain access to the suite of services offered by the testing platform. + +> [!IMPORTANT] +> The sequence of registration is significant, as the APIs are called in the order they were registered. + +The `ITestHostProcessLifetimeHandler` interface includes the following methods: + +```csharp +public interface ITestHostProcessLifetimeHandler : ITestHostControllersExtension +{ + Task BeforeTestHostProcessStartAsync(CancellationToken cancellationToken); + + Task OnTestHostProcessStartedAsync( + ITestHostProcessInformation testHostProcessInformation, + CancellationToken cancellation); + + Task OnTestHostProcessExitedAsync( + ITestHostProcessInformation testHostProcessInformation, + CancellationToken cancellation); +} + +public interface ITestHostProcessInformation +{ + int PID { get; } + int ExitCode { get; } + bool HasExitedGracefully { get; } +} +``` + +The `ITestHostProcessLifetimeHandler` is a type of `ITestHostControllersExtension`, which serves as a base for all *test host controller* extensions. Like all other extension points, it also inherits from [IExtension](#the-iextension-interface). Therefore, like any other extension, you can choose to enable or disable it using the `IExtension.IsEnabledAsync` API. + +Consider the following details for this API: + +`BeforeTestHostProcessStartAsync`: This method is invoked prior to the testing platform initiating the test hosts. + +`OnTestHostProcessStartedAsync`: This method is invoked immediately after the test host starts. This method offers an object that implements the `ITestHostProcessInformation` interface, which provides key details about the test host process result. +> [!IMPORTANT] +> The invocation of this method does not halt the test host's execution. If you need to pause it, you should register an [*in-process*](#microsofttestingplatform-extensibility) extension such as [`ITestApplicationLifecycleCallbacks`](#the-itestapplicationlifecyclecallbacks-extensions) and synchronize it with the *out-of-process* extension. + +`OnTestHostProcessExitedAsync`: This method is invoked when the test suite execution is complete. This method supplies an object that adheres to the `ITestHostProcessInformation` interface, which conveys crucial details about the outcome of the test host process. + +The `ITestHostProcessInformation` interface provides the following details: + +* `PID`: The process ID of the test host. +* `ExitCode`: The exit code of the process. This value is only available within the `OnTestHostProcessExitedAsync` method. Attempting to access it within the `OnTestHostProcessStartedAsync` method will result in an exception. +* `HasExitedGracefully`: A boolean value indicating whether the test host has crashed. If true, it signifies that the test host did not exit gracefully. + +## Extensions execution order + +The testing platform consists of a [testing framework](#test-framework-extension) and any number of extensions that can operate [*in-process*](#microsofttestingplatform-extensibility) or [*out-of-process*](#microsofttestingplatform-extensibility). This document outlines the **sequence of calls** to all potential extensibility points to provide clarity on when a feature is anticipated to be invoked: + +1. [ITestHostEnvironmentVariableProvider.UpdateAsync](#the-itesthostenvironmentvariableprovider-extensions) : Out-of-process +1. [ITestHostEnvironmentVariableProvider.ValidateTestHostEnvironmentVariablesAsync](#the-itesthostenvironmentvariableprovider-extensions) : Out-of-process +1. [ITestHostProcessLifetimeHandler.BeforeTestHostProcessStartAsync](#the-itestsessionlifetimehandler-extensions) : Out-of-process +1. Test host process start +1. [ITestHostProcessLifetimeHandler.OnTestHostProcessStartedAsync](#the-itestsessionlifetimehandler-extensions) : Out-of-process, this event can intertwine the actions of *in-process* extensions, depending on race conditions. +1. [ITestApplicationLifecycleCallbacks.BeforeRunAsync](#the-itestsessionlifetimehandler-extensions): In-process +1. [ITestSessionLifetimeHandler.OnTestSessionStartingAsync](#the-itestsessionlifetimehandler-extensions): In-process +1. [ITestFramework.CreateTestSessionAsync](#test-framework-extension): In-process +1. [ITestFramework.ExecuteRequestAsync](#test-framework-extension): In-process, this method can be called one or more times. At this point, the testing framework will transmit information to the [IMessageBus](./unit-testing-platform-architecture-services.md#the-imessagebus-service) that can be utilized by the [IDataConsumer](#the-idataconsumer-extensions). +1. [ITestFramework.CloseTestSessionAsync](#test-framework-extension): In-process +1. [ITestSessionLifetimeHandler.OnTestSessionFinishingAsync](#the-itestsessionlifetimehandler-extensions): In-process +1. [ITestApplicationLifecycleCallbacks.AfterRunAsync](#the-itestsessionlifetimehandler-extensions): In-process +1. In-process cleanup, involves calling dispose and [IAsyncCleanableExtension](#asynchronous-initialization-and-cleanup-of-extensions) on all extension points. +1. [ITestHostProcessLifetimeHandler.OnTestHostProcessExitedAsync](#the-itestsessionlifetimehandler-extensions) : Out-of-process +1. Out-of-process cleanup, involves calling dispose and [IAsyncCleanableExtension](#asynchronous-initialization-and-cleanup-of-extensions) on all extension points. + +## Extensions helpers + +The testing platform provides a set of helper classes and interfaces to simplify the implementation of extensions. These helpers are designed to streamline the development process and ensure that the extension adheres to the platform's standards. + +### Asynchronous initialization and cleanup of extensions + +The creation of the testing framework and extensions through factories adheres to the standard .NET object creation mechanism, which uses synchronous constructors. If an extension requires intensive initialization (such as accessing the file system or network), it cannot employ the *async/await* pattern in the constructor because constructors return void, not `Task`. + +Therefore, the testing platform provides a method to initialize an extension using the async/await pattern through a simple interface. For symmetry, it also offers an async interface for cleanup that extensions can implement seamlessly. + +```csharp +public interface IAsyncInitializableExtension +{ + Task InitializeAsync(); +} + +public interface IAsyncCleanableExtension +{ + Task CleanupAsync(); +} +``` + +`IAsyncInitializableExtension.InitializeAsync`: This method is assured to be invoked following the creation factory. + +`IAsyncCleanableExtension.CleanupAsync`: This method is assured to be invoked *at least one time* during the termination of the testing session, prior to the default `DisposeAsync` or `Dispose`. + +> [!IMPORTANT] +> Similar to the standard `Dispose` method, `CleanupAsync` may be invoked multiple times. If an object's `CleanupAsync` method is called more than once, the object must ignore all calls after the first one. The object must not throw an exception if its `CleanupAsync` method is called multiple times. +> [!NOTE] +> By default, the testing platform will call `DisposeAsync` if it's available, or `Dispose` if it's implemented. It's important to note that the testing platform will not call both dispose methods but will prioritize the async one if implemented. + +### The CompositeExtensionFactory + +As outlined in the [extensions](#microsofttestingplatform-extensibility) section, the testing platform enables you to implement interfaces to incorporate custom extensions both in and out of process. + +Each interface addresses a particular feature, and according to .NET design, you implement this interface in a specific object. You can register the extension itself using the specific registration API `AddXXX` from the `TestHost` or `TestHostController` object from the `ITestApplicationBuilder` as detailed in the corresponding sections. + +However, if you need to *share state* between two extensions, the fact that you can implement and register different objects implementing different interfaces makes sharing a challenging task. Without any assistance, you would need a way to pass one extension to the other to share information, which complicates the design. + +Hence, the testing platform provides a sophisticated method to implement multiple extension points using the same type, making data sharing a straightforward task. All you need to do is utilize the `CompositeExtensionFactory`, which can then be registered using the same API as you would for a single interface implementation. + +For instance, consider a type that implements both `ITestSessionLifetimeHandler` and `IDataConsumer`. This is a common scenario because you often want to gather information from the [testing framework](#test-framework-extension) and then, when the testing session concludes, you'll dispatch your artifact using the [`IMessageBus`](./unit-testing-platform-architecture-services.md#the-imessagebus-service) within the `ITestSessionLifetimeHandler.OnTestSessionFinishingAsync`. + +What you should do is to normally implement the interfaces: + +```csharp +internal class CustomExtension : ITestSessionLifetimeHandler, IDataConsumer, ... +{ + ... +} +``` + +Once you've created the `CompositeExtensionFactory` for your type, you can register it with both the `IDataConsumer` and `ITestSessionLifetimeHandler` APIs, which offer an overload for the `CompositeExtensionFactory`: + +```csharp +var builder = await TestApplication.CreateBuilderAsync(args); + +// ... + +var factory = new CompositeExtensionFactory(serviceProvider => new CustomExtension()); + +builder.TestHost.AddTestSessionLifetimeHandle(factory); +builder.TestHost.AddDataConsumer(factory); +``` + +The factory constructor employs the [IServiceProvider](./unit-testing-platform-architecture-services.md) to access the services provided by the testing platform. + +The testing platform will be responsible for managing the lifecycle of the composite extension. + +It's important to note that due to the testing platform's support for both *in-process* and *out-of-process* extensions, you can't combine any extension point arbitrarily. The creation and utilization of extensions are contingent on the host type, meaning you can only group *in-process* (TestHost) and *out-of-process* (TestHostController) extensions together. + +The following combinations are possible: + +* For `ITestApplicationBuilder.TestHost`, you can combine `IDataConsumer` and `ITestSessionLifetimeHandler`. +* For `ITestApplicationBuilder.TestHostControllers`, you can combine `ITestHostEnvironmentVariableProvider` and `ITestHostProcessLifetimeHandler`. diff --git a/docs/core/testing/unit-testing-platform-architecture-services.md b/docs/core/testing/unit-testing-platform-architecture-services.md new file mode 100644 index 0000000000000..09aebe7b027c4 --- /dev/null +++ b/docs/core/testing/unit-testing-platform-architecture-services.md @@ -0,0 +1,411 @@ +--- +title: Microsoft.Testing.Platform services overview +description: Learn about the Microsoft.Testing.Platform available services. +author: MarcoRossignoli +ms.author: mrossignoli +ms.date: 07/11/2024 +--- + +# Microsoft.Testing.Platform Services + +The testing platform offers valuable services to both the testing framework and extension points. These services cater to common needs such as accessing the configuration, parsing and retrieving command-line arguments, obtaining the logging factory, and accessing the logging system, among others. `IServiceProvider` implements the _service locator pattern_ for the testing platform. + +The `IServiceProvider` is derived directly from the base class library. + +```csharp +namespace System +{ + public interface IServiceProvider + { + object? GetService(Type serviceType); + } +} +``` + +The testing platform offers handy extension methods to access well-known service objects. All these methods are housed in a static class within the `Microsoft.Testing.Platform.Services` namespace. + +```csharp +public static class ServiceProviderExtensions +{ + public static TService GetRequiredService( + this IServiceProvider provider) + + public static TService? GetService( + this IServiceProvider provider) + + public static IMessageBus GetMessageBus( + this IServiceProvider serviceProvider) + + public static IConfiguration GetConfiguration( + this IServiceProvider serviceProvider) + + public static ICommandLineOptions GetCommandLineOptions( + this IServiceProvider serviceProvider) + + public static ILoggerFactory GetLoggerFactory( + this IServiceProvider serviceProvider) + + public static IOutputDevice GetOutputDevice( + this IServiceProvider serviceProvider) + + // ... and more +} +``` + +Most of the registration factories exposed by extension points provide access to the `IServiceProvider`: For example, when [registering the testing framework](./unit-testing-platform-architecture-extensions.md#register-a-testing-framework), the `IServiceProvider` is passed as a parameter to the factory method. + +```csharp +ITestApplicationBuilder RegisterTestFramework( + Func capabilitiesFactory, + Func adapterFactory); +``` + +In the preceding code, both the `capabilitiesFactory` and the `adapterFactory` supply the `IServiceProvider` as a parameter. + +## The `IConfiguration` service + +The `IConfiguration` interface can be retrieved using the [`IServiceProvider`](#microsofttestingplatform-services) and provides access to the configuration settings for the testing framework and any extension points. By default, these configurations are loaded from: + +* Environment variables +* A JSON file named `[assemblyName].testingplatformconfig.json` located near the entry point assembly. + +**The order of precedence is maintained, which means that if a configuration is found in the environment variables, the JSON file will not be processed.** + +The interface is a straightforward key-value pair of strings: + +```csharp +public interface IConfiguration +{ + string? this[string key] { get; } +} +``` + +### JSON configuration file + +The JSON file follows a hierarchical structure. To access child properties, you need to use the `:` separator. For example, consider a configuration for a potential testing framework like: + +```json +{ + "CustomTestingFramework": { + "DisableParallelism": true + } +} +``` + +The code snippet would look something like this: + +```csharp +IServiceProvider serviceProvider = null; // Get the service provider... + +var configuration = serviceProvider.GetConfiguration(); + +if (bool.TryParse(configuration["CustomTestingFramework:DisableParallelism"], out var value) && value is true) +{ + // ... +} +``` + +In the case of an array, such as: + +```json +{ + "CustomTestingFramework": { + "Engine": [ + "ThreadPool", + "CustomThread" + ] + } +} +``` + +The syntax to access to the fist element ("ThreadPool") is: + +```csharp +IServiceProvider serviceProvider = null; // Get the service provider... + +var configuration = serviceProvider.GetConfiguration(); + +var fistElement = configuration["CustomTestingFramework:Engine:0"]; +``` + +### Environment variables + +The `:` separator doesn't work with environment variable hierarchical keys on all platforms. `__`, the double underscore, is: + +* Supported by all platforms. For example, the `:` separator is not supported by [Bash](https://linuxhint.com/bash-environment-variables/), but `__` is. +* Automatically replaced by a `:` + +For instance, the environment variable can be set as follows (This example is applicable for Windows): + +```bash +setx CustomTestingFramework__DisableParallelism=True +``` + +You can choose not to use the environment variable configuration source when creating the `ITestApplicationBuilder`: + +```csharp +var options = new TestApplicationOptions(); + +options.Configuration.ConfigurationSources.RegisterEnvironmentVariablesConfigurationSource = false; + +var builder = await TestApplication.CreateBuilderAsync(args, options); +``` + +## The `ICommandLineOptions` service + +The `ICommandLineOptions` service is utilized to fetch details regarding the command-line options that the platform has parsed. The APIs available include: + +```csharp +public interface ICommandLineOptions +{ + bool IsOptionSet(string optionName); + + bool TryGetOptionArgumentList( + string optionName, + out string[]? arguments); +} +``` + +The `ICommandLineOptions` can be obtained through certain APIs, such as the [ICommandLineOptionsProvider](./unit-testing-platform-architecture-extensions.md#the-icommandlineoptionsprovider-extensions), or you can retrieve an instance of it from the [IServiceProvider](#microsofttestingplatform-services) via the extension method `serviceProvider.GetCommandLineOptions()`. + +`ICommandLineOptions.IsOptionSet(string optionName)`: This method allows you to verify whether a specific option has been specified. When specifying the `optionName`, omit the `--` prefix. For example, if the user inputs `--myOption`, you should simply pass `myOption`. + +`ICommandLineOptions.TryGetOptionArgumentList(string optionName, out string[]? arguments)`: This method enables you to check whether a specific option has been set and, if so, retrieve the corresponding value or values (if the arity is more than one). Similar to the previous case, the `optionName` should be provided without the `--` prefix. + +### The `ILoggerFactory` service + +The testing platform comes with an integrated logging system that generates a log file. You can view the logging options by running the `--help` command. +The options you can choose from include: + +```dotnetcli +--diagnostic Enable the diagnostic logging. The default log level is 'Trace'. The file will be written in the output directory with the name log_[MMddHHssfff].diag +--diagnostic-filelogger-synchronouswrite Force the built-in file logger to write the log synchronously. Useful for scenario where you don't want to lose any log (i.e. in case of crash). Note that this is slowing down the test execution. +--diagnostic-output-directory Output directory of the diagnostic logging, if not specified the file will be generated inside the default 'TestResults' directory. +--diagnostic-output-fileprefix Prefix for the log file name that will replace '[log]_.' +--diagnostic-verbosity Define the level of the verbosity for the --diagnostic. The available values are 'Trace', 'Debug', 'Information', 'Warning', 'Error', and 'Critical' +``` + +From a coding standpoint, to log information, you need to obtain the `ILoggerFactory` from the [`IServiceProvider`](#microsofttestingplatform-services). +The `ILoggerFactory` API is as follows: + +```csharp +public interface ILoggerFactory +{ + ILogger CreateLogger(string categoryName); +} + +public static class LoggerFactoryExtensions +{ + public static ILogger CreateLogger(this ILoggerFactory factory); +} +``` + +The logger factory allows you to create an `ILogger` object using the `CreateLogger` API. There's also a convenient API that accepts a generic argument, which will be used as the category name. + +```csharp +public interface ILogger +{ + Task LogAsync( + LogLevel logLevel, + TState state, + Exception? exception, + Func formatter); + + void Log( + LogLevel logLevel, + TState state, + Exception? exception, + Func formatter); + + bool IsEnabled(LogLevel logLevel); +} + +public interface ILogger : ILogger +{ +} + +public static class LoggingExtensions +{ + public static Task LogCriticalAsync(this ILogger logger, string message); + public static Task LogDebugAsync(this ILogger logger, string message); + public static Task LogErrorAsync(this ILogger logger, Exception ex); + public static Task LogErrorAsync(this ILogger logger, string message, Exception ex); + public static Task LogErrorAsync(this ILogger logger, string message); + public static Task LogInformationAsync(this ILogger logger, string message); + public static Task LogTraceAsync(this ILogger logger, string message); + public static Task LogWarningAsync(this ILogger logger, string message); + public static void LogCritical(this ILogger logger, string message); + public static void LogDebug(this ILogger logger, string message); + public static void LogError(this ILogger logger, Exception ex); + public static void LogError(this ILogger logger, string message, Exception ex); + public static void LogError(this ILogger logger, string message); + public static void LogInformation(this ILogger logger, string message); + public static void LogTrace(this ILogger logger, string message); + public static void LogWarning(this ILogger logger, string message); +} +``` + +The `ILogger` object, which is created by the `ILoggerFactory`, offers APIs for logging information at various levels. These logging levels include: + +```csharp +public enum LogLevel +{ + Trace, + Debug, + Information, + Warning, + Error, + Critical, + None, +} +``` + +Here's an example of how you might use the logging API: + +```csharp +... +IServiceProvider provider = null; // Get the service provider... + +var factory = provider.GetLoggerFactory(); + +var logger = factory.CreateLogger(); + +// ... + +if (logger.IsEnabled(LogLevel.Information)) +{ + await logger.LogInformationAsync( + $"Executing request of type '{context.Request}'"); +} + +// ... +``` + +Keep in mind that to prevent unnecessary allocation, you should check if the level is *enabled* using the `ILogger.IsEnabled(LogLevel)` API. + +## The `IMessageBus` service + +The message bus service is the central mechanism that facilitates information exchange between the test framework and its extensions. + +The message bus of the testing platform employs the _publish-subscribe pattern_. + +The overarching structure of the shared bus is as follows: + +:::image type="content" source="./media/message-bus.png" lightbox="./media/message-bus.png" alt-text="A picture representing the interactions of the various extensions with the message bus."::: + +As illustrated in the diagram, which includes an extensions and a test framework, there are two potential actions: pushing information to the bus or consuming information from the bus. + +The `IMessageBus` satisfied the *pushing action* to the bus and the API is: + +```csharp +public interface IMessageBus +{ + Task PublishAsync( + IDataProducer dataProducer, + IData data); +} + +public interface IDataProducer : IExtension +{ + Type[] DataTypesProduced { get; } +} + +public interface IData +{ + string DisplayName { get; } + string? Description { get; } +} +``` + +Consider the following details about the parameters: + +* `IDataProducer`: The `IDataProducer` communicates to the message bus the `Type` of information it can supply and establishes ownership through inheritance from the base interface [IExtension](./unit-testing-platform-architecture-extensions.md#the-iextension-interface). This implies that you can't indiscriminately push data to the message bus; you must declare the data type produced in advance. If you push unexpected data, an exception will be triggered. + +* `IData`: This interface serves as a placeholder where you only need to provide descriptive details such as the name and a description. The interface doesn't reveal much about the data's nature, which is intentional. It implies that the test framework and extensions can push any type of data to the bus, and this data can be consumed by any registered extension or the test framework itself. + +This approach facilitates the evolution of the information exchange process, preventing breaking changes when an extension is unfamiliar with new data. **It allows different versions of extensions and the test framework to operate in harmony, based on their mutual understanding**. + +The opposite end of the bus is referred to as a [consumer](./unit-testing-platform-architecture-extensions.md#the-idataconsumer-extensions), which is subscribed to a specific type of data and can thus consume it. + +> [!IMPORTANT] +> Always use *await* the call to `PublishAsync`. If you don't, the `IData` might not be processed correctly by the testing platform and extensions, which could lead to subtle bugs. It's only after you've returned from the *await* that you can be assured that the `IData` has been queued for processing on the message bus. Regardless of the extension point you're working on, ensure that you've awaited all `PublishAsync` calls before exiting the extension. For example, if you're implementing the [`testing framework`](./unit-testing-platform-architecture-extensions.md#create-a-testing-framework), you should not call `Complete` on the [requests](./unit-testing-platform-architecture-extensions.md#handling-requests) until you've awaited all `PublishAsync` calls for that specific request. + +## The `IOutputDevice` service + +The testing platform encapsulates the idea of an *output device*, allowing the testing framework and extensions to *present* information by transmitting any kind of data to the currently utilized display system. + +The most traditional example of an *output device* is the console output. + +> [!NOTE] +> While the testing platform is engineered to support custom *output devices*, currently, this extension point is not available. + +To transmit data to the *output device*, you must obtain the `IOutputDevice` from the [`IServiceProvider`](#microsofttestingplatform-services). + +The API consists of: + +```csharp +public interface IOutputDevice +{ + Task DisplayAsync( + IOutputDeviceDataProducer producer, + IOutputDeviceData data); +} + +public interface IOutputDeviceDataProducer : IExtension +{ +} + +public interface IOutputDeviceData +{ +} +``` + +The `IOutputDeviceDataProducer` extends the [`IExtension`](./unit-testing-platform-architecture-extensions.md#the-iextension-interface) and provides information about the sender to the *output device*. + +The `IOutputDeviceData` serves as a placeholder interface. The concept behind `IOutputDevice` is to accommodate more intricate information than just colored text. For instance, it could be a complex object that can be graphically represented. + +The testing platform, by default, offers a traditional colored text model for the `IOutputDeviceData` object: + +```csharp +public class TextOutputDeviceData : IOutputDeviceData +{ + public TextOutputDeviceData(string text) + public string Text { get; } +} + +public sealed class FormattedTextOutputDeviceData : TextOutputDeviceData +{ + public FormattedTextOutputDeviceData(string text) + public IColor? ForegroundColor { get; init; } + public IColor? BackgroundColor { get; init; } +} + +public sealed class SystemConsoleColor : IColor +{ + public ConsoleColor ConsoleColor { get; init; } +} +``` + +Here's an example of how you might use the colored text with the *active* output device: + +```csharp +IServiceProvider provider = null; // Get the service provider... + +var outputDevice = provider.GetOutputDevice(); + +await outputDevice.DisplayAsync( + this, + new FormattedTextOutputDeviceData($"TestingFramework version '{Version}' running tests with parallelism of {_dopValue}") + { + ForegroundColor = new SystemConsoleColor + { + ConsoleColor = ConsoleColor.Green + } + }); +``` + +Beyond the standard use of colored text, the main advantage of `IOutputDevice` and `IOutputDeviceData` is that the *output device* is entirely independent and unknown to the user. This allows for the development of complex user interfaces. For example, it's entirely feasible to implement a *real-time* web application that displays the progress of tests. + +## The `IPlatformInformation` service + +Provides information about the platform such as: name, version, commit hash and build date. diff --git a/docs/core/testing/unit-testing-platform-architecture.md b/docs/core/testing/unit-testing-platform-architecture.md new file mode 100644 index 0000000000000..137bcc844b93d --- /dev/null +++ b/docs/core/testing/unit-testing-platform-architecture.md @@ -0,0 +1,167 @@ +--- +title: Microsoft.Testing.Platform architecture overview +description: Learn about Microsoft.Testing.Platform architecture. +author: MarcoRossignoli +ms.author: mrossignoli +ms.date: 07/11/2024 +--- + +# Microsoft.Testing.Platform architecture + +Welcome to our new test platform! To help you get acquainted with its capabilities, we'll start with a simple example that demonstrates how to register and run a test. This foundational example will give you a solid understanding of the core functionality and how to get started quickly. + +> [!NOTE] +> All of the concepts in this article are exemplified in the Microsoft Test Framework repository as a complete sample. For more information, see the [Sample code](https://github.com/microsoft/testfx/tree/main/samples/public/TestingPlatformExamples). + +[Step 1: Register and Run a simple test application](#step-1-register-and-run-a-simple-test-application) + +In this initial example, you walk through the basic steps to declare and run a test application. This straightforward approach ensures that you can immediately start using the platform with minimal setup. + +[Step 2: Extending the Platform](#step-2-extending-the-platform) + +After you've discovered how to create your first test application, you explore an example of extension to cover partially the concepts surrounding the test application extensions. + +[Step 3: Comprehensive Overview of Extension Points](#step-3-comprehensive-overview-of-extension-points) + +Once you're comfortable with the basics, you delve into the various extension points. This will include: + +1. **Platform and Test Framework Capabilities**: Understanding the full range of capabilities provided by the platform and the test framework, allowing you to leverage them effectively. + +1. **Custom Test Framework**: How to write and register your custom test framework, enabling you to tailor the testing environment to your specific requirements. + +1. **In-Process and Out-of-Process Extensions**: Detailed instructions on how to write and register both in-process and out-of-process extensions, offering flexibility in how you extend the platform. + +1. **Order of Execution**: Clarifying the order of execution for the various extension points to ensure seamless integration and operation of your custom extensions. + +[Step 4: Available Services and Helpers](#step-4-available-services) + +Finally, you review an exhaustive list of the available services and helper functions within the platform. This section will serve as a reference to help you leverage all the tools at your disposal for creating robust and efficient test extensions. + +By following this structured approach, you will gain a comprehensive understanding of our test platform, from basic usage to advanced customization. Let's get started and explore the full potential of what our platform can offer! + +## Step 1: Register and Run a simple test application + +To introduce the architecture of the testing platform, this document will use the classic console application (for Windows) as the host. The samples in this document are written in C#, but you can use the testing platform with any language that supports the .NET Ecma specification, and run on any OS supported by .NET. To use the platform, simply reference the `Microsoft.Testing.Platform.dll` assembly, which can be consumed through the official NuGet package available at . + +In a console project `Contoso.UnitTests.exe` the following `Main` method defines the entry point: + +```csharp +public static async Task Main(string[] args) +{ + ITestApplicationBuilder builder = await TestApplication.CreateBuilderAsync(args); + + builder.RegisterTestFramework(); + + using ITestApplication testApp = await builder.BuildAsync(); + + return await testApp.RunAsync(); +} +``` + +This code includes everything needed to execute a test session, except for registering a test framework such as MSTest through `RegisterTestFramework`. This code is shown and explained in later sections. + +> [!NOTE] +> The default behavior is to have the entry point automatically generated by the testing platform MSBuild task. This is done by adding the `Microsoft.Testing.Platform.MSBuild` package to your project. + +When `Contoso.UnitTests.exe` application is started a standard Windows process is created, and the testing platform interacts with the registered testing framework to execute the testing session. + +A single process is created to carry out this work: + + +:::image type="content" source="./media/platform-testhost.png" lightbox="./media/platform-testhost.png" alt-text="A diagram representing the test host process."::: + +The testing platform includes a built-in display device that writes the testing session information in the terminal, similar to: + +```bash +Microsoft(R) Testing Platform Execution Command Line Tool +Version: 1.1.0+8c0a8fd8e (UTC 2024/04/03) +RuntimeInformation: win-x64 - .NET 9.0.0-preview.1.24080.9 +Copyright(c) Microsoft Corporation.  All rights reserved. +Passed! - Failed: 0, Passed: 1, Skipped: 0, Total: 1, Duration: 5ms - Contoso.UnitTests.dll (win-x64 - .NET 9.0.0-preview.1.24080.9) +``` + +> [!NOTE] +> The known exit codes returned by the `ITestApplication.RunAsync()` call are detailed in [platform exit codes](./unit-testing-platform-exit-codes.md). + +## Step 2: Extending the platform + +Test runs commonly collect code coverage information, or similar information to evaluate code quality. Such workloads may require configuration before the test host process starts, for example setting environment variables. + +The testing platform accommodates this by having **out-of-process** extensions. When running with an out-of-process extensions, the testing platform will start multiple processes and it will manage them appropriately. + +The following example demonstrates how to register a code coverage feature using a **TestHostController** extension. + +```csharp +ITestApplicationBuilder builder = await TestApplication.CreateBuilderAsync(args); + +builder.RegisterTestFramework(); +builder.AddCodeCoverage(); + +using ITestApplication testApp = await builder.BuildAsync(); + +return await testApp.RunAsync(); +``` + +The `builder.AddCodeCoverage();` internally uses the `TestHostController` extensibility point, which is an out-of-process extensibility point. + +```csharp +public static class TestApplicationBuilderExtensions +{ + public static ITestApplicationBuilder AddCodeCoverage( + this ITestApplicationBuilder builder) + { + builder.TestHostControllers + .AddEnvironmentVariableProvider(/* ... */); + + // ... + + return builder; + } +} +``` + +The parameters for the api `AddEnvironmentVariableProvider` will be explained in later sections. + +When running `Contoso.UnitTests.exe` this time, the testing platform detects that a `TestHostController` extension is registered. As a result, it starts another instance of the `Contoso.UnitTests.exe` process as a child process. This is done to properly set the environment variables as required by the extension registered with the `AddEnvironmentVariableProvider` API. + +The process layout looks like this: + + +:::image type="content" source="./media/platform-testhostcontroller-testhost.png" lightbox="./media/platform-testhostcontroller-testhost.png" alt-text="A diagram representing the process layout of the test host and test host controller."::: + +> [!NOTE] +> The provided example assumes a console application layout, which handles the start process correctly and propagates all command line arguments to the child process. +> If you are using a different host, you need to ensure that the entry point code correctly forwards the process entry point (the "Main") to the appropriate code block. +> The runtime simply starts itself with the same command line arguments. + +The above section provides a brief introduction to the architecture of the testing platform. The current extensibility points are divided into two categories: + +1. **In process** extensions can be accessed through the `TestHost` property of the test application builder. In process means that they will run in the same process as the test framework. + + ```csharp + ITestApplicationBuilder builder = await TestApplication.CreateBuilderAsync(args); + + builder.RegisterTestFramework(); + + builder.TestHost.AddXXX(/* ... */); + ``` + + As observed, the most crucial extension point is the in-process *testing framework* (`RegisterTestFramework`), which is the only **mandatory** one. + +1. **Out of process** extensions can be accessed through the `TestHostControllers` property of the test application builder. These extensions run in a separate process from the test framework to "observe" it. + + ```csharp + ITestApplicationBuilder builder = await TestApplication.CreateBuilderAsync(args); + + builder.TestHostControllers.AddXXX(/* ... */); + ``` + +## Step 3: Comprehensive Overview of Extension points + +Let's start by getting familiar with the concept of [capabilities](./unit-testing-platform-architecture-capabilities.md) before diving into the various [extensions points](./unit-testing-platform-architecture-extensions.md). + +## Step 4: Available services + +The testing platform offers valuable services to both the testing framework and extension points. These services cater to common needs such as accessing the configuration, parsing and retrieving command-line arguments, obtaining the logging factory, and accessing the logging system, among others. `IServiceProvider` implements the _service locator pattern_ for the testing platform. + +All the services, helpers and technical information about how to access and use these services is listed [here](./unit-testing-platform-architecture-services.md). diff --git a/docs/core/testing/unit-testing-platform-exit-codes.md b/docs/core/testing/unit-testing-platform-exit-codes.md index 0ffcbd00ba9cd..322f0721e8e40 100644 --- a/docs/core/testing/unit-testing-platform-exit-codes.md +++ b/docs/core/testing/unit-testing-platform-exit-codes.md @@ -19,7 +19,7 @@ ms.topic: reference | `3` | The exit code `3` indicates that the test session was aborted. A session can be aborted using Ctrl+C, as an example. | | `4` | The exit code `4` indicates that the setup of used extensions is invalid and the tests session cannot run. | | `5` | The exit code `5` indicates that the command line arguments passed to the test app are invalid. | -| `6` | The exit code `6` indicates that the test session is using a nonimplemented feature. | +| `6` | The exit code `6` indicates that the test session is using a non-implemented feature. | | `7` | The exit code `7` indicates that a test session was unable to complete successfully, and likely crashed. It's possible that this was caused by a test session that was run via a test controller's extension point. | | `8` | The exit code `8` indicates that the test session ran zero tests. | | `9` | The exit code `9` indicates that the minimum execution policy for the executed tests was violated. | diff --git a/docs/core/testing/unit-testing-platform-intro.md b/docs/core/testing/unit-testing-platform-intro.md index d298d8fd494c0..26edb0c032be2 100644 --- a/docs/core/testing/unit-testing-platform-intro.md +++ b/docs/core/testing/unit-testing-platform-intro.md @@ -12,6 +12,30 @@ Microsoft.Testing.Platform is a lightweight and portable alternative to [VSTest] `Microsoft.Testing.Platform` is open source. You can find `Microsoft.Testing.Platform` code in [microsoft/testfx](https://github.com/microsoft/testfx/tree/main/src/Platform/Microsoft.Testing.Platform) GitHub repository. +## Microsoft.Testing.Platform pillars + +This new testing platform is built on the .NET Developer Experience Testing team's experience and aims to address the challenges encountered since the release of .NET Core in 2016. While there's a high level of compatibility between the .NET Framework and the .NET Core/.NET, some key features like the plugin-system and the new possible form factors of .NET compilations have made it complex to evolve or fully support the new runtime feature with the current [VSTest platform](https://github.com/microsoft/vstest) architecture. + +The main driving factors for the evolution of the new testing platform are detailed in the following: + +* **Determinism**: Ensuring that running the same tests in different contexts (local, CI) will produce the same result. The new runtime does not rely on reflection or any other dynamic .NET runtime feature to coordinate a test run. + +* **Runtime transparency**: The test runtime does not interfere with the test framework code, it does not create isolated contexts like `AppDomain` or `AssemblyLoadContext`, and it does not use reflection or custom assembly resolvers. + +* **Compile-time registration of extensions**: Extensions, such as test frameworks and in/out-of-process extensions, are registered during compile-time to ensure determinism and to facilitate detection of inconsistencies. + +* **Zero dependencies**: The core of the platform is a single .NET assembly, `Microsoft.Testing.Platform.dll`, which has no dependencies other than the supported runtimes. + +* **Hostable**: The test runtime can be hosted in any .NET application. While a console application is commonly used to run tests, you can create a test application in any type of .NET application. This allows you to run tests within special contexts, such as devices or browsers, where there may be limitations. + +* **Support all .NET form factors**: Support current and future .NET form factors, including Native AOT. + +* **Performant**: Finding the right balance between features and extension points to avoid bloating the runtime with non-fundamental code. The new test platform is designed to "orchestrate" a test run, rather than providing implementation details on how to do it. + +* **Extensible enough**: The new platform is built on extensibility points to allow for maximum customization of runtime execution. It allows you to configure the test process host, observe the test process, and consume information from the test framework within the test host process. + +* **Single module deploy**: The hostability feature enables a single module deploy model, where a single compilation result can be used to support all extensibility points, both out-of-process and in-process, without the need to ship different executable modules. + ## Supported test frameworks * MSTest. In MSTest, the support of `Microsoft.Testing.Platform` is done via [MSTest runner](unit-testing-mstest-runner-intro.md). diff --git a/docs/core/tools/sdk-errors/netsdk1045.md b/docs/core/tools/sdk-errors/netsdk1045.md index f857918e362e0..e3b940f7f982a 100644 --- a/docs/core/tools/sdk-errors/netsdk1045.md +++ b/docs/core/tools/sdk-errors/netsdk1045.md @@ -48,14 +48,6 @@ If you have a preview installed of the requested .NET SDK version, you also need For example, .NET Core 3.0 and later require Visual Studio 2019. Upgrade to [Visual Studio 2019 version 16.3](https://visualstudio.microsoft.com/downloads) or later to build your project. -## Visual Studio for Mac - -VS for Mac supports both `dotnet msbuild` and MSBuild on Mono. But the .NET SDK version is downgraded when MSBuild on Mono is used, and this can result in the NETSDK1045 error. - -Open the **Solution Properties** window (ctrl-click the solution in the **Solution** window and select **Properties**), select **Build - General**, and uncheck **Build with MSBuild on Mono**. This **Build with MSBuild on Mono** option will be checked if there are any classic projects in the solution, and this can cause problems since Mono does not support the later .NET SDKs. - -For more information about which Visual Studio for Mac 2022 versions support which .NET versions, see [Supported versions of .NET](/visualstudio/mac/supported-versions-net). - ## PATH environment variable The build tools use the PATH environment variable to find the right version of the .NET build tools. If the PATH environment variable contains direct paths to older build tools, this error message could appear. Make sure the only path to the .NET tools in the PATH environment variable is to the top-level *dotnet* folder, for example, *C:\Program Files\dotnet*. An example of an incorrect PATH would be something like *C:\Program Files\dotnet\2.1.0\sdks*. diff --git a/docs/core/tutorials/debugging-with-visual-studio-mac.md b/docs/core/tutorials/debugging-with-visual-studio-mac.md deleted file mode 100644 index e4da3d8db3857..0000000000000 --- a/docs/core/tutorials/debugging-with-visual-studio-mac.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -title: Debug a .NET console application using Visual Studio for Mac -description: Learn how to debug a .NET console app using Visual Studio Mac. -ms.date: 01/28/2023 ---- -# Tutorial: Debug a .NET console application using Visual Studio for Mac - -[!INCLUDE [](~/includes/vs-mac-eol.md)] - -This tutorial introduces the debugging tools available in Visual Studio for Mac. - -## Prerequisites - -- This tutorial works with the console app that you create in [Create a .NET console application using Visual Studio for Mac](with-visual-studio-mac.md). - -## Use Debug build configuration - -*Debug* and *Release* are Visual Studio's built-in build configurations. You use the Debug build configuration for debugging and the Release configuration for the final release distribution. - -In the Debug configuration, a program compiles with full symbolic debug information and no optimization. Optimization complicates debugging, because the relationship between source code and generated instructions is more complex. The release configuration of a program has no symbolic debug information and is fully optimized. - -By default, Visual Studio for Mac uses the Debug build configuration, so you don't need to change it before debugging. - -1. Start Visual Studio for Mac. - -1. Open the project that you created in [Create a .NET console application using Visual Studio for Mac](with-visual-studio-mac.md). - - The current build configuration is shown on the toolbar. The following toolbar image shows that Visual Studio is configured to compile the Debug version of the app: - - :::image type="content" source="media/debugging-with-visual-studio-mac/visual-studio-toolbar-debug.png" alt-text="Visual Studio toolbar with debug highlighted"::: - -## Set a breakpoint - -A *breakpoint* temporarily interrupts the execution of the application before the line with the breakpoint is executed. - -1. Set a breakpoint on the line that displays the name, date, and time. To do that, place the cursor in the line of code and press ⌘\\ (command+\\). Another way to set a breakpoint is by selecting **Debug** > **Toggle Breakpoint** from the menu. - - Visual Studio indicates the line on which the breakpoint is set by highlighting it and displaying a red dot in the left margin. - - :::image type="content" source="media/debugging-with-visual-studio-mac/set-breakpoint-in-editor.png" alt-text="Visual Studio Program window with breakpoint set"::: - -1. Press ⌘↵ (command+enter) to start the program in debugging mode. Another way to start debugging is by choosing **Debug** > **Start Debugging** from the menu. - -1. Enter a string in the terminal window when the program prompts for a name, and then press enter. - -1. Program execution stops when it reaches the breakpoint, before the `Console.WriteLine` method executes. - - :::image type="content" source="media/debugging-with-visual-studio-mac/breakpoint-hit.png" alt-text="Screenshot of a breakpoint in Visual Studio"::: - -## Use the Immediate window - -The **Immediate** window lets you interact with the application you're debugging. You can interactively change the value of variables to see how it affects your program. - -1. If the **Immediate** window is not visible, display it by choosing **View** > **Debug Windows** > **Immediate**. - -1. Enter `name = "Gracie"` in the **Immediate** window and press enter. - -1. Enter `currentDate = currentDate.AddDays(1)` in the **Immediate** window and press enter. - - The **Immediate** window displays the new value of the string variable and the properties of the value. - - :::image type="content" source="media/debugging-with-visual-studio-mac/immediate-window.png" alt-text="Immediate Window in Visual Studio"::: - - The **Locals** window displays the values of variables that are defined in the currently executing method. The values of the variables that you just changed are updated in the **Locals** window. - - :::image type="content" source="media/debugging-with-visual-studio-mac/locals-window.png" alt-text="Locals Window in Visual Studio"::: - -1. Press ⌘↵ (command+enter) to continue debugging. - - The values displayed in the terminal correspond to the changes you made in the **Immediate** window. - - If you don't see the Terminal, select **Terminal - HelloWorld** in the bottom navigation bar. - - :::image type="content" source="media/debugging-with-visual-studio-mac/terminal-hello-world.png" alt-text="Terminal - Hello World in bottom navigation bar"::: - -1. Press any key to exit the program. - -1. Close the terminal window. - -## Set a conditional breakpoint - -The program displays a string that the user enters. What happens if the user doesn't enter anything? You can test this with a useful debugging feature called a *conditional breakpoint*. - -1. ctrl-click on the red dot that represents the breakpoint. In the context menu, select **Edit Breakpoint**. - -1. In the **Edit Breakpoint** dialog, enter the following code in the field that follows **And the following condition is true**, and select **Apply**. - - ```csharp - String.IsNullOrEmpty(name) - ``` - - :::image type="content" source="media/debugging-with-visual-studio-mac/breakpoint-settings.png" alt-text="Editor showing breakpoint settings panel"::: - - Each time the breakpoint is hit, the debugger calls the `String.IsNullOrEmpty(name)` method, and it breaks on this line only if the method call returns `true`. - - Instead of a conditional expression, you can specify a *hit count*, which interrupts program execution before a statement is executed a specified number of times. - -1. Press ⌘↵ (command+enter) to start debugging. - -1. In the terminal window, press enter when prompted to enter your name. - - Because the condition you specified (`name` is either `null` or ) has been satisfied, program execution stops when it reaches the breakpoint. - -1. Select the **Locals** window, which shows the values of variables that are local to the currently executing method. In this case, `Main` is the currently executing method. Observe that the value of the `name` variable is `""`, that is, . - -1. You can also see that the value is an empty string by entering the `name` variable name in the **Immediate** window and pressing enter. - - :::image type="content" source="media/debugging-with-visual-studio-mac/immediate-window-output.png" alt-text="Immediate window showing name is an empty string"::: - -1. Press ⌘↵ (command+enter) to continue debugging. - -1. In the terminal window, press any key to exit the program. - -1. Close the terminal window. - -1. Clear the breakpoint by clicking on the red dot in the left margin of the code window. Another way to clear a breakpoint is by choosing **Debug > Toggle Breakpoint** while the line of code is selected. - -## Step through a program - -Visual Studio also allows you to step line by line through a program and monitor its execution. Ordinarily, you'd set a breakpoint and follow program flow through a small part of your program code. Since this program is small, you can step through the entire program. - -1. Set a breakpoint on the curly brace that marks the start of the `Main` method (press command+\\). - -1. Press ⌘↵ (command+enter) to start debugging. - - Visual Studio stops on the line with the breakpoint. - -1. Press ⇧⌘I (shift+command+I) or select **Debug** > **Step Into** to advance one line. - - Visual Studio highlights and displays an arrow beside the next line of execution. - - :::image type="content" source="media/debugging-with-visual-studio-mac/step-into-method.png" alt-text="Visual Studio step into method"::: - - At this point, the **Locals** window shows that the `args` array is empty, and `name` and `currentDate` have default values. In addition, Visual Studio has opened a blank terminal. - -1. Press ⇧⌘I (shift+command+I). - - Visual Studio highlights the statement that includes the `name` variable assignment. The **Locals** window shows that `name` is `null`, and the terminal displays the string "What is your name?". - -1. Respond to the prompt by entering a string in the console window and pressing enter. - -1. Press ⇧⌘I (shift+command+I). - - Visual Studio highlights the statement that includes the `currentDate` variable assignment. The **Locals** window shows the value returned by the call to the method. The terminal displays the string you entered at the prompt. - -1. Press ⇧⌘I (shift+command+I). - - The **Locals** window shows the value of the `currentDate` variable after the assignment from the property. The terminal is unchanged. - -1. Press ⇧⌘I (shift+command+I). - - Visual Studio calls the method. The terminal displays the formatted string. - -1. Press ⇧⌘U (shift+command+U) or select **Run** > **Step Out**. - - The terminal displays a message and waits for you to press a key. - -1. Press any key to exit the program. - -## Use Release build configuration - -Once you've tested the Debug version of your application, you should also compile and test the Release version. The Release version incorporates compiler optimizations that can negatively affect the behavior of an application. For example, compiler optimizations that are designed to improve performance can create race conditions in multithreaded applications. - -To build and test the Release version of the console application, do the following steps: - -1. Change the build configuration on the toolbar from **Debug** to **Release**. - - :::image type="content" source="media/debugging-with-visual-studio-mac/visual-studio-toolbar-release.png" alt-text="default Visual Studio toolbar with release highlighted"::: - -1. Press ⌥⌘↵ (option+command+enter) to run without debugging. - -## Next steps - -In this tutorial, you used Visual Studio debugging tools. In the next tutorial, you publish a deployable version of the app. - -> [!div class="nextstepaction"] -> [Publish a .NET console application using Visual Studio for Mac](publishing-with-visual-studio-mac.md) diff --git a/docs/core/tutorials/library-with-visual-studio-mac.md b/docs/core/tutorials/library-with-visual-studio-mac.md deleted file mode 100644 index b33770a637f0f..0000000000000 --- a/docs/core/tutorials/library-with-visual-studio-mac.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: Create a .NET class library using Visual Studio for Mac -description: Learn how to create a .NET class library using Visual Studio for Mac. -ms.date: 11/30/2020 ---- -# Tutorial: Create a .NET class library using Visual Studio for Mac - -[!INCLUDE [](~/includes/vs-mac-eol.md)] - -In this tutorial, you create a class library that contains a single string-handling method. - -A *class library* defines types and methods that are called by an application. If the library targets .NET Standard 2.0, it can be called by any .NET implementation (including .NET Framework) that supports .NET Standard 2.0. If the library targets .NET 5, it can be called by any application that targets .NET 5. This tutorial shows how to target .NET 5. - -> [!NOTE] -> Your feedback is highly valued. There are two ways you can provide feedback to the development team on Visual Studio for Mac: -> -> - In Visual Studio for Mac, select **Help** > **Report a Problem** from the menu or **Report a Problem** from the Welcome screen, which opens a window for filing a bug report. You can track your feedback in the [Developer Community](https://aka.ms/feedback/report?space=41) portal. -> - To make a suggestion, select **Help** > **Provide a Suggestion** from the menu or **Provide a Suggestion** from the Welcome screen, which takes you to the [Visual Studio for Mac Developer Community webpage](https://aka.ms/feedback/suggest?space=41). - -## Prerequisites - -* [Install Visual Studio for Mac version 8.8 or later](https://visualstudio.microsoft.com/vs/mac/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link). Select the option to install .NET Core. Installing Xamarin is optional for .NET development. For more information, see the following resources: - - * [Tutorial: Install Visual Studio for Mac](/visualstudio/mac/installation). - * [Supported macOS versions](../install/macos.md). - * [.NET versions supported by Visual Studio for Mac](/visualstudio/mac/net-core-support). - -## Create a solution with a class library project - -A Visual Studio solution serves as a container for one or more projects. Create a solution and a class library project in the solution. You'll add additional, related projects to the same solution later. - -1. Start Visual Studio for Mac. - -1. In the start window, select **New Project**. - -1. In the **Choose a template for your new project** dialog select **Web and Console** > **Library** > **Class Library**, and then select **Next**. - - :::image type="content" source="media/library-with-visual-studio-mac/visual-studio-mac-new-project.png" alt-text="New Project dialog"::: - -1. In the **Configure your new Class Library** dialog, choose **.NET 5.0**, and select **Next**. - -1. Name the project "StringLibrary" and the solution "ClassLibraryProjects". Leave **Create a project directory within the solution directory** selected. Select **Create**. - - :::image type="content" source="media/library-with-visual-studio-mac/visual-studio-mac-new-project-options.png" alt-text="Visual Studio for Mac New project dialog options"::: - -1. From the main menu, select **View** > **Solution**, and select the dock icon to keep the pad open. - - :::image type="content" source="media/library-with-visual-studio-mac/solution-dock-icon.png" alt-text="Dock icon for Solution pad"::: - -1. In the **Solution** pad, expand the `StringLibrary` node to reveal the class file provided by the template, *Class1.cs*. ctrl-click the file, select **Rename** from the context menu, and rename the file to *StringLibrary.cs*. Open the file and replace the contents with the following code: - - :::code language="csharp" source="./snippets/library-with-visual-studio/csharp/StringLibrary/Class1.cs"::: - -1. Press ⌘S (command+S) to save the file. - -1. Select **Errors** in the margin at the bottom of the IDE window to open the **Errors** panel. Select the **Build Output** button. - - :::image type="content" source="media/library-with-visual-studio-mac/visual-studio-mac-error-button.png" alt-text="Bottom margin of the Visual Studio Mac IDE showing the Errors button"::: - -1. Select **Build** > **Build All** from the menu. - - The solution builds. The build output panel shows that the build is successful. - - :::image type="content" source="media/library-with-visual-studio-mac/visual-studio-mac-build-panel.png" alt-text="Visual Studio Mac Build output pane of the Errors panel with Build successful message"::: - -## Add a console app to the solution - -Add a console application that uses the class library. The app will prompt the user to enter a string and report whether the string begins with an uppercase character. - -1. In the **Solution** pad, ctrl-click the `ClassLibraryProjects` solution. Add a new **Console Application** project by selecting the template from the **Web and Console** > **App** templates, and select **Next**. - -1. Select **.NET 5.0** as the **Target Framework** and select **Next**. - -1. Name the project **ShowCase**. Select **Create** to create the project in the solution. - - :::image type="content" source="media/library-with-visual-studio-mac/add-showcase-project.png" alt-text="Add ShowCase project"::: - -1. Open the *Program.cs* file. Replace the code with the following code: - - :::code language="csharp" source="./snippets/library-with-visual-studio/csharp/ShowCase/Program.cs"::: - - The program prompts the user to enter a string. It indicates whether the string starts with an uppercase character. If the user presses the enter key without entering a string, the application ends, and the console window closes. - - The code uses the `row` variable to maintain a count of the number of rows of data written to the console window. Whenever it's greater than or equal to 25, the code clears the console window and displays a message to the user. - -## Add a project reference - -Initially, the new console app project doesn't have access to the class library. To allow it to call methods in the class library, create a project reference to the class library project. - -1. In the **Solutions** pad, ctrl-click the **Dependencies** node of the new **ShowCase** project. In the context menu, select **Add Reference**. - -1. In the **References** dialog, select **StringLibrary** and select **OK**. - -## Run the app - -1. ctrl-click the **ShowCase** project and select **Run project** from the context menu. - -1. Try out the program by entering strings and pressing enter, then press enter to exit. - - :::image type="content" source="media/library-with-visual-studio-mac/visual-studio-mac-console-window.png" alt-text="Visual Studio for Mac console window showing your app running"::: - -## Additional resources - -* [Develop libraries with the .NET CLI](libraries.md) -* [Visual Studio 2019 for Mac Release Notes](/visualstudio/releasenotes/vs2019-mac-relnotes) -* [.NET Standard versions and the platforms they support](../../standard/net-standard.md). - -## Next steps - -In this tutorial, you created a solution and a library project, and added a console app project that uses the library. In the next tutorial, you add a unit test project to the solution. - -> [!div class="nextstepaction"] -> [Test a .NET class library using Visual Studio for Mac](testing-library-with-visual-studio-mac.md) diff --git a/docs/core/tutorials/publishing-with-visual-studio-mac.md b/docs/core/tutorials/publishing-with-visual-studio-mac.md deleted file mode 100644 index a5dab55d928a8..0000000000000 --- a/docs/core/tutorials/publishing-with-visual-studio-mac.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Publish a .NET console application using Visual Studio for Mac -description: Learn how to use Visual Studio for Mac to create the set of files that are needed to run a .NET application. -ms.date: 12/19/2022 ---- -# Tutorial: Publish a .NET console application using Visual Studio for Mac - -[!INCLUDE [](~/includes/vs-mac-eol.md)] - -This tutorial shows how to publish a console app so that other users can run it. Publishing creates the set of files that are needed to run your application. To deploy the files, copy them to the target machine. - -## Prerequisites - -- This tutorial works with the console app that you create in [Create a .NET console application using Visual Studio for Mac](with-visual-studio-mac.md). - -## Publish the app - -1. Start Visual Studio for Mac. - -1. Open the HelloWorld project that you created in [Create a .NET console application using Visual Studio for Mac](with-visual-studio-mac.md). - -1. Make sure that Visual Studio is building the Release version of your application. If necessary, change the build configuration setting on the toolbar from **Debug** to **Release**. - - :::image type="content" source="media/publishing-with-visual-studio-mac/toolbar-release.png" alt-text="Visual Studio toolbar with release build selected"::: - -1. From the main menu, choose **Build** > **Publish to Folder...**. - - :::image type="content" source="media/publishing-with-visual-studio-mac/publish-context-menu.png" alt-text="Visual Studio Publish context menu"::: - -1. In the **Publish to Folder** dialog, select **Publish**. - - :::image type="content" source="media/publishing-with-visual-studio-mac/publish-to-folder-dialog.png" alt-text="Visual Studio Publish to Folder dialog"::: - - The publish folder opens, showing the files that were created. - - :::image type="content" source="media/publishing-with-visual-studio-mac/publish-folder.png" alt-text="publish folder"::: - -1. Select the gear icon, and select **Copy "publish" as Pathname** from the context menu. - - :::image type="content" source="media/publishing-with-visual-studio-mac/copy-path.png" alt-text="Copy path to publish folder"::: - -## Inspect the files - -The publishing process creates a framework-dependent deployment, which is a type of deployment where the published application runs on a machine that has the .NET runtime installed. Users can run the published app by running the `dotnet HelloWorld.dll` command from a command prompt. - -As the preceding image shows, the published output includes the following files: - -* *HelloWorld.deps.json* - - This is the application's runtime dependencies file. It defines the .NET components and the libraries (including the dynamic link library that contains your application) needed to run the app. For more information, see [Runtime configuration files](https://github.com/dotnet/cli/blob/85ca206d84633d658d7363894c4ea9d59e515c1a/Documentation/specs/runtime-configuration-file.md). - -* *HelloWorld.dll* - - This is the [framework-dependent deployment](../deploying/deploy-with-cli.md#framework-dependent-deployment) version of the application. To execute this dynamic link library, enter `dotnet HelloWorld.dll` at a command prompt. This method of running the app works on any platform that has the .NET runtime installed. - -* *HelloWorld.pdb* (optional for deployment) - - This is the debug symbols file. You aren't required to deploy this file along with your application, although you should save it in the event that you need to debug the published version of your application. - -* *HelloWorld.runtimeconfig.json* - - This is the application's runtime configuration file. It identifies the version of .NET that your application was built to run on. You can also add configuration options to it. For more information, see [.NET runtime configuration settings](../runtime-config/index.md#runtimeconfigjson). - -## Run the published app - -1. Open a terminal and navigate to the *publish* folder. To do that, enter `cd` and then paste the path that you copied earlier. For example: - - ```console - cd ~/Projects/HelloWorld/HelloWorld/bin/Release/net5.0/publish/ - ``` - -1. Run the app by using the `dotnet` command: - - 1. Enter `dotnet HelloWorld.dll` and press enter. - - 1. Enter a name in response to the prompt, and press any key to exit. - -## Additional resources - -- [.NET application deployment](../deploying/index.md) -- [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md) -- [`dotnet publish`](../tools/dotnet-publish.md) -- [Tutorial: Publish a .NET console application using Visual Studio Code](publishing-with-visual-studio-code.md) -- [Use the .NET SDK in continuous integration (CI) environments](../../devops/dotnet-cli-and-continuous-integration.md) - -## Next steps - -In this tutorial, you published a console app. In the next tutorial, you create a class library. - -> [!div class="nextstepaction"] -> [Create a .NET library using Visual Studio for Mac](library-with-visual-studio-mac.md) diff --git a/docs/core/tutorials/testing-library-with-visual-studio-mac.md b/docs/core/tutorials/testing-library-with-visual-studio-mac.md deleted file mode 100644 index 5376250eae1a4..0000000000000 --- a/docs/core/tutorials/testing-library-with-visual-studio-mac.md +++ /dev/null @@ -1,189 +0,0 @@ ---- -title: Test a .NET class library using Visual Studio for Mac -description: Create a unit test project for a .NET class library. Verify that a .NET class library works correctly with unit tests. -ms.date: 11/18/2020 ---- -# Test a .NET class library using Visual Studio - -[!INCLUDE [](~/includes/vs-mac-eol.md)] - -This tutorial shows how to automate unit testing by adding a test project to a solution. - -## Prerequisites - -- This tutorial works with the solution that you create in [Create a .NET class library using Visual Studio for Mac](library-with-visual-studio-mac.md). - -## Create a unit test project - -Unit tests provide automated software testing during your development and publishing. [MSTest](https://github.com/Microsoft/testfx-docs) is one of three test frameworks you can choose from. The others are [xUnit](https://xunit.net/) and [nUnit](https://nunit.org/). - -1. Start Visual Studio for Mac. - -1. Open the `ClassLibraryProjects` solution you created in [Create a .NET class library using Visual Studio for Mac](library-with-visual-studio-mac.md). - -1. In the **Solution** pad, ctrl-click the `ClassLibraryProjects` solution and select **Add** > **New Project**. - -1. In the **New Project** dialog, select **Tests** from the **Web and Console** node. Select the **MSTest Project** followed by **Next**. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/visual-studio-mac-unit-test-project.png" alt-text="Visual Studio Mac New Project dialog creating test project"::: - -1. Select **.NET 5.0** as the **Target Framework** and select **Next**. - -1. Name the new project "StringLibraryTest" and select **Create**. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/visual-studio-mac-new-project-name.png" alt-text="Visual Studio Mac New Project dialog providing project name"::: - - Visual Studio creates a class file with the following code: - - ```csharp - using Microsoft.VisualStudio.TestTools.UnitTesting; - - namespace StringLibraryTest - { - [TestClass] - public class UnitTest1 - { - [TestMethod] - public void TestMethod1() - { - } - } - } - ``` - - The source code created by the unit test template does the following: - - - It imports the namespace, which contains the types used for unit testing. - - It applies the attribute to the `UnitTest1` class. - - It applies the attribute to `TestMethod1`. - - Each method tagged with [[TestMethod]](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestMethodAttribute) in a test class tagged with [[TestClass]](xref:Microsoft.VisualStudio.TestTools.UnitTesting.TestClassAttribute) is executed automatically when the unit test is run. - -## Add a project reference - -For the test project to work with the `StringLibrary` class, add a reference to the `StringLibrary` project. - -1. In the **Solution** pad, ctrl-click **Dependencies** under **StringLibraryTest**. Select **Add Reference** from the context menu. - -1. In the **References** dialog, select the **StringLibrary** project. Select **OK**. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/visual-studio-mac-edit-references.png" alt-text="Visual Studio Mac Edit References dialog"::: - -## Add and run unit test methods - -When Visual Studio runs a unit test, it executes each method that is marked with the attribute in a class that is marked with the attribute. A test method ends when the first failure is found or when all tests contained in the method have succeeded. - -The most common tests call members of the class. Many assert methods include at least two parameters, one of which is the expected test result and the other of which is the actual test result. Some of the `Assert` class's most frequently called methods are shown in the following table: - -| Assert methods | Function | -| ------------------ | -------- | -| `Assert.AreEqual` | Verifies that two values or objects are equal. The assert fails if the values or objects aren't equal. | -| `Assert.AreSame` | Verifies that two object variables refer to the same object. The assert fails if the variables refer to different objects. | -| `Assert.IsFalse` | Verifies that a condition is `false`. The assert fails if the condition is `true`. | -| `Assert.IsNotNull` | Verifies that an object isn't `null`. The assert fails if the object is `null`. | - -You can also use the method in a test method to indicate the type of exception it's expected to throw. The test fails if the specified exception isn't thrown. - -In testing the `StringLibrary.StartsWithUpper` method, you want to provide a number of strings that begin with an uppercase character. You expect the method to return `true` in these cases, so you can call the method. Similarly, you want to provide a number of strings that begin with something other than an uppercase character. You expect the method to return `false` in these cases, so you can call the method. - -Since your library method handles strings, you also want to make sure that it successfully handles an [empty string (`String.Empty`)](xref:System.String.Empty), a valid string that has no characters and whose is 0, and a `null` string that hasn't been initialized. You can call `StartsWithUpper` directly as a static method and pass a single argument. Or you can call `StartsWithUpper` as an extension method on a `string` variable assigned to `null`. - -You'll define three methods, each of which calls an method for each element in a string array. You'll call a method overload that lets you specify an error message to be displayed in case of test failure. The message identifies the string that caused the failure. - -To create the test methods: - -1. Open the *UnitTest1.cs* file and replace the code with the following code: - - :::code language="csharp" source="./snippets/library-with-visual-studio/csharp/StringLibraryTest/UnitTest1.cs"::: - - The test of uppercase characters in the `TestStartsWithUpper` method includes the Greek capital letter alpha (U+0391) and the Cyrillic capital letter EM (U+041C). The test of lowercase characters in the `TestDoesNotStartWithUpper` method includes the Greek small letter alpha (U+03B1) and the Cyrillic small letter Ghe (U+0433). - -1. On the menu bar, select **File** > **Save As**. In the dialog, make sure that **Encoding** is set to **Unicode (UTF-8)**. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/save-file-as-dialog.png" alt-text="Visual Studio Save File As dialog"::: - -1. When you're asked if you want to replace the existing file, select **Replace**. - - If you fail to save your source code as a UTF8-encoded file, Visual Studio may save it as an ASCII file. When that happens, the runtime doesn't accurately decode the UTF8 characters outside of the ASCII range, and the test results won't be correct. - -1. Open the **Unit Tests** panel on the right side of the screen. Select **View** > **Tests** from the menu. - -1. Click the **Dock** icon to keep the panel open. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/visual-studio-mac-unit-test-dock-icon.png" alt-text="Visual Studio for Mac Unit Tests panel dock icon"::: - -1. Click the **Run All** button. - - All tests pass. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/visual-studio-mac-unit-test-pass.png" alt-text="Visual Studio for Mac expected test passes"::: - -## Handle test failures - -If you're doing test-driven development (TDD), you write tests first and they fail the first time you run them. Then you add code to the app that makes the test succeed. For this tutorial, you created the test after writing the app code that it validates, so you haven't seen the test fail. To validate that a test fails when you expect it to fail, add an invalid value to the test input. - -1. Modify the `words` array in the `TestDoesNotStartWithUpper` method to include the string "Error". You don't need to save the file because Visual Studio automatically saves open files when a solution is built to run tests. - - ```csharp - string[] words = { "alphabet", "Error", "zebra", "abc", "αυτοκινητοβιομηχανία", "государство", - "1234", ".", ";", " " }; - ``` - -1. Run the tests again. - - This time, the **Test Explorer** window indicates that two tests succeeded and one failed. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/failed-test-window.png" alt-text="Test Explorer window with failing tests"::: - -1. ctrl-click the failed test, `TestDoesNotStartWithUpper`, and select **Show Results Pad** from the context menu. - - The **Results** pad displays the message produced by the assert: "Assert.IsFalse failed. Expected for 'Error': false; actual: True". Because of the failure, no strings in the array after "Error" were tested. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/visual-studio-mac-unit-test-failure.png" alt-text="Test Explorer window showing the IsFalse assertion failure"::: - -1. Remove the string "Error" that you added in step 1. Rerun the test and the tests pass. - -## Test the Release version of the library - -Now that the tests have all passed when running the Debug build of the library, run the tests an additional time against the Release build of the library. A number of factors, including compiler optimizations, can sometimes produce different behavior between Debug and Release builds. - -To test the Release build: - -1. In the Visual Studio toolbar, change the build configuration from **Debug** to **Release**. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/visual-studio-toolbar-release.png" alt-text="Visual Studio toolbar with release build highlighted"::: - -1. In the **Solution** pad, ctrl-click the **StringLibrary** project and select **Build** from the context menu to recompile the library. - - :::image type="content" source="media/testing-library-with-visual-studio-mac/build-library-context-menu.png" alt-text="StringLibrary context menu with build command"::: - -1. Run the unit tests again. - - The tests pass. - -## Debug tests - -If you're using Visual Studio for Mac as your IDE, you can use the same process shown in [Tutorial: Debug a .NET console application using Visual Studio for Mac](debugging-with-visual-studio-mac.md) to debug code using your unit test project. Instead of starting the *ShowCase* app project, ctrl-click the **StringLibraryTests** project, and select **Start Debugging Project** from the context menu. - -Visual Studio starts the test project with the debugger attached. Execution will stop at any breakpoint you've added to the test project or the underlying library code. - -## Additional resources - -- [Unit testing in .NET](../testing/index.md) - -## Next steps - -In this tutorial, you unit tested a class library. You can make the library available to others by publishing it to [NuGet](https://nuget.org) as a package. To learn how, follow a NuGet tutorial: - -> [!div class="nextstepaction"] -> [Create and publish a package (dotnet CLI)](/nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli) - -If you publish a library as a NuGet package, others can install and use it. To learn how, follow a NuGet tutorial: - -> [!div class="nextstepaction"] -> [Install and use a package in Visual Studio for Mac](/nuget/quickstart/install-and-use-a-package-in-visual-studio-mac) - -A library doesn't have to be distributed as a package. It can be bundled with a console app that uses it. To learn how to publish a console app, see the earlier tutorial in this series: - -> [!div class="nextstepaction"] -> [Publish a .NET console application using Visual Studio for Mac](publishing-with-visual-studio-mac.md) diff --git a/docs/core/tutorials/with-visual-studio-mac.md b/docs/core/tutorials/with-visual-studio-mac.md deleted file mode 100644 index 3d6f1373c31bf..0000000000000 --- a/docs/core/tutorials/with-visual-studio-mac.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -title: Create a .NET console application using Visual Studio for Mac -description: Learn how to create a .NET console application using Visual Studio for Mac. -ms.date: 11/30/2020 ---- -# Tutorial: Create a .NET console application using Visual Studio for Mac - -This tutorial shows how to create and run a .NET console application using Visual Studio for Mac. - -[!INCLUDE [](~/includes/vs-mac-eol.md)] - -## Prerequisites - -* [Visual Studio for Mac version 8.8 or later](https://visualstudio.microsoft.com/vs/mac/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link). Select the option to install .NET Core. Installing Xamarin is optional for .NET development. For more information, see the following resources: - - * [Tutorial: Install Visual Studio for Mac](/visualstudio/mac/installation). - * [Supported macOS versions](../install/windows.md). - * [.NET versions supported by Visual Studio for Mac](/visualstudio/mac/net-core-support). - -## Create the app - -1. Start Visual Studio for Mac. - -1. Select **New** in the start window. - - :::image type="content" source="media/with-visual-studio-mac/visual-studio-mac-new-project.png" alt-text="New button on the Visual Studio for Mac Start screen"::: - -1. In the **New Project** dialog, select **App** under the **Web and Console** node. Select the **Console Application** template, and select **Next**. - - :::image type="content" source="media/with-visual-studio-mac/visual-studio-mac-new-dialog.png" alt-text="New project templates list"::: - -1. In the **Target Framework** drop-down of the **Configure your new Console Application** dialog, select **.NET 5.0**, and select **Next**. - -1. Type "HelloWorld" for the **Project Name**, and select **Create**. - - :::image type="content" source="media/with-visual-studio-mac/visual-studio-mac-new-options.png" alt-text="Configure your new Console Application dialog"::: - -The template creates a simple "Hello World" application. It calls the method to display "Hello World!" in the terminal window. - -The template code defines a class, `Program`, with a single method, `Main`, that takes a array as an argument: - -```csharp -using System; - -namespace HelloWorld -{ - class Program - { - static void Main(string[] args) - { - Console.WriteLine("Hello World!"); - } - } -} -``` - -`Main` is the application entry point, the method that's called automatically by the runtime when it launches the application. Any command-line arguments supplied when the application is launched are available in the `args` array. - -## Run the app - -1. Press ⌥⌘↵ (option+command+enter) to run the app without debugging. - - :::image type="content" source="media/with-visual-studio-mac/visual-studio-mac-output.png" alt-text="The terminal shows Hello World!"::: - -1. Close the **Terminal** window. - -## Enhance the app - -Enhance the application to prompt the user for their name and display it along with the date and time. - -1. In *Program.cs*, replace the contents of the `Main` method, which is the line that calls `Console.WriteLine`, with the following code: - - :::code language="csharp" source="./snippets/with-visual-studio/csharp/Program.cs" id="MainMethod"::: - - This code displays a prompt in the console window and waits until the user enters a string followed by the enter key. It stores this string in a variable named `name`. It also retrieves the value of the property, which contains the current local time, and assigns it to a variable named `currentDate`. And it displays these values in the console window. Finally, it displays a prompt in the console window and calls the method to wait for user input. - - is a platform-independent and language-independent way to represent a line break. Alternatives are `\n` in C# and `vbCrLf` in Visual Basic. - - The dollar sign (`$`) in front of a string lets you put expressions such as variable names in curly braces in the string. The expression value is inserted into the string in place of the expression. This syntax is referred to as [interpolated strings](../../csharp/language-reference/tokens/interpolated.md). - -1. Press ⌥⌘↵ (option+command+enter) to run the app. - -1. Respond to the prompt by entering a name and pressing enter. - - :::image type="content" source="media/with-visual-studio-mac/hello-world-update.png" alt-text="Terminal shows modified program output"::: - -1. Close the terminal. - -## Next steps - -In this tutorial, you created a .NET console application. In the next tutorial, you debug the app. - -> [!div class="nextstepaction"] -> [Debug a .NET console application using Visual Studio for Mac](debugging-with-visual-studio-mac.md) diff --git a/docs/core/whats-new/dotnet-6.md b/docs/core/whats-new/dotnet-6.md index 3ead2f98b580c..1b703499158a7 100644 --- a/docs/core/whats-new/dotnet-6.md +++ b/docs/core/whats-new/dotnet-6.md @@ -20,7 +20,7 @@ author: gewarren *Preview* features are disabled by default. They are also not supported for use in production and may be removed in a future version. The new is used to annotate preview APIs, and a corresponding analyzer alerts you if you're using these preview APIs. -.NET 6 is supported by Visual Studio 2022 and Visual Studio 2022 for Mac (and later versions). +.NET 6 is supported by Visual Studio 2022 and later versions. This article does not cover all of the new features of .NET 6. To see all of the new features, and for further information about the features listed in this article, see the [Announcing .NET 6](https://devblogs.microsoft.com/dotnet/announcing-net-6) blog post. diff --git a/docs/core/whats-new/dotnet-core-2-0.md b/docs/core/whats-new/dotnet-core-2-0.md index 71c02a42bbe64..a0e3fb6dddc6a 100644 --- a/docs/core/whats-new/dotnet-core-2-0.md +++ b/docs/core/whats-new/dotnet-core-2-0.md @@ -118,7 +118,7 @@ And with the [Windows Compatibility Pack](../porting/windows-compat-pack.md) por ## Visual Studio integration -Visual Studio 2017 version 15.3 and in some cases Visual Studio for Mac offer a number of significant enhancements for .NET Core developers. +Visual Studio 2017 version 15.3 offers a number of significant enhancements for .NET Core developers. ### Retargeting .NET Core apps and .NET Standard libraries diff --git a/docs/core/whats-new/dotnet-core-3-0.md b/docs/core/whats-new/dotnet-core-3-0.md index d6e6fadc57471..309bd6e3e2a33 100644 --- a/docs/core/whats-new/dotnet-core-3-0.md +++ b/docs/core/whats-new/dotnet-core-3-0.md @@ -13,7 +13,7 @@ ms.date: 01/27/2020 This article describes what is new in .NET Core 3.0. One of the biggest enhancements is support for Windows desktop applications (Windows only). By using the .NET Core 3.0 SDK component Windows Desktop, you can port your Windows Forms and Windows Presentation Foundation (WPF) applications. To be clear, the Windows Desktop component is only supported and included on Windows. For more information, see the [Windows desktop](#windows-desktop) section later in this article. -.NET Core 3.0 adds support for C# 8.0. It's highly recommended that you use [Visual Studio 2019 version 16.3](https://visualstudio.microsoft.com/vs/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2019) or newer, [Visual Studio for Mac 8.3](/visualstudio/mac/install-preview) or newer, or [Visual Studio Code](https://code.visualstudio.com/) with the latest **C# extension**. +.NET Core 3.0 adds support for C# 8.0. It's highly recommended that you use [Visual Studio 2019 version 16.3](https://visualstudio.microsoft.com/vs/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2019) or newer, or [Visual Studio Code](https://code.visualstudio.com/) with the latest **C# extension**. [Download and get started with .NET Core 3.0](https://aka.ms/netcore3download) right now on Windows, macOS, or Linux. diff --git a/docs/core/whats-new/dotnet-core-3-1.md b/docs/core/whats-new/dotnet-core-3-1.md index c1a3468228932..b04f1bce6a11c 100644 --- a/docs/core/whats-new/dotnet-core-3-1.md +++ b/docs/core/whats-new/dotnet-core-3-1.md @@ -14,8 +14,6 @@ This article describes what is new in .NET Core 3.1. This release contains minor If you're using Visual Studio 2019, you must update to [Visual Studio 2019 version 16.4 or later](https://visualstudio.microsoft.com/downloads/) to work with .NET Core 3.1 projects. For information on what's new in Visual Studio version 16.4, see [What's New in Visual Studio 2019 version 16.4](/visualstudio/releases/2019/release-notes-v16.4#whats-new-in-visual-studio-2019-version-164). -Visual Studio for Mac also supports and includes .NET Core 3.1 in Visual Studio for Mac 8.4. - For more information about the release, see the [.NET Core 3.1 announcement](https://devblogs.microsoft.com/dotnet/announcing-net-core-3-1/). - [Download and get started with .NET Core 3.1](https://dotnet.microsoft.com/download/dotnet/3.1) on Windows, macOS, or Linux. diff --git a/docs/csharp/language-reference/builtin-types/arrays.md b/docs/csharp/language-reference/builtin-types/arrays.md index b5e63d1aaffde..8ae2af65ac494 100644 --- a/docs/csharp/language-reference/builtin-types/arrays.md +++ b/docs/csharp/language-reference/builtin-types/arrays.md @@ -42,7 +42,7 @@ The following example creates single-dimensional, multidimensional, and jagged a :::code language="csharp" source="./snippets/shared/Arrays.cs" id="DeclareArrays"::: > [!IMPORTANT] -> Many of the examples in this article use [collection expressions](../operators/collection-expressions.md) (which use square brackets) to initialize the arrays. Collection expressions were first introduced in C# 12, which shipped with .NET 8. If you can't ugrade to C# 12 yet, use `{` and `}` to initialize the arrays instead. +> Many of the examples in this article use [collection expressions](../operators/collection-expressions.md) (which use square brackets) to initialize the arrays. Collection expressions were first introduced in C# 12, which shipped with .NET 8. If you can't upgrade to C# 12 yet, use `{` and `}` to initialize the arrays instead. > > ```csharp > // Collection expressions: diff --git a/docs/csharp/language-reference/keywords/method-parameters.md b/docs/csharp/language-reference/keywords/method-parameters.md index d69693fd739d5..1113bcf204512 100644 --- a/docs/csharp/language-reference/keywords/method-parameters.md +++ b/docs/csharp/language-reference/keywords/method-parameters.md @@ -35,7 +35,7 @@ How an argument is passed, and whether it's a reference type or value type contr - If the method assigns the parameter to refer to a different object, those changes **aren't** visible from the caller. - If the method modifies the state of the object referred to by the parameter, those changes **are** visible from the caller. - When you pass a *value* type *by reference*: - - If the method assigns the parameter to refer to a different object, those changes **aren't** visible from the caller. + - If the method assigns the parameter to refer to a different object using `ref =`, those changes **aren't** visible from the caller. - If the method modifies the state of the object referred to by the parameter, those changes **are** visible from the caller. - When you pass a *reference* type *by reference*: - If the method assigns the parameter to refer to a different object, those changes **are** visible from the caller. diff --git a/docs/csharp/language-reference/language-versioning.md b/docs/csharp/language-reference/language-versioning.md index 222f96644a401..41a3c718fd766 100644 --- a/docs/csharp/language-reference/language-versioning.md +++ b/docs/csharp/language-reference/language-versioning.md @@ -11,7 +11,7 @@ The latest C# compiler determines a default language version based on your proje [C# 13](../whats-new/csharp-13.md) is supported only on .NET 9 and newer versions. [C# 12](../whats-new/csharp-12.md) is supported only on .NET 8 and newer versions. [C# 11](../whats-new/csharp-11.md) is supported only on .NET 7 and newer versions. -Check the [Visual Studio platform compatibility](/visualstudio/releases/2022/compatibility#-visual-studio-2022-support-for-net-development) page for details on which .NET versions are supported by versions of Visual Studio. Check the [Visual Studio for Mac platform compatibility](/visualstudio/mac/supported-versions-net) page for details on which .NET versions are supported by versions of Visual Studio for Mac. Check the [Mono page for C#](https://www.mono-project.com/docs/about-mono/languages/csharp/) for Mono compatibility with C# versions. +Check the [Visual Studio platform compatibility](/visualstudio/releases/2022/compatibility#-visual-studio-2022-support-for-net-development) page for details on which .NET versions are supported by versions of Visual Studio. Check the [Mono page for C#](https://www.mono-project.com/docs/about-mono/languages/csharp/) for Mono compatibility with C# versions. ## Defaults diff --git a/docs/csharp/linq/includes/data-sources-definition.md b/docs/csharp/linq/includes/data-sources-definition.md new file mode 100644 index 0000000000000..5112ce8960d25 --- /dev/null +++ b/docs/csharp/linq/includes/data-sources-definition.md @@ -0,0 +1,13 @@ +--- +author: BillWagner +ms.author: wiwagn +ms.topic: include +ms.date: 10/04/2024 +--- + +> [!NOTE] +> The following examples in this article use the common data sources for this area. +> Each `Student` has a grade level, a primary department, and a series of scores. A `Teacher` also has a `City` property that identifies the campus where the teacher holds classes. A `Department` has a name, and a reference to a `Teacher` who serves as the department head. +> You can find the example data set in the [source repo](https://github.com/dotnet/docs/blob/main/docs/csharp/linq/standard-query-operators/snippets/standard-query-operators/DataSources.cs#L41). + +:::code language="csharp" source="../standard-query-operators/snippets/standard-query-operators/DataSources.cs" id="QueryDataSource"::: diff --git a/docs/csharp/linq/standard-query-operators/converting-data-types.md b/docs/csharp/linq/standard-query-operators/converting-data-types.md index eea9af0edff62..3f775f7590dc6 100644 --- a/docs/csharp/linq/standard-query-operators/converting-data-types.md +++ b/docs/csharp/linq/standard-query-operators/converting-data-types.md @@ -32,11 +32,7 @@ The conversion methods in this table whose names start with "As" change the stat |ToList|Converts a collection to a . This method forces query execution.|Not applicable.|| |ToLookup|Puts elements into a (a one-to-many dictionary) based on a key selector function. This method forces query execution.|Not applicable.|| -The following examples in this article use the common data sources for this area: - -:::code language="csharp" source="./snippets/standard-query-operators/DataSources.cs" id="QueryDataSource"::: - -Each `Student` has a grade level, a primary department, and a series of scores. A `Teacher` also has a `City` property that identifies the campus where the teacher holds classes. A `Department` has a name, and a reference to a `Teacher` who serves as the department head. +[!INCLUDE [Datasources](../includes/data-sources-definition.md)] ## Query Expression Syntax Example diff --git a/docs/csharp/linq/standard-query-operators/grouping-data.md b/docs/csharp/linq/standard-query-operators/grouping-data.md index fc5bf1e607c96..8fe818384d311 100644 --- a/docs/csharp/linq/standard-query-operators/grouping-data.md +++ b/docs/csharp/linq/standard-query-operators/grouping-data.md @@ -26,11 +26,7 @@ The equivalent query using method syntax is shown in the following code: :::code language="csharp" source="./snippets/standard-query-operators/GroupOverview.cs" id="OverviewSampleMethodSyntax"::: -The following examples in this article use the common data sources for this area: - -:::code language="csharp" source="./snippets/standard-query-operators/DataSources.cs" id="QueryDataSource"::: - -Each `Student` has a grade level, a primary department, and a series of scores. A `Teacher` also has a `City` property that identifies the campus where the teacher holds classes. A `Department` has a name, and a reference to a `Teacher` who serves as the department head. +[!INCLUDE [Datasources](../includes/data-sources-definition.md)] ## Group query results diff --git a/docs/csharp/linq/standard-query-operators/index.md b/docs/csharp/linq/standard-query-operators/index.md index d830483043dc0..c3b452288f13a 100644 --- a/docs/csharp/linq/standard-query-operators/index.md +++ b/docs/csharp/linq/standard-query-operators/index.md @@ -27,17 +27,19 @@ Where possible, the queries in this section use a sequence of words or numbers a Each `Student` has a grade level, a primary department, and a series of scores. A `Teacher` also has a `City` property that identifies the campus where the teacher holds classes. A `Department` has a name, and a reference to a `Teacher` who serves as the department head. +You can find the data set in the [source repo](https://github.com/dotnet/docs/blob/main/docs/csharp/linq/standard-query-operators/snippets/standard-query-operators/DataSources.cs#L41). + ## Types of query operators The standard query operators differ in the timing of their execution, depending on whether they return a singleton value or a sequence of values. Those methods that return a singleton value (such as and ) execute immediately. Methods that return a sequence defer the query execution and return an enumerable object. You can use the output sequence of one query as the input sequence to another query. Calls to query methods can be chained together in one query, which enables queries to become arbitrarily complex. ## Query operators -In a LINQ query, the first step is to specify the data source. In a LINQ query, the `from` clause comes first in order to introduce the data source (`customers`) and the *range variable* (`cust`). +In a LINQ query, the first step is to specify the data source. In a LINQ query, the `from` clause comes first in order to introduce the data source (`students`) and the *range variable* (`student`). :::code language="csharp" source="./snippets/standard-query-operators/IndexExamples.cs" id="ObtainDataSource"::: -The range variable is like the iteration variable in a `foreach` loop except that no actual iteration occurs in a query expression. When the query is executed, the range variable serves as a reference to each successive element in `customers`. Because the compiler can infer the type of `cust`, you don't have to specify it explicitly. You can introduce more range variables in a `let` clause. For more information, see [let clause](../../language-reference/keywords/let-clause.md). +The range variable is like the iteration variable in a `foreach` loop except that no actual iteration occurs in a query expression. When the query is executed, the range variable serves as a reference to each successive element in `students`. Because the compiler can infer the type of `student`, you don't have to specify it explicitly. You can introduce more range variables in a `let` clause. For more information, see [let clause](../../language-reference/keywords/let-clause.md). > [!NOTE] > For non-generic data sources such as , the range variable must be explicitly typed. For more information, see [How to query an ArrayList with LINQ (C#)](../how-to-query-collections.md) and [from clause](../../language-reference/keywords/from-clause.md). diff --git a/docs/csharp/linq/standard-query-operators/join-operations.md b/docs/csharp/linq/standard-query-operators/join-operations.md index ca9a473936674..05c9c2db0aaea 100644 --- a/docs/csharp/linq/standard-query-operators/join-operations.md +++ b/docs/csharp/linq/standard-query-operators/join-operations.md @@ -25,11 +25,7 @@ The following illustration shows a conceptual view of two sets and the elements |Join|Joins two sequences based on key selector functions and extracts pairs of values.|`join … in … on … equals …`|

| |GroupJoin|Joins two sequences based on key selector functions and groups the resulting matches for each element.|`join … in … on … equals … into …`|

| -The following examples in this article use the common data sources for this area: - -:::code language="csharp" source="./snippets/standard-query-operators/DataSources.cs" id="QueryDataSource"::: - -Each `Student` has a grade level, a primary department, and a series of scores. A `Teacher` also has a `City` property that identifies the campus where the teacher holds classes. A `Department` has a name, and a reference to a `Teacher` who serves as the department head. +[!INCLUDE [Datasources](../includes/data-sources-definition.md)] The following example uses the `join … in … on … equals …` clause to join two sequences based on specific value: diff --git a/docs/csharp/linq/standard-query-operators/set-operations.md b/docs/csharp/linq/standard-query-operators/set-operations.md index 095a01a015fa3..801c574ca575c 100644 --- a/docs/csharp/linq/standard-query-operators/set-operations.md +++ b/docs/csharp/linq/standard-query-operators/set-operations.md @@ -34,11 +34,7 @@ The following example depicts the behavior of

| |Reverse|Reverses the order of the elements in a collection.|Not applicable.|

| -The following examples in this article use the common data sources for this area: - -:::code language="csharp" source="./snippets/standard-query-operators/DataSources.cs" id="QueryDataSource"::: - -Each `Student` has a grade level, a primary department, and a series of scores. A `Teacher` also has a `City` property that identifies the campus where the teacher holds classes. A `Department` has a name, and a reference to a `Teacher` who serves as the department head. +[!INCLUDE [Datasources](../includes/data-sources-definition.md)] ## Primary Ascending Sort diff --git a/docs/framework/windows-workflow-foundation/workflow-security.md b/docs/framework/windows-workflow-foundation/workflow-security.md index 6202134249608..de3ca59e0de48 100644 --- a/docs/framework/windows-workflow-foundation/workflow-security.md +++ b/docs/framework/windows-workflow-foundation/workflow-security.md @@ -10,6 +10,9 @@ ms.assetid: d712a566-f435-44c0-b8c0-49298e84b114 Windows Workflow Foundation (WF) is integrated with several different technologies, such as Microsoft SQL Server and Windows Communication Foundation (WCF). Interacting with these technologies may introduce security issues into your workflow if done improperly. +> [!NOTE] +> Workflows describe the order of execution and dependencies between short- or long-running tasks. As a code execution mechanism, only trusted code should be loaded and executed. Developers must ensure that only trusted workflows are used with applications using WF. + ## Persistence Security Concerns 1. Workflows that use a activity and persistence need to be reactivated by a service. Windows AppFabric uses the Workflow Management Service (WMS) to reactivate workflows with expired timers. WMS creates a to host the reactivated workflow. If the WMS service is stopped, persisted workflows will not be reactivated when their timers expire. diff --git a/docs/fsharp/get-started/get-started-with-visual-studio-for-mac.md b/docs/fsharp/get-started/get-started-with-visual-studio-for-mac.md deleted file mode 100644 index 08c7d79f7c4f8..0000000000000 --- a/docs/fsharp/get-started/get-started-with-visual-studio-for-mac.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Get started with F# in Visual Studio for Mac -description: Learn how to use F# with Visual Studio for Mac. -ms.date: 10/29/2021 ---- -# Get started with F# in Visual Studio for Mac - -[!INCLUDE [](~/includes/vs-mac-eol.md)] - -F# is supported in the Visual Studio for Mac IDE. Ensure that you have [Visual Studio for Mac installed](install-fsharp.md#install-f-with-visual-studio-for-mac). - -## Creating a console application - -One of the most basic projects in Visual Studio for Mac is the Console Application. Here's how to do it. Once Visual Studio for Mac is open: - -1. On the **File** menu, point to **New Solution**. - -2. In the New Project dialog, there are 2 different templates for Console Application. There is one under Other -> .NET which targets the .NET Framework. The other template is under .NET Core -> App which targets .NET Core. Either template should work for the purpose of this article. - -3. Under console app, change C# to F# if needed. Choose the **Next** button to move forward! - -4. Give your project a name, and choose the options you want for the app. Notice, the preview pane to the side of the screen that will show the directory structure that will be created based on the options selected. - -5. Click **Create**. You should now see an F# project in the Solution Explorer. - -## Writing your code - -Let's get started by writing some code first. Make sure that the `Program.fs` file is open, and then replace its contents with the following: - -[!code-fsharp[HelloSquare](~/samples/snippets/fsharp/getting-started/hello-square.fs)] - -In the previous code sample, a function `square` has been defined which takes an input named `x` and multiplies it by itself. Because F# uses [Type Inference](../language-reference/type-inference.md), the type of `x` doesn't need to be specified. The F# compiler understands the types where multiplication is valid, and will assign a type to `x` based on how `square` is called. If you hover over `square`, you should see the following: - -```console -val square: x:int -> int -``` - -This is what is known as the function's type signature. It can be read like this: "Square is a function which takes an integer named x and produces an integer". Note that the compiler gave `square` the `int` type for now - this is because multiplication is not generic across *all* types, but rather is generic across a closed set of types. The F# compiler picked `int` at this point, but it will adjust the type signature if you call `square` with a different input type, such as a `float`. - -Another function, `main`, is defined, which is decorated with the `EntryPoint` attribute to tell the F# compiler that program execution should start there. It follows the same convention as other [C-style programming languages](https://en.wikipedia.org/wiki/Entry_point#C_and_C.2B.2B), where command-line arguments can be passed to this function, and an integer code is returned (typically `0`). - -It is in this function that we call the `square` function with an argument of `12`. The F# compiler then assigns the type of `square` to be `int -> int` (that is, a function which takes an `int` and produces an `int`). The call to `printfn` is a formatted printing function which uses a format string, similar to C-style programming languages, parameters which correspond to those specified in the format string, and then prints the result and a new line. - -## Running your code - -You can run the code and see results by clicking on **Run** from the top level menu and then **Start Without Debugging**. This will run the program without debugging and allows you to see the results. - -You should now see the following printed to the console window that Visual Studio for Mac popped up: - -```console -12 squared is 144! -``` - -Congratulations! You've created your first F# project in Visual Studio for Mac, written an F# function printed the results of calling that function, and run the project to see some results. - -## Using F# Interactive - -One of the best features of F# tooling in Visual Studio for Mac is the F# Interactive Window. It allows you to send code over to a process where you can call that code and see the result interactively. - -To begin using it, highlight the `square` function defined in your code. Next, click on **Edit** from the top level menu. Next select **Send selection to F# Interactive**. This executes the code in the F# Interactive Window. Alternatively, you can right click on the selection and choose **Send selection to F# Interactive**. You should see the F# Interactive Window appear with the following in it: - -```console -> - -val square: x: int -> int - -> -``` - -This shows the same function signature for the `square` function, which you saw earlier when you hovered over the function. Because `square` is now defined in the F# Interactive process, you can call it with different values: - -```console -> square 12;; -val it: int = 144 -> square 13;; -val it: int = 169 -``` - -This executes the function, binds the result to a new name `it`, and displays the type and value of `it`. Note that you must terminate each line with `;;`. This is how F# Interactive knows when your function call is finished. You can also define new functions in F# Interactive: - -```console -> let isOdd x = x % 2 <> 0;; - -val isOdd: x: int -> bool - -> isOdd 12;; -val it: bool = false -``` - -The above defines a new function, `isOdd`, which takes an `int` and checks to see if it's odd! You can call this function to see what it returns with different inputs. You can call functions within function calls: - -```console -> isOdd (square 15);; -val it: bool = true -``` - -You can also use the [pipe-forward operator](../language-reference/symbol-and-operator-reference/index.md) to pipeline the value into the two functions: - -```console -> 15 |> square |> isOdd;; -val it: bool = true -``` - -The pipe-forward operator, and more, are covered in later tutorials. - -This is only a glimpse into what you can do with F# Interactive. To learn more, check out [Interactive Programming with F#](../tools/fsharp-interactive/index.md). - -## Next steps - -If you haven't already, check out the [Tour of F#](../tour.md), which covers some of the core features of F#. It will give you an overview of some of the capabilities of F#, and provide ample code samples that you can copy into Visual Studio for Mac and run. There are also some great external resources you can use, showcased in the [F# Guide](../index.yml). - -## See also - -- [F# guide](../index.yml) -- [Tour of F#](../tour.md) -- [F# language guide](../language-reference/index.md) -- [Type inference](../language-reference/type-inference.md) -- [Symbol and operator reference](../language-reference/symbol-and-operator-reference/index.md) diff --git a/docs/fsharp/get-started/index.md b/docs/fsharp/get-started/index.md index 29ee4c6829299..9665c0ec32b53 100644 --- a/docs/fsharp/get-started/index.md +++ b/docs/fsharp/get-started/index.md @@ -11,11 +11,11 @@ You can get started with F# on your machine or online. There are multiple guides on how to install and use F# for the first time on your machine. You can use the following table to help in making a decision: -| OS | Prefer Visual Studio | Prefer Visual Studio Code | Prefer command line | -| -- |------------------------|--------------------------|-----------------------------|-------------------------| +| OS | Prefer Visual Studio | Prefer Visual Studio Code | Prefer command line | +| ------- |----------------------------------------------------------------|--------------------------------------------------------------|--------------------------------------------------------------| | Windows | [Get started with Visual Studio](get-started-visual-studio.md) | [Get started with Visual Studio Code](get-started-vscode.md) | [Get started with the .NET CLI](get-started-command-line.md) | -| macOS | [Get started with VS for Mac](get-started-with-visual-studio-for-mac.md) | [Get started with Visual Studio Code](get-started-vscode.md) | [Get started with the .NET CLI](get-started-command-line.md) | -| Linux | N/A | [Get started with Visual Studio Code](get-started-vscode.md) | [Get started with the .NET CLI](get-started-command-line.md) | +| macOS | N/A | [Get started with Visual Studio Code](get-started-vscode.md) | [Get started with the .NET CLI](get-started-command-line.md) | +| Linux | N/A | [Get started with Visual Studio Code](get-started-vscode.md) | [Get started with the .NET CLI](get-started-command-line.md) | In general, there is no specific way that is better than the rest. We recommend trying all ways to use F# on your machine to see what you like the best! diff --git a/docs/fsharp/get-started/install-fsharp.md b/docs/fsharp/get-started/install-fsharp.md index fda613b4dcebd..c43655bd43dc2 100644 --- a/docs/fsharp/get-started/install-fsharp.md +++ b/docs/fsharp/get-started/install-fsharp.md @@ -29,12 +29,6 @@ You can install F# in multiple ways, depending on your environment. The only plugin required for F# support in Visual Studio Code is [Ionide-fsharp](https://marketplace.visualstudio.com/items?itemName=Ionide.Ionide-fsharp). However, you can also install [Ionide-FAKE](https://marketplace.visualstudio.com/items?itemName=Ionide.Ionide-FAKE) to get [FAKE](https://fake.build/) support and [Ionide-Paket](https://marketplace.visualstudio.com/items?itemName=Ionide.Ionide-Paket) to get [Paket](https://fsprojects.github.io/Paket/) support. FAKE and Paket are additional F# community tools for building projects and managing dependencies, respectively. -## Install F# with Visual Studio for Mac - -F# is installed by default in [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link), no matter which configuration you choose. - -After the install completes, choose **Start Visual Studio**. You can also open Visual Studio through Finder on macOS. - ## Install F# on a build server If you're using .NET Core or .NET Framework via the .NET SDK, you simply need to install the .NET SDK on your build server. It has everything you need. diff --git a/docs/fsharp/toc.yml b/docs/fsharp/toc.yml index ac6e3e005d5f2..9deb876784f2a 100644 --- a/docs/fsharp/toc.yml +++ b/docs/fsharp/toc.yml @@ -16,8 +16,6 @@ items: href: get-started/get-started-vscode.md - name: F# with the .NET CLI href: get-started/get-started-command-line.md - - name: F# in Visual Studio for Mac - href: get-started/get-started-with-visual-studio-for-mac.md - name: F# language guide items: - name: Overview diff --git a/docs/fsharp/tools/development-tools.md b/docs/fsharp/tools/development-tools.md index 519e461269494..0c46c9b65914f 100644 --- a/docs/fsharp/tools/development-tools.md +++ b/docs/fsharp/tools/development-tools.md @@ -21,10 +21,6 @@ F# can be installed as part of [Visual Studio](https://visualstudio.microsoft.co F# can be installed as part of [Visual Studio Code](https://code.visualstudio.com/). See [Getting Started with F# in Visual Studio Code](../get-started/get-started-vscode.md). -### F# with Visual Studio for Mac - -F# can be installed as part of [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/). See [Getting Started with F# in Visual Studio for Mac](../get-started/get-started-with-visual-studio-for-mac.md). - ### Other development environments Other IDEs are available for F#, see [F# Tools](https://dotnet.microsoft.com/languages/fsharp/tools) diff --git a/docs/fsharp/tools/fsharp-interactive/index.md b/docs/fsharp/tools/fsharp-interactive/index.md index 7b757ca6046ba..8684b1f1ac6eb 100644 --- a/docs/fsharp/tools/fsharp-interactive/index.md +++ b/docs/fsharp/tools/fsharp-interactive/index.md @@ -88,7 +88,7 @@ dotnet fsi Script.fsx [1; 9; 25; 49; 81] ``` -F# scripting is natively supported in [Visual Studio](../../get-started/get-started-visual-studio.md), [Visual Studio Code](../../get-started/get-started-vscode.md), and [Visual Studio for Mac](../../get-started/get-started-with-visual-studio-for-mac.md). +F# scripting is natively supported in [Visual Studio](../../get-started/get-started-visual-studio.md) and [Visual Studio Code](../../get-started/get-started-vscode.md). ## Referencing packages in F# Interactive diff --git a/docs/fundamentals/code-analysis/code-style-rule-options.md b/docs/fundamentals/code-analysis/code-style-rule-options.md index d88a37b48efc8..91c7eceb821d7 100644 --- a/docs/fundamentals/code-analysis/code-style-rule-options.md +++ b/docs/fundamentals/code-analysis/code-style-rule-options.md @@ -33,7 +33,6 @@ To help you get started, here's an example *.editorconfig* file with the default > > - In Visual Studio, you can add the following default .NET .editorconfig file to your project from the **Add New Item** dialog box. For detailed steps, see [Add and remove EditorConfig files](/visualstudio/ide/create-portable-custom-editor-options?#add-and-remove-editorconfig-files). > - For Visual Studio Code, you can use the [EditorConfig for VS Code plugin](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) to override user/workspace settings with settings found in .editorconfig files. -> - For information about using .editorconfig files in Visual Studio for Mac, see [Creating and editing a custom EditorConfig file](/visualstudio/mac/editorconfig). ```ini # Remove the line below if you want to inherit .editorconfig settings from higher directories diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1036.md b/docs/fundamentals/code-analysis/quality-rules/ca1036.md index 5114299764df8..b3c04be4de301 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1036.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1036.md @@ -10,6 +10,9 @@ helpviewer_keywords: - CA1036 author: gewarren ms.author: gewarren +dev_langs: +- CSharp +- VB --- # CA1036: Override methods on comparable types @@ -35,23 +38,42 @@ Types that define a custom sort order implement the in To fix a violation of this rule, override . If your programming language supports operator overloading, supply the following operators: -- op_Equality -- op_Inequality -- op_LessThan -- op_GreaterThan - -In C#, the tokens that are used to represent these operators are as follows: +- `op_Equality` +- `op_Inequality` +- `op_LessThan` +- `op_GreaterThan` ```csharp -== -!= -< -> +// In C#, implement these operators. +public static bool operator ==(SampleClass? one, SampleClass? other) { } +public static bool operator !=(SampleClass? one, SampleClass? other) { } +public static bool operator <(SampleClass? one, SampleClass? other) { } +public static bool operator >(SampleClass? one, SampleClass? other) { } +``` + +```vb +' In Visual Basic, implement these operators. + +Public Shared Operator =(one As SampleClass, other As SampleClass) As Boolean + ... +End Operator + +Public Shared Operator <>(one As SampleClass, other As SampleClass) As Boolean + ... +End Operator + +Public Shared Operator <(one As SampleClass, other As SampleClass) As Boolean + ... +End Operator + +Public Shared Operator >(one As SampleClass, other As SampleClass) As Boolean + ... +End Operator ``` ## When to suppress warnings -It is safe to suppress a warning from rule CA1036 when the violation is caused by missing operators and your programming language does not support operator overloading, as is the case with Visual Basic. If you determine that implementing the operators does not make sense in your app context, it's also safe to suppress a warning from this rule when it fires on equality operators other than op_Equality. However, you should always override op_Equality and the == operator if you override . +It's safe to suppress a warning from rule CA1036 when the violation is caused by missing operators and your programming language does not support operator overloading. If you determine that implementing the operators does not make sense in your app context, it's also safe to suppress a warning from this rule when it fires on equality operators other than `op_Equality`. However, you should always override `op_Equality` and the `==` operator if you override . ## Suppress a warning @@ -87,10 +109,12 @@ You can configure this option for just this rule, for all rules it applies to, o The following code contains a type that correctly implements . Code comments identify the methods that satisfy various rules that are related to and the interface. :::code language="csharp" source="snippets/csharp/all-rules/ca1036.cs" id="snippet1"::: +:::code language="vb" source="snippets/vb/all-rules/ca1036.vb" id="snippet1"::: The following application code tests the behavior of the implementation that was shown earlier. :::code language="csharp" source="snippets/csharp/all-rules/ca1036.cs" id="snippet2"::: +:::code language="vb" source="snippets/vb/all-rules/ca1036.vb" id="snippet2"::: ## See also diff --git a/docs/fundamentals/code-analysis/quality-rules/ca1852.md b/docs/fundamentals/code-analysis/quality-rules/ca1852.md index 7fbea618c67cd..08bde169e8b55 100644 --- a/docs/fundamentals/code-analysis/quality-rules/ca1852.md +++ b/docs/fundamentals/code-analysis/quality-rules/ca1852.md @@ -29,7 +29,7 @@ A type that's not accessible outside its assembly and has no subtypes within its ## Rule description -When a type isn't accessible outside its assembly and has no subtypes within its containing assembly, it can be safely sealed. Sealing types can improve performance. +When a type isn't accessible outside its assembly and has no subtypes within its containing assembly, it can be safely sealed. Sealing types can improve performance. For more information, see [Analyzer Proposal: Seal internal/private types](https://github.com/dotnet/runtime/issues/49944)]. If you apply to the assembly that's being analyzed, this rule doesn't flag types that aren't marked as `sealed` by default, because a field may be used by a friend assembly. To analyze the assembly anyway, see [Configure code to analyze](#configure-code-to-analyze). diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/Program.cs b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/Program.cs new file mode 100644 index 0000000000000..e221ad0970131 --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/Program.cs @@ -0,0 +1 @@ +TestCompare.Main1036("A", "B"); diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca1036.cs b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca1036.cs index f00e506b471ce..a7443668d5edc 100644 --- a/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca1036.cs +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/csharp/all-rules/ca1036.cs @@ -1,143 +1,134 @@ using System; using System.Globalization; -namespace ca1036 +// +// Valid ratings are between A and C. +// A is the highest rating; it is greater than any other valid rating. +// C is the lowest rating; it is less than any other valid rating. + +public class RatingInformation : IComparable, IComparable { - // - // Valid ratings are between A and C. - // A is the highest rating; it is greater than any other valid rating. - // C is the lowest rating; it is less than any other valid rating. + public string Rating { get; private set; } - public class RatingInformation : IComparable, IComparable + public RatingInformation(string rating) { - public string Rating - { - get; - private set; - } + ArgumentNullException.ThrowIfNull(rating); - public RatingInformation(string rating) + string v = rating.ToUpper(CultureInfo.InvariantCulture); + if (v.Length != 1 || + string.Compare(v, "C", StringComparison.Ordinal) > 0 || + string.Compare(v, "A", StringComparison.Ordinal) < 0) { - if (rating == null) - { - throw new ArgumentNullException("rating"); - } - - string v = rating.ToUpper(CultureInfo.InvariantCulture); - if (v.Length != 1 || string.Compare(v, "C", StringComparison.Ordinal) > 0 || string.Compare(v, "A", StringComparison.Ordinal) < 0) - { - throw new ArgumentException("Invalid rating value was specified.", "rating"); - } - - Rating = v; + throw new ArgumentException("Invalid rating value was specified.", nameof(rating)); } - public int CompareTo(object? obj) - { - if (obj == null) - { - return 1; - } - - if (obj is RatingInformation other) - { - return CompareTo(other); - } - - throw new ArgumentException("A RatingInformation object is required for comparison.", "obj"); - } + Rating = v; + } - public int CompareTo(RatingInformation? other) + public int CompareTo(object? obj) + { + if (obj == null) { - if (other is null) - { - return 1; - } - - // Ratings compare opposite to normal string order, - // so reverse the value returned by String.CompareTo. - return -string.Compare(this.Rating, other.Rating, StringComparison.OrdinalIgnoreCase); + return 1; } - public static int Compare(RatingInformation left, RatingInformation right) + if (obj is RatingInformation other) { - if (object.ReferenceEquals(left, right)) - { - return 0; - } - if (left is null) - { - return -1; - } - return left.CompareTo(right); + return CompareTo(other); } - // Omitting Equals violates rule: OverrideMethodsOnComparableTypes. - public override bool Equals(object? obj) - { - if (obj is RatingInformation other) - { - return this.CompareTo(other) == 0; - } - - return false; - } + throw new ArgumentException("A RatingInformation object is required for comparison.", nameof(obj)); + } - // Omitting getHashCode violates rule: OverrideGetHashCodeOnOverridingEquals. - public override int GetHashCode() + public int CompareTo(RatingInformation? other) + { + if (other is null) { - char[] c = this.Rating.ToCharArray(); - return (int)c[0]; + return 1; } - // Omitting any of the following operator overloads - // violates rule: OverrideMethodsOnComparableTypes. - public static bool operator ==(RatingInformation left, RatingInformation right) + // Ratings compare opposite to normal string order, + // so reverse the value returned by String.CompareTo. + return -string.Compare(Rating, other.Rating, StringComparison.OrdinalIgnoreCase); + } + + public static int Compare(RatingInformation left, RatingInformation right) + { + if (object.ReferenceEquals(left, right)) { - if (left is null) - { - return right is null; - } - return left.Equals(right); + return 0; } - public static bool operator !=(RatingInformation left, RatingInformation right) + if (left is null) { - return !(left == right); + return -1; } - public static bool operator <(RatingInformation left, RatingInformation right) + return left.CompareTo(right); + } + + // Omitting Equals violates rule: OverrideMethodsOnComparableTypes. + public override bool Equals(object? obj) + { + if (obj is RatingInformation other) { - return (Compare(left, right) < 0); + return CompareTo(other) == 0; } - public static bool operator >(RatingInformation left, RatingInformation right) + + return false; + } + + // Omitting getHashCode violates rule: OverrideGetHashCodeOnOverridingEquals. + public override int GetHashCode() + { + char[] c = Rating.ToCharArray(); + return (int)c[0]; + } + + // Omitting any of the following operator overloads + // violates rule: OverrideMethodsOnComparableTypes. + public static bool operator ==(RatingInformation left, RatingInformation right) + { + if (left is null) { - return (Compare(left, right) > 0); + return right is null; } + return left.Equals(right); } - // + public static bool operator !=(RatingInformation left, RatingInformation right) + { + return !(left == right); + } + public static bool operator <(RatingInformation left, RatingInformation right) + { + return (Compare(left, right) < 0); + } + public static bool operator >(RatingInformation left, RatingInformation right) + { + return (Compare(left, right) > 0); + } +} +// - // - public class Test +// +public class TestCompare +{ + public static void Main1036(params string[] args) { - public static void Main1036(string[] args) + if (args.Length < 2) { - if (args.Length < 2) - { - Console.WriteLine("usage - TestRatings string 1 string2"); - return; - } - RatingInformation r1 = new RatingInformation(args[0]); - RatingInformation r2 = new RatingInformation(args[1]); - string answer; - - if (r1.CompareTo(r2) > 0) - answer = "greater than"; - else if (r1.CompareTo(r2) < 0) - answer = "less than"; - else - answer = "equal to"; - - Console.WriteLine("{0} is {1} {2}", r1.Rating, answer, r2.Rating); + return; } + RatingInformation r1 = new(args[0]); + RatingInformation r2 = new(args[1]); + string answer; + + if (r1.CompareTo(r2) > 0) + answer = "greater than"; + else if (r1.CompareTo(r2) < 0) + answer = "less than"; + else + answer = "equal to"; + + Console.WriteLine("{0} is {1} {2}", r1.Rating, answer, r2.Rating); } - // } +// diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/Program.vb b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/Program.vb new file mode 100644 index 0000000000000..ce1cd9c2960e5 --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/Program.vb @@ -0,0 +1,5 @@ +Public Class Program + Public Shared Sub Main() + TestCompare.Main1036(New String() {"C", "B"}) + End Sub +End Class diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj index 0f5343a149b29..a108957937cbd 100644 --- a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/all-rules.vbproj @@ -4,12 +4,9 @@ Exe all_rules net8.0 + $(NoWarn);SYSLIB0050 - - - - diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1003-use-generic-event-handler-instances_1.vb b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1003-use-generic-event-handler-instances_1.vb index 4394e9d21e541..ea5fd681e4b24 100644 --- a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1003-use-generic-event-handler-instances_1.vb +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1003-use-generic-event-handler-instances_1.vb @@ -42,7 +42,7 @@ Namespace ca1003 Class Test - Shared Sub Main() + Shared Sub Main1003() Dim eventRaiser As New ClassThatRaisesEvent() Dim eventHandler As New ClassThatHandlesEvent(eventRaiser) diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1036.vb b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1036.vb new file mode 100644 index 0000000000000..553bdf81e5e8d --- /dev/null +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca1036.vb @@ -0,0 +1,101 @@ + +' +Imports System.Globalization + +Public Class RatingInformation + Implements IComparable + Implements IComparable(Of RatingInformation) + + Public Sub New(rating As String) + ArgumentNullException.ThrowIfNull(rating) + + Dim v As String = rating.ToUpper(CultureInfo.InvariantCulture) + If (v.Length <> 1 Or + String.Compare(v, "C", StringComparison.Ordinal) > 0 Or + String.Compare(v, "A", StringComparison.Ordinal) < 0) Then + Throw New ArgumentException("Invalid rating value was specified.", NameOf(rating)) + End If + + Me.Rating = v + End Sub + + Public ReadOnly Property Rating As String + + Public Function CompareTo(obj As Object) As Integer Implements IComparable.CompareTo + If (obj Is Nothing) Then Return 1 + If (TypeOf obj IsNot RatingInformation) Then Return 0 + Dim other As RatingInformation = DirectCast(obj, RatingInformation) + Return CompareTo(other) + End Function + + Public Function CompareTo(other As RatingInformation) As Integer Implements IComparable(Of RatingInformation).CompareTo + If (other Is Nothing) Then Return 1 + ' Ratings compare opposite To normal String order, + ' so reverse the value returned by String.CompareTo. + Return -String.Compare(Rating, other.Rating, StringComparison.OrdinalIgnoreCase) + End Function + + Public Shared Operator =(one As RatingInformation, other As RatingInformation) As Boolean + If (one Is Nothing) Then Return (other Is Nothing) + If (other Is Nothing) Then Return False + Return (one.Rating = other.Rating) + End Operator + + Public Shared Operator <>(one As RatingInformation, other As RatingInformation) As Boolean + If (one Is Nothing) Then Return (other IsNot Nothing) + If (other Is Nothing) Then Return True + Return (one.Rating <> other.Rating) + End Operator + + Public Shared Operator <(one As RatingInformation, other As RatingInformation) As Boolean + If (one Is Nothing) Then Return (other IsNot Nothing) + If (other Is Nothing) Then Return False + Return (one.Rating < other.Rating) + End Operator + + Public Shared Operator >(one As RatingInformation, other As RatingInformation) As Boolean + If (one Is Nothing) Then Return False + If (other Is Nothing) Then Return True + Return (one.Rating > other.Rating) + End Operator + + Public Overrides Function Equals(obj As Object) As Boolean + If ReferenceEquals(Me, obj) Then + Return True + End If + + If obj Is Nothing Then + Return False + End If + + Throw New NotImplementedException() + End Function + + Public Overrides Function GetHashCode() As Integer + Throw New NotImplementedException() + End Function +End Class +' + +' +Public Class TestCompare + Public Shared Sub Main1036(ByVal args As String()) + If (args.Length < 2) Then + Return + End If + Dim r1 As New RatingInformation(args(0)) + Dim r2 As New RatingInformation(args(1)) + Dim answer As String + + If (r1.CompareTo(r2) > 0) Then + answer = "greater than" + ElseIf (r1.CompareTo(r2) < 0) Then + answer = "less than" + Else + answer = "equal to" + End If + + Console.WriteLine("{0} is {1} {2}", r1.Rating, answer, r2.Rating) + End Sub +End Class +' diff --git a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2237-mark-iserializable-types-with-serializableattribute_1.vb b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2237-mark-iserializable-types-with-serializableattribute_1.vb index f2b2bf5ba7f10..c07faa5d2aa3c 100644 --- a/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2237-mark-iserializable-types-with-serializableattribute_1.vb +++ b/docs/fundamentals/code-analysis/quality-rules/snippets/vb/all-rules/ca2237-mark-iserializable-types-with-serializableattribute_1.vb @@ -1,6 +1,4 @@ -Imports System -Imports System.Runtime.Serialization -Imports System.Security.Permissions +Imports System.Runtime.Serialization Namespace ca2237 @@ -22,13 +20,11 @@ Namespace ca2237 End Sub Overridable Sub GetObjectData( - info As SerializationInfo, context As StreamingContext) _ - Implements ISerializable.GetObjectData + info As SerializationInfo, context As StreamingContext) Implements ISerializable.GetObjectData info.AddValue("baseValue", baseValue) End Sub - End Class End Namespace diff --git a/docs/fundamentals/implementations.md b/docs/fundamentals/implementations.md index 637c1fc7779cd..b1a3f3b594f5f 100644 --- a/docs/fundamentals/implementations.md +++ b/docs/fundamentals/implementations.md @@ -17,7 +17,7 @@ Each implementation of .NET includes the following components: There are four .NET implementations that Microsoft supports: -- .NET 6 and later versions +- .NET 5 and later versions - .NET Framework - Mono - UWP diff --git a/docs/fundamentals/networking/quic/quic-overview.md b/docs/fundamentals/networking/quic/quic-overview.md index 68dd58e9f4358..e30384e02c6f8 100644 --- a/docs/fundamentals/networking/quic/quic-overview.md +++ b/docs/fundamentals/networking/quic/quic-overview.md @@ -47,10 +47,14 @@ On Windows, msquic.dll is distributed as part of the .NET runtime, and no other > [!NOTE] > .NET 7+ is only compatible with 2.2+ versions of libmsquic. -The `libmsquic` package is required on Linux. This package is published in Microsoft's official Linux package repository, . You must add this repository to your package manager before installing the package. For more information, see [Linux Software Repository for Microsoft Products](/linux/packages). +The `libmsquic` package is required on Linux. This package is published in Microsoft's official Linux package repository, and is also available in some official repositories, such as the [Alpine Packages - libmsquic](https://pkgs.alpinelinux.org/packages?name=libmsquic&branch=edge&repo=&arch=&origin=yes&flagged=&maintainer=). + +#### Installing `libmsquic` from Microsoft's official Linux package repository + +You must add this repository to your package manager before installing the package. For more information, see [Linux Software Repository for Microsoft Products](/linux/packages). > [!CAUTION] -> Adding the Microsoft pacakge repository may conflict with your distribution's repository when your distribution's repository provides .NET and other Microsoft packages. To avoid or troubleshoot package mixups, review [Troubleshoot .NET errors related to missing files on Linux](../../../core/install/linux-package-mixup.md#whats-going-on). +> Adding the Microsoft package repository may conflict with your distribution's repository when your distribution's repository provides .NET and other Microsoft packages. To avoid or troubleshoot package mixups, review [Troubleshoot .NET errors related to missing files on Linux](../../../core/install/linux-package-mixup.md#whats-going-on). ##### Examples @@ -59,7 +63,7 @@ Here are some examples of using a package manager to install `libmsquic`: - **APT** ```bash - sudo apt-get libmsquic + sudo apt-get install libmsquic ``` - **APK** @@ -86,6 +90,27 @@ Here are some examples of using a package manager to install `libmsquic`: sudo yum install libmsquic ``` +#### Installing `libmsquic` from the Distribution Package Repository + +Installing `libmsquic` from distribution package repository is also possible, but currently this is only available for `Alpine`. + +##### Examples + +Here are some examples of using a package manager to install `libmsquic`: + +- **Alpine 3.21 and later** + +```bash +apk add libmsquic +``` + +- **Alpine 3.20 and older** + +```bash +# Get libmsquic from community repository edge branch. +apk add --repository=http://dl-cdn.alpinelinux.org/alpine/edge/community/ libmsquic +``` + ##### Dependencies of libmsquic All the following dependencies are stated in the `libmsquic` package manifest and are automatically installed by the package manager: diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 310af951e46ee..6f10b1f675226 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -133,26 +133,6 @@ items: - name: Create and publish a package href: /nuget/quickstart/create-and-publish-a-package-using-the-dotnet-cli?toc=/dotnet/fundamentals/toc.json&bc=/dotnet/breadcrumb/toc.json displayName: tutorials - - name: Use Visual Studio for Mac - items: - - name: Create a console app - href: ../core/tutorials/with-visual-studio-mac.md - displayName: tutorials, visual studio for mac, vs for mac, cli - - name: Debug an app - href: ../core/tutorials/debugging-with-visual-studio-mac.md - displayName: tutorials, visual studio for mac, vs for mac - - name: Publish an app - href: ../core/tutorials/publishing-with-visual-studio-mac.md - displayName: tutorials, visual studio for mac, vs for mac - - name: Create a library - href: ../core/tutorials/library-with-visual-studio-mac.md - displayName: tutorials, visual studio for mac, vs for mac - - name: Unit test a library - href: ../core/tutorials/testing-library-with-visual-studio-mac.md - displayName: tutorials, visual studio for mac, vs for mac - - name: Install and use a package - href: /nuget/quickstart/install-and-use-a-package-in-visual-studio-mac?toc=/dotnet/fundamentals/toc.json&bc=/dotnet/breadcrumb/toc.json - displayName: tutorials, visual studio for mac, vs for mac - name: More tutorials href: ../core/tutorials/index.md - name: What's new in .NET diff --git a/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md b/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md index f0ad0f01112d1..f822ec79f8931 100644 --- a/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md +++ b/docs/machine-learning/how-to-guides/how-to-use-the-automl-api.md @@ -22,7 +22,6 @@ To use the AutoML API, install the [`Microsoft.ML.AutoML`](https://www.nuget.org For more information on installing NuGet packages, see the following guides: - [Install and use a NuGet package in Visual Studio](/nuget/quickstart/install-and-use-a-package-in-visual-studio) -- [Install and use a package in Visual Studio for Mac](/nuget/quickstart/install-and-use-a-package-in-visual-studio-mac) - [Install and use a package (dotnet CLI)](/nuget/quickstart/install-and-use-a-package-using-the-dotnet-cli) ## Quick Start diff --git a/docs/navigate/devops-testing/toc.yml b/docs/navigate/devops-testing/toc.yml index d0825da987aff..a142a86181538 100644 --- a/docs/navigate/devops-testing/toc.yml +++ b/docs/navigate/devops-testing/toc.yml @@ -213,8 +213,16 @@ items: href: ../../core/testing/unit-testing-platform-exit-codes.md - name: Integration with dotnet test href: ../../core/testing/unit-testing-platform-integration-dotnet-test.md - - name: Testing platform SDK - href: https://github.com/microsoft/testfx/blob/main/docs/testingplatform/Index.md + - name: Testing platform Architecture + items: + - name: Overview + href: ../../core/testing/unit-testing-platform-architecture.md + - name: Capabilities + href: ../../core/testing/unit-testing-platform-architecture-capabilities.md + - name: Extensions + href: ../../core/testing/unit-testing-platform-architecture-extensions.md + - name: Services + href: ../../core/testing/unit-testing-platform-architecture-services.md - name: Run selective unit tests href: ../../core/testing/selective-unit-tests.md - name: Order unit tests diff --git a/docs/navigate/tools-diagnostics/toc.yml b/docs/navigate/tools-diagnostics/toc.yml index 205a5a79a7208..214d287f3aaa5 100644 --- a/docs/navigate/tools-diagnostics/toc.yml +++ b/docs/navigate/tools-diagnostics/toc.yml @@ -273,9 +273,6 @@ items: - name: Visual Studio displayName: ide,integrated development environment,vs href: /visualstudio/get-started/visual-studio-ide?toc=/dotnet/navigate/tools-diagnostics/toc.json&bc=/dotnet/breadcrumb/toc.json - - name: Visual Studio for Mac - displayName: ide,integrated development environment,vs for mac,macOS,Mac - href: /visualstudio/mac/ide-tour?toc=/dotnet/navigate/tools-diagnostics/toc.json&bc=/dotnet/breadcrumb/toc.json - name: Visual Studio Code displayName: ide,integrated development environment,code,vs code,oss ide, href: https://code.visualstudio.com/docs diff --git a/docs/orleans/deployment/snippets/service-fabric/.gitignore b/docs/orleans/deployment/snippets/service-fabric/.gitignore index 154e127228aa3..6242261b062c7 100644 --- a/docs/orleans/deployment/snippets/service-fabric/.gitignore +++ b/docs/orleans/deployment/snippets/service-fabric/.gitignore @@ -400,11 +400,6 @@ FodyWeavers.xsd # JetBrains Rider *.sln.iml -## -## Visual studio for Mac -## - - # globs Makefile.in *.userprefs diff --git a/docs/samples-and-tutorials/index.md b/docs/samples-and-tutorials/index.md index 9e112e914df70..ba744f21116b9 100644 --- a/docs/samples-and-tutorials/index.md +++ b/docs/samples-and-tutorials/index.md @@ -101,6 +101,6 @@ Many topics show source code and samples that are available for viewing or downl 1. Navigate within the repository's folders to the sample's location. The relative path to the sample's location appears in your browser's address bar when you follow the link to the sample. 1. To run a sample, you have several options: * Use the [.NET CLI](../core/tools/index.md): In a console window, navigate to the sample's folder and use dotnet CLI commands. - * Use [Visual Studio](https://visualstudio.microsoft.com/vs/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link) or [Visual Studio for Mac](https://visualstudio.microsoft.com/vs/mac/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link): Open the sample by selecting **File > Open > Project/Solution** from the menu bar, navigate to the sample project folder, and select the project file (*.csproj* or *.fsproj*). + * Use [Visual Studio](https://visualstudio.microsoft.com/vs/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link): Open the sample by selecting **File > Open > Project/Solution** from the menu bar, navigate to the sample project folder, and select the project file (*.csproj* or *.fsproj*). * Use [Visual Studio Code](https://code.visualstudio.com/): Open the sample by selecting **File > Open Folder** from the menu bar and selecting the sample's project folder. * Use a different IDE that supports .NET projects. diff --git a/docs/standard/net-standard.md b/docs/standard/net-standard.md index 151a169e3b93b..c0f2c6237696f 100644 --- a/docs/standard/net-standard.md +++ b/docs/standard/net-standard.md @@ -82,7 +82,7 @@ For more information, see [.NET Framework compatibility mode](../core/porting/th ## .NET Standard libraries and Visual Studio -To build .NET Standard libraries in Visual Studio, make sure you have [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2022), [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2019), or Visual Studio 2017 version 15.3 or later installed on Windows, or [Visual Studio for Mac version 7.1](https://visualstudio.microsoft.com/vs/mac/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link) or later installed on macOS. +To build .NET Standard libraries in Visual Studio, make sure you have [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2022), [Visual Studio 2019](https://visualstudio.microsoft.com/downloads/?utm_medium=microsoft&utm_source=learn.microsoft.com&utm_campaign=inline+link&utm_content=download+vs2019), or Visual Studio 2017 version 15.3 or later installed on Windows. If you only need to consume .NET Standard 2.0 libraries in your projects, you can also do that in Visual Studio 2015. However, you need NuGet client 3.6 or higher installed. You can download the NuGet client for Visual Studio 2015 from the [NuGet downloads](https://www.nuget.org/downloads) page. diff --git a/docs/standard/serialization/xml-schema-def-tool-gen.md b/docs/standard/serialization/xml-schema-def-tool-gen.md index c659c4543adb8..83fff63c83639 100644 --- a/docs/standard/serialization/xml-schema-def-tool-gen.md +++ b/docs/standard/serialization/xml-schema-def-tool-gen.md @@ -23,10 +23,11 @@ _C:\\Program Files (x86)\\Microsoft SDKs\\Windows\\{version}\\bin\\NETFX {versio 2. Pass the XML Schema as an argument to the XML Schema Definition tool, which creates a set of classes that are precisely matched to the XML Schema, for example: ```console - xsd mySchema.xsd + xsd mySchema.xsd /classes ``` - - The tool can only process schemas that reference the World Wide Web Consortium XML specification of March 16, 2001. In other words, the XML Schema namespace must be `"http://www.w3.org/2001/XMLSchema"`, as shown in the following example. + + (The `/classes` option in this command is used to generate classes for the `mySchema` schema.) + The tool can only process schemas that reference the World Wide Web Consortium XML specification of March 16, 2001. In other words, the XML Schema namespace must be `"http://www.w3.org/2001/XMLSchema"`, as shown in the following example. ```xml diff --git a/docs/whats-new/index.yml b/docs/whats-new/index.yml index 949e2e8a2fab3..87bf01b73c14e 100644 --- a/docs/whats-new/index.yml +++ b/docs/whats-new/index.yml @@ -102,7 +102,5 @@ landingContent: url: /aspnet/core/release-notes/aspnetcore-8.0 - text: Visual Studio 2022 url: /visualstudio/releases/2022/release-notes - - text: Visual Studio 2022 for Mac - url: /visualstudio/releases/2022/mac-release-notes - text: Visual Studio Code url: https://code.visualstudio.com/updates diff --git a/includes/vs-mac-eol.md b/includes/vs-mac-eol.md deleted file mode 100644 index ccf0c055d6b5d..0000000000000 --- a/includes/vs-mac-eol.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -author: tdykstra -ms.author: tdykstra -ms.date: 09/07/2023 -ms.topic: include ---- -> [!IMPORTANT] -> Microsoft has announced the retirement of Visual Studio for Mac. Visual Studio for Mac will no longer be supported starting August 31, 2024. Alternatives include: -> -> * Visual Studio Code with the [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) and related extensions, such as [.NET MAUI](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-maui) and [Unity](https://marketplace.visualstudio.com/items?itemName=visualstudiotoolsforunity.vstuc). -> * Visual Studio running on Windows in a VM on Mac. -> * Visual Studio running on Windows in a [VM in the Cloud](https://aka.ms/devbox). -> -> For more information, see [Visual Studio for Mac retirement announcement](https://devblogs.microsoft.com/visualstudio/visual-studio-for-mac-retirement-announcement).