diff --git a/docs/architecture/containerized-lifecycle/Microsoft-platform-tools-containerized-apps/index.md b/docs/architecture/containerized-lifecycle/Microsoft-platform-tools-containerized-apps/index.md index e13432d419b61..843f161ba9888 100644 --- a/docs/architecture/containerized-lifecycle/Microsoft-platform-tools-containerized-apps/index.md +++ b/docs/architecture/containerized-lifecycle/Microsoft-platform-tools-containerized-apps/index.md @@ -10,7 +10,7 @@ ms.date: 02/15/2019 Figure 3-1 shows the main pillars in the life cycle of Docker apps classified by the type of work delivered by multiple teams (app-development, DevOps infrastructure processes, and IT management and operations). Usually, in the enterprise, the profiles of "the persona" responsible for each area are different. So are their skills. :::image type="complex" source="./media/index/microsoft-tools-contanerized-docker-app.png" alt-text="Diagram showing the Microsoft tools needed to maintain Docker apps."::: -Microsoft tools. For the Develop/Design workload: Docker engine for Windows, VS and VS Code, .NET Core, Azure Kubernetes Service. For the Build/Test/Ship workload: Azure DevOps, Team Foundation Server, Docker CLI, Azure Kubernetes Service. For the Run/Monitor/Manage workload: Azure Monitor, Azure Portal Azure Kubernetes Services, Service Fabric, other orchestrators. +Microsoft tools. For the Develop/Design workload: Docker engine for Windows, Visual Studio and Visual Studio Code, .NET Core, Azure Kubernetes Service. For the Build/Test/Ship workload: Azure DevOps, Team Foundation Server, Docker CLI, Azure Kubernetes Service. For the Run/Monitor/Manage workload: Azure Monitor, Azure portal, Azure Kubernetes Services, Service Fabric, other orchestrators. :::image-end::: **Figure 3-1.** Main pillars in the life cycle for containerized Docker applications with Microsoft platform and tools diff --git a/docs/architecture/serverless/serverless-business-scenarios.md b/docs/architecture/serverless/serverless-business-scenarios.md index 3cab0a92946ae..4270e2a2f5c04 100644 --- a/docs/architecture/serverless/serverless-business-scenarios.md +++ b/docs/architecture/serverless/serverless-business-scenarios.md @@ -87,13 +87,13 @@ This sample is a generic function (`.csx` file) that can be used to convert any ## Serverless for mobile -Azure Functions are easy to implement and maintain, and accessible through HTTP. They are a great way to implement an API for a mobile application. Microsoft offers great cross-platform tools for iOS, Android, and Windows with Xamarin. As such, Xamarin and Azure Functions are working great together. This article shows how to implement an Azure Function in the Azure Web Portal or in Visual Studio at first, and build a cross-platform client with Xamarin.Forms, running on Android, iOS, and Windows. +Azure Functions are easy to implement and maintain, and accessible through HTTP. They are a great way to implement an API for a mobile application. Microsoft offers great cross-platform tools for iOS, Android, and Windows with Xamarin. As such, Xamarin and Azure Functions are working great together. This article shows how to implement an Azure Function in the Azure portal or in Visual Studio at first, and build a cross-platform client with Xamarin.Forms running on Android, iOS, and Windows. [Implementing a simple Azure Function with a Xamarin.Forms client](https://docs.microsoft.com/samples/azure-samples/functions-xamarin-getting-started/implementing-a-simple-azure-function-with-a-xamarinforms-client/) ## Serverless messaging -This sample shows how to utilize Durable Functions' fan out pattern to load an arbitrary number of messages across any number of sessions/partitions. It targets Service Bus, Event Hubs, or Storage Queues. The sample also adds the ability to consume those messages with another Azure Function and load the resulting timing data in to another Event Hub. The data is then ingested into analytics services like Azure Data Explorer. +This sample shows how to utilize Durable Functions' fan-out pattern to load an arbitrary number of messages across any number of sessions/partitions. It targets Service Bus, Event Hubs, or Storage Queues. The sample also adds the ability to consume those messages with another Azure Function and load the resulting timing data in to another Event Hub. The data is then ingested into analytics services like Azure Data Explorer. [Produce and Consume messages through Service Bus, Event Hubs, and Storage Queues with Azure Functions](https://docs.microsoft.com/samples/azure-samples/durable-functions-producer-consumer/product-consume-messages-az-functions/) diff --git a/docs/core/compatibility/2.2-3.0.md b/docs/core/compatibility/2.2-3.0.md index 07ec61f515d94..3ab6de1d526e8 100644 --- a/docs/core/compatibility/2.2-3.0.md +++ b/docs/core/compatibility/2.2-3.0.md @@ -267,7 +267,7 @@ If you're migrating from version 2.2 to version 3.0 of .NET Core, ASP.NET Core, - [Floating point formatting and parsing behavior changes](#floating-point-formatting-and-parsing-behavior-changed) - [Floating-point parsing operations no longer fail or throw an OverflowException](#floating-point-parsing-operations-no-longer-fail-or-throw-an-overflowexception) - [InvalidAsynchronousStateException moved to another assembly](#invalidasynchronousstateexception-moved-to-another-assembly) -- [NET Core 3.0 follows Unicode best practices when replacing ill-formed UTF-8 byte sequences](#net-core-30-follows-unicode-best-practices-when-replacing-ill-formed-utf-8-byte-sequences) +- [Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines](#replacing-ill-formed-utf-8-byte-sequences-follows-unicode-guidelines) - [TypeDescriptionProviderAttribute moved to another assembly](#typedescriptionproviderattribute-moved-to-another-assembly) - [JSON serializer exception type changed from JsonException to NotSupportedException](#json-serializer-exception-type-changed-from-jsonexception-to-notsupportedexception) - [Change in semantics of (string)null in Utf8JsonWriter](#change-in-semantics-of-stringnull-in-utf8jsonwriter) diff --git a/docs/core/compatibility/2.2-3.1.md b/docs/core/compatibility/2.2-3.1.md index 38bef24ac15e0..b5cf5f047a1b2 100644 --- a/docs/core/compatibility/2.2-3.1.md +++ b/docs/core/compatibility/2.2-3.1.md @@ -270,7 +270,7 @@ If you're migrating from version 2.2 to version 3.1 of .NET Core, ASP.NET Core, - [Floating point formatting and parsing behavior changes](#floating-point-formatting-and-parsing-behavior-changed) - [Floating-point parsing operations no longer fail or throw an OverflowException](#floating-point-parsing-operations-no-longer-fail-or-throw-an-overflowexception) - [InvalidAsynchronousStateException moved to another assembly](#invalidasynchronousstateexception-moved-to-another-assembly) -- [NET Core 3.0 follows Unicode best practices when replacing ill-formed UTF-8 byte sequences](#net-core-30-follows-unicode-best-practices-when-replacing-ill-formed-utf-8-byte-sequences) +- [Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines](#replacing-ill-formed-utf-8-byte-sequences-follows-unicode-guidelines) - [TypeDescriptionProviderAttribute moved to another assembly](#typedescriptionproviderattribute-moved-to-another-assembly) - [JSON serializer exception type changed from JsonException to NotSupportedException](#json-serializer-exception-type-changed-from-jsonexception-to-notsupportedexception) - [Change in semantics of (string)null in Utf8JsonWriter](#change-in-semantics-of-stringnull-in-utf8jsonwriter) diff --git a/docs/core/compatibility/3.1-5.0.md b/docs/core/compatibility/3.1-5.0.md index 809a5d8beed8e..b9c99375c6d08 100644 --- a/docs/core/compatibility/3.1-5.0.md +++ b/docs/core/compatibility/3.1-5.0.md @@ -41,12 +41,17 @@ If you're migrating from version 3.1 of .NET Core, ASP.NET Core, or EF Core to v ## Windows Forms - [Removed status bar controls](#removed-status-bar-controls) -- [WinForms APIs now throw ArgumentNullException](#winforms-apis-now-throw-argumentnullexception) +- [WinForms methods now throw ArgumentException](#winforms-methods-now-throw-argumentexception) +- [WinForms methods now throw ArgumentNullException](#winforms-methods-now-throw-argumentnullexception) [!INCLUDE [winforms-deprecated-controls](../../../includes/core-changes/windowsforms/5.0/winforms-deprecated-controls.md)] *** +[!INCLUDE [invalid-args-cause-argumentexception](../../../includes/core-changes/windowsforms/5.0/invalid-args-cause-argumentexception.md)] + +*** + [!INCLUDE [null-args-cause-argumentnullexception](../../../includes/core-changes/windowsforms/5.0/null-args-cause-argumentnullexception.md)] *** diff --git a/docs/core/compatibility/corefx.md b/docs/core/compatibility/corefx.md index 9cdeb94366cce..71b92cd9af53a 100644 --- a/docs/core/compatibility/corefx.md +++ b/docs/core/compatibility/corefx.md @@ -16,7 +16,7 @@ The following breaking changes are documented on this page: | [Floating point formatting and parsing behavior changes](#floating-point-formatting-and-parsing-behavior-changed) | 3.0 | | [Floating-point parsing operations no longer fail or throw an OverflowException](#floating-point-parsing-operations-no-longer-fail-or-throw-an-overflowexception) | 3.0 | | [InvalidAsynchronousStateException moved to another assembly](#invalidasynchronousstateexception-moved-to-another-assembly) | 3.0 | -| [NET Core 3.0 follows Unicode best practices when replacing ill-formed UTF-8 byte sequences](#net-core-30-follows-unicode-best-practices-when-replacing-ill-formed-utf-8-byte-sequences) | 3.0 | +| [Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines](#replacing-ill-formed-utf-8-byte-sequences-follows-unicode-guidelines) | 3.0 | | [TypeDescriptionProviderAttribute moved to another assembly](#typedescriptionproviderattribute-moved-to-another-assembly) | 3.0 | | [ZipArchiveEntry no longer handles archives with inconsistent entry sizes](#ziparchiveentry-no-longer-handles-archives-with-inconsistent-entry-sizes) | 3.0 | | [JSON serializer exception type changed from JsonException to NotSupportedException](#json-serializer-exception-type-changed-from-jsonexception-to-notsupportedexception) | 3.0 | diff --git a/docs/core/compatibility/winforms.md b/docs/core/compatibility/winforms.md index 743ca8a85df7e..398ebb4d3110f 100644 --- a/docs/core/compatibility/winforms.md +++ b/docs/core/compatibility/winforms.md @@ -12,7 +12,8 @@ The following breaking changes are documented on this page: | Breaking change | Version introduced | | - | :-: | | [Removed status bar controls](#removed-status-bar-controls) | 5.0 | -| [WinForms APIs now throw ArgumentNullException](#winforms-apis-now-throw-argumentnullexception) | 5.0 | +| [WinForms methods now throw ArgumentException](#winforms-methods-now-throw-argumentexception) | 5.0 | +| [WinForms methods now throw ArgumentNullException](#winforms-methods-now-throw-argumentnullexception) | 5.0 | | [Removed controls](#removed-controls) | 3.1 | | [CellFormatting event not raised if tooltip is shown](#cellformatting-event-not-raised-if-tooltip-is-shown) | 3.1 | | [Control.DefaultFont changed to Segoe UI 9 pt](#default-control-font-changed-to-segoe-ui-9-pt) | 3.0 | @@ -35,6 +36,10 @@ The following breaking changes are documented on this page: *** +[!INCLUDE [invalid-args-cause-argumentexception](../../../includes/core-changes/windowsforms/5.0/invalid-args-cause-argumentexception.md)] + +*** + [!INCLUDE [null-args-cause-argumentnullexception](../../../includes/core-changes/windowsforms/5.0/null-args-cause-argumentnullexception.md)] *** diff --git a/docs/core/deploying/runtime-store.md b/docs/core/deploying/runtime-store.md index 3aace9bb0ebd4..b565501eb0b60 100644 --- a/docs/core/deploying/runtime-store.md +++ b/docs/core/deploying/runtime-store.md @@ -100,6 +100,12 @@ You deploy the resulting published app to an environment that has the packages d Specify multiple target manifests when publishing an app by repeating the option and path (for example, `--manifest manifest1.xml --manifest manifest2.xml`). When you do so, the app is trimmed for the union of packages specified in the target manifest files provided to the command. +If you deploy an application with a manifest dependency that's present in the deployment (the assembly is present in the *bin* folder), the runtime package store *isn't used* on the host for that assembly. The *bin* folder assembly is used regardless of its presence in the runtime package store on the host. + +The version of the dependency indicated in the manifest must match the version of the dependency in the runtime package store. If you have a version mismatch between the dependency in the target manifest and the version that exists in the runtime package store and the app doesn't include the required version of the package in its deployment, the app fails to start. The exception includes the name of the target manifest that called for the runtime package store assembly, which helps you troubleshoot the mismatch. + +When the deployment is *trimmed* on publish, only the specific versions of the manifest packages you indicate are withheld from the published output. The packages at the versions indicated must be present on the host for the app to start. + ## Specifying target manifests in the project file An alternative to specifying target manifests with the [`dotnet publish`](../tools/dotnet-publish.md) command is to specify them in the project file as a semicolon-separated list of paths under a **\** tag. @@ -112,15 +118,15 @@ An alternative to specifying target manifests with the [`dotnet publish`](../too Specify the target manifests in the project file only when the target environment for the app is well-known, such as for .NET Core projects. This isn't the case for open-source projects. The users of an open-source project typically deploy it to different production environments. These production environments generally have different sets of packages pre-installed. You can't make assumptions about the target manifest in such environments, so you should use the `--manifest` option of [`dotnet publish`](../tools/dotnet-publish.md). -## ASP.NET Core implicit store +## ASP.NET Core implicit store (.NET Core 2.0 only) The ASP.NET Core implicit store applies only to ASP.NET Core 2.0. We strongly recommend applications use ASP.NET Core 2.1 and later, which does **not** use the implicit store. ASP.NET Core 2.1 and later use the shared framework. -The runtime package store feature is used implicitly by an ASP.NET Core app when the app is deployed as a [framework-dependent deployment (FDD)](index.md#publish-runtime-dependent) app. The targets in [`Microsoft.NET.Sdk.Web`](https://github.com/aspnet/websdk) include manifests referencing the implicit package store on the target system. Additionally, any FDD app that depends on the `Microsoft.AspNetCore.All` package results in a published app that contains only the app and its assets and not the packages listed in the `Microsoft.AspNetCore.All` metapackage. It's assumed that those packages are present on the target system. +For .NET Core 2.0, the runtime package store feature is used implicitly by an ASP.NET Core app when the app is deployed as a [runtime-dependent deployment](index.md#publish-runtime-dependent) app. The targets in [`Microsoft.NET.Sdk.Web`](https://github.com/aspnet/websdk) include manifests referencing the implicit package store on the target system. Additionally, any runtime-dependent app that depends on the `Microsoft.AspNetCore.All` package results in a published app that contains only the app and its assets and not the packages listed in the `Microsoft.AspNetCore.All` metapackage. It's assumed that those packages are present on the target system. The runtime package store is installed on the host when the .NET Core SDK is installed. Other installers may provide the runtime package store, including Zip/tarball installations of the .NET Core SDK, `apt-get`, Red Hat Yum, the .NET Core Windows Server Hosting bundle, and manual runtime package store installations. -When deploying a [framework-dependent deployment (FDD)](index.md#publish-runtime-dependent) app, make sure that the target environment has the .NET Core SDK installed. If the app is deployed to an environment that doesn't include ASP.NET Core, you can opt out of the implicit store by specifying **\** set to `false` in the project file as in the following example: +When deploying a [runtime-dependent deployment](index.md#publish-runtime-dependent) app, make sure that the target environment has the .NET Core SDK installed. If the app is deployed to an environment that doesn't include ASP.NET Core, you can opt out of the implicit store by specifying **\** set to `false` in the project file as in the following example: ```xml @@ -129,13 +135,7 @@ When deploying a [framework-dependent deployment (FDD)](index.md#publish-runtime ``` > [!NOTE] -> For [self-contained deployment (SCD)](index.md#publish-self-contained) apps, it's assumed that the target system doesn't necessarily contain the required manifest packages. Therefore, **\** cannot be set to `true` for an SCD app. - -If you deploy an application with a manifest dependency that's present in the deployment (the assembly is present in the *bin* folder), the runtime package store *isn't used* on the host for that assembly. The *bin* folder assembly is used regardless of its presence in the runtime package store on the host. - -The version of the dependency indicated in the manifest must match the version of the dependency in the runtime package store. If you have a version mismatch between the dependency in the target manifest and the version that exists in the runtime package store and the app doesn't include the required version of the package in its deployment, the app fails to start. The exception includes the name of the target manifest that called for the runtime package store assembly, which helps you troubleshoot the mismatch. - -When the deployment is *trimmed* on publish, only the specific versions of the manifest packages you indicate are withheld from the published output. The packages at the versions indicated must be present on the host for the app to start. +> For [self-contained deployment](index.md#publish-self-contained) apps, it's assumed that the target system doesn't necessarily contain the required manifest packages. Therefore, **\** cannot be set to `true` for an self-contained app. ## See also diff --git a/docs/core/porting/index.md b/docs/core/porting/index.md index 63c9bf395ebd5..bfd20ada5e752 100644 --- a/docs/core/porting/index.md +++ b/docs/core/porting/index.md @@ -27,7 +27,7 @@ The following tools will be used throughout the process: ## Porting a solution -When there are multiple projects in a solution the porting can seem more complicated because you must address projects in a specific order. The conversion process should be a bottom-up approach, where the projects with no dependencies on other projects in the solution are converted first, and continue up through the whole solution. +When there are multiple projects in a solution, the porting can seem more complicated because you must address projects in a specific order. The conversion process should be a bottom-up approach, where the projects with no dependencies on other projects in the solution are converted first, and continue up through the whole solution. In order to identify the order projects should be migrated, you can use the following tools: @@ -40,7 +40,7 @@ We recommend you use the following process when porting your project to .NET Cor 1. Convert all of your `packages.config` dependencies to the [PackageReference](/nuget/consume-packages/package-references-in-project-files) format with the [conversion tool in Visual Studio](/nuget/consume-packages/migrate-packages-config-to-package-reference). - This step involves converting your dependencies from the legacy `packages.config` format. `packages.config` doesn't work on .NET Core, so this conversion is required if you have package dependencies. It also only requires the dependencies you are directly using in a project which will make later steps easier by reducing the amount of dependencies you must manage. + This step involves converting your dependencies from the legacy `packages.config` format. `packages.config` doesn't work on .NET Core, so this conversion is required if you have package dependencies. It also only requires the dependencies you are directly using in a project, which makes later steps easier by reducing the number of dependencies you must manage. 1. Convert your project file to the new SDK-style files structure. You can create new projects for .NET Core and copy over source files, or attempt to convert your existing project file with a tool. @@ -60,7 +60,7 @@ We recommend you use the following process when porting your project to .NET Cor While reading the reports generated by the analyzer, the important information is the actual APIs that are being used and not necessarily the percentage of support for the target platform. Many APIs have equivalent options in .NET Standard/Core, and so understanding the scenarios your library or application needs the API for will help determine the implication for portability. - There are some cases where APIs are not equivalent and you'll need to do some compiler preprocessor directives (i.e. `#if NET45`) to special case the platforms. At this point, you're project will still be targeting .NET Framework. For each of these targeted cases, it is recommended to use well-known conditionals that can be understood as a scenario. For example, AppDomain support in .NET Core is limited, but for the scenario of loading and unloading assemblies, there is a new API that is not available in .NET Core. A common way to handle this in code would be something like this: + There are some cases where APIs are not equivalent and you'll need to do some compiler preprocessor directives (that is, `#if NET45`) to special case the platforms. At this point, your project will still be targeting .NET Framework. For each of these targeted cases, it is recommended to use well-known conditionals that can be understood as a scenario. For example, AppDomain support in .NET Core is limited, but for the scenario of loading and unloading assemblies, there is a new API that's not available in .NET Core. A common way to handle this in code would be something like this: ```csharp #if FEATURE_APPDOMAIN_LOADING @@ -78,7 +78,7 @@ We recommend you use the following process when porting your project to .NET Cor 1. At this point, you can switch to targeting .NET Core (generally for applications) or .NET Standard (for libraries). - The choice between .NET Core and .NET Standard is largely dependent on where the project will be run. If it is a library that will be consumed by other applications or distributed via NuGet, the preference is usually to target .NET Standard. However, there may be APIs that are only available on .NET Core for performance or other reasons; if that's the case, .NET Core should be targeted with potentially a .NET Standard build available as well with reduced performance or funcitonality. By targeting .NET Standard, the project will be ready to run on new platforms (such as WebAssembly). If the project has dependencies on specific app frameworks (such as ASP.NET Core), then the target will be limited by what the dependencies support. + The choice between .NET Core and .NET Standard is largely dependent on where the project will be run. If it is a library that will be consumed by other applications or distributed via NuGet, the preference is usually to target .NET Standard. However, there may be APIs that are only available on .NET Core for performance or other reasons; if that's the case, .NET Core should be targeted with potentially a .NET Standard build available as well with reduced performance or functionality. By targeting .NET Standard, the project will be ready to run on new platforms (such as WebAssembly). If the project has dependencies on specific app frameworks (such as ASP.NET Core), then the target will be limited by what the dependencies support. If there are no preprocessor directives to conditional compile code for .NET Framework or .NET Standard, this will be as simple as finding the following in the project file: @@ -92,17 +92,17 @@ We recommend you use the following process when porting your project to .NET Cor netcoreapp3.1 ``` - However, if this is a library that you want to continue supporting .NET Framework specific builds for some reason, you can [multi-target](../../standard/library-guidance/cross-platform-targeting.md) by replacing it with the following: + However, if this is a library for which you want to continue supporting .NET Framework-specific builds, you can [multi-target](../../standard/library-guidance/cross-platform-targeting.md) by replacing it with the following: ```xml net472;netstandard2.0 ``` - If you're using Windows-specific APIs (such as registry access), you should install the [Windows Compatibility Pack](./windows-compat-pack.md). + If you're using Windows-specific APIs (such as registry access), install the [Windows Compatibility Pack](./windows-compat-pack.md). ## Next steps ->[!div class="nextstepaction"] ->[Analyze dependencies](third-party-deps.md) ->[Package NuGet Package](../deploying/creating-nuget-packages.md) ->[ASP.NET to ASP.NET Core Migration](/aspnet/core/migration/proper-to-2x) +> [!div class="nextstepaction"] +> [Analyze dependencies](third-party-deps.md) +> [Package NuGet Package](../deploying/creating-nuget-packages.md) +> [ASP.NET to ASP.NET Core Migration](/aspnet/core/migration/proper-to-2x) diff --git a/docs/core/tools/dotnet-add-reference.md b/docs/core/tools/dotnet-add-reference.md index b219b8104758c..5e2a8f96cfca5 100644 --- a/docs/core/tools/dotnet-add-reference.md +++ b/docs/core/tools/dotnet-add-reference.md @@ -46,7 +46,7 @@ The `dotnet add reference` command provides a convenient option to add project r - **`-f|--framework `** - Adds project references only when targeting a specific [framework](../../standard/frameworks.md). + Adds project references only when targeting a specific [framework](../../standard/frameworks.md) using the TFM format. - **`-h|--help`** @@ -54,7 +54,7 @@ The `dotnet add reference` command provides a convenient option to add project r - **`--interactive`** - Allows the command to stop and wait for user input or action (for example, to complete authentication). Available since .NET Core 3.0 SDK. + Allows the command to stop and wait for user input or action (typically used to complete authentication). Available since .NET Core 3.0 SDK. ## Examples diff --git a/docs/core/tools/dotnet-remove-reference.md b/docs/core/tools/dotnet-remove-reference.md index 4b9661056648e..4ffe6861afe8a 100644 --- a/docs/core/tools/dotnet-remove-reference.md +++ b/docs/core/tools/dotnet-remove-reference.md @@ -9,12 +9,13 @@ ms.date: 02/14/2020 ## Name -`dotnet remove reference` - Removes project-to-project references. +`dotnet remove reference` - Removes project-to-project (P2P) references. ## Synopsis ```dotnetcli -dotnet remove [] reference [-f|--framework ] +dotnet remove [] reference [-f|--framework ] + dotnet remove reference -h|--help ``` @@ -41,7 +42,7 @@ Project-to-project (P2P) references to remove. You can specify one or multiple p - **`-f|--framework `** - Removes the reference only when targeting a specific [framework](../../standard/frameworks.md). + Removes the reference only when targeting a specific [framework](../../standard/frameworks.md) using the TFM format. ## Examples diff --git a/docs/core/tools/dotnet-restore.md b/docs/core/tools/dotnet-restore.md index 258dac14cfde5..84904541ad9e7 100644 --- a/docs/core/tools/dotnet-restore.md +++ b/docs/core/tools/dotnet-restore.md @@ -26,7 +26,17 @@ dotnet restore -h|--help ## Description -The `dotnet restore` command uses NuGet to restore dependencies as well as project-specific tools that are specified in the project file. By default, the restoration of dependencies and tools are executed in parallel. +The `dotnet restore` command uses NuGet to restore dependencies as well as project-specific tools that are specified in the project file. In most cases, you don't need to explicitly use the `dotnet restore` command, since a NuGet restore is run implicitly if necessary when you run the following commands: + +- [`dotnet new`](dotnet-new.md) +- [`dotnet build`](dotnet-build.md) +- [`dotnet build-server`](dotnet-build-server.md) +- [`dotnet run`](dotnet-run.md) +- [`dotnet test`](dotnet-test.md) +- [`dotnet publish`](dotnet-publish.md) +- [`dotnet pack`](dotnet-pack.md) + +Sometimes, it might be inconvenient to run the implicit NuGet restore with these commands. For example, some automated systems, such as build systems, need to call `dotnet restore` explicitly to control when the restore occurs so that they can control network usage. To prevent the implicit NuGet restore, you can use the `--no-restore` flag with any of these commands to disable implicit restore. ### Specify feeds @@ -39,9 +49,9 @@ You can override the *nuget.config* feeds with the `-s` option. For information about how to use authenticated feeds, see [Consuming packages from authenticated feeds](/nuget/consume-packages/consuming-packages-authenticated-feeds). -### Package cache +### Global packages folder -For dependencies, you specify where the restored packages are placed during the restore operation using the `--packages` argument. If not specified, the default NuGet package cache is used, which is found in the `.nuget/packages` directory in the user's home directory on all operating systems. For example, */home/user1* on Linux or *C:\Users\user1* on Windows. +For dependencies, you can specify where the restored packages are placed during the restore operation using the `--packages` argument. If not specified, the default NuGet package cache is used, which is found in the `.nuget/packages` directory in the user's home directory on all operating systems. For example, */home/user1* on Linux or *C:\Users\user1* on Windows. ### Project-specific tooling @@ -65,22 +75,6 @@ There are three specific settings that `dotnet restore` ignores: This setting isn't applicable as [NuGet doesn't yet support cross-platform verification](https://github.com/NuGet/Home/issues/7939) of trusted packages. -## Implicit restore - -The `dotnet restore` command is run implicitly if necessary when you run the following commands: - -- [`dotnet new`](dotnet-new.md) -- [`dotnet build`](dotnet-build.md) -- [`dotnet build-server`](dotnet-build-server.md) -- [`dotnet run`](dotnet-run.md) -- [`dotnet test`](dotnet-test.md) -- [`dotnet publish`](dotnet-publish.md) -- [`dotnet pack`](dotnet-pack.md) - -In most cases, you don't need to explicitly use the `dotnet restore` command. - -Sometimes, it might be inconvenient to run `dotnet restore` implicitly. For example, some automated systems, such as build systems, need to call `dotnet restore` explicitly to control when the restore occurs so that they can control network usage. To prevent `dotnet restore` from running implicitly, you can use the `--no-restore` flag with any of these commands to disable implicit restore. - ## Arguments - **`ROOT`** diff --git a/docs/csharp/misc/cs0200.md b/docs/csharp/misc/cs0200.md index 691639caa7e22..09d9dde7d020e 100644 --- a/docs/csharp/misc/cs0200.md +++ b/docs/csharp/misc/cs0200.md @@ -7,12 +7,14 @@ helpviewer_keywords: - "CS0200" ms.assetid: 1990704a-edfa-4dbd-8477-d9c7aae58c96 --- -# Compiler Error CS0200 +# Compiler error CS0200 + Property or indexer 'property' cannot be assigned to -- it is read only -An attempt was made to assign a value to a [property](../programming-guide/classes-and-structs/using-properties.md), but the property does not have a set accessor or the assignment was outside of the constructor. Resolve the error by adding a set accessor. For more information, see [How to declare and use read write properties](../programming-guide/classes-and-structs/how-to-declare-and-use-read-write-properties.md). +An attempt was made to assign a value to a [property](../programming-guide/classes-and-structs/using-properties.md), but the property does not have a set accessor or the assignment was outside of the constructor. Resolve the error by adding a set accessor. For more information, see [How to declare and use read-write properties](../programming-guide/classes-and-structs/how-to-declare-and-use-read-write-properties.md). ## Examples + The following sample generates CS0200: ```csharp @@ -43,7 +45,7 @@ public class Example } ``` -The following sample uses [auto-implemented properties](../programming-guide/classes-and-structs/auto-implemented-properties.md), [object initializers](../programming-guide/classes-and-structs/object-and-collection-initializers.md), and still generates CS0200: +The following sample uses [auto-implemented properties](../programming-guide/classes-and-structs/auto-implemented-properties.md) and [object initializers](../programming-guide/classes-and-structs/object-and-collection-initializers.md) and still generates CS0200: ```csharp // CS0200.cs @@ -66,7 +68,7 @@ public class Example } ``` -Assignment to a property or indexer 'property' that is read only, can be achieved through adding a set accessor or by assigning to the property in the object's constructor. +To assign to a property or indexer 'property' that's read-only, add a set accessor or assign the value in the object's constructor. ```csharp public class Example diff --git a/docs/framework/unmanaged-api/profiling/cor-prf-gc-generation-enumeration.md b/docs/framework/unmanaged-api/profiling/cor-prf-gc-generation-enumeration.md index 5d74faa6b70a6..c6f3badf141f6 100644 --- a/docs/framework/unmanaged-api/profiling/cor-prf-gc-generation-enumeration.md +++ b/docs/framework/unmanaged-api/profiling/cor-prf-gc-generation-enumeration.md @@ -25,7 +25,8 @@ typedef enum { COR_PRF_GC_GEN_0 = 0, COR_PRF_GC_GEN_1 = 1, COR_PRF_GC_GEN_2 = 2, - COR_PRF_GC_LARGE_OBJECT_HEAP = 3 + COR_PRF_GC_LARGE_OBJECT_HEAP = 3, + COR_PRF_GC_PINNED_OBJECT_HEAP= 4 } COR_PRF_GC_GENERATION; ``` @@ -37,9 +38,12 @@ typedef enum { |`COR_PRF_GC_GEN_1`|The object is stored as generation 1.| |`COR_PRF_GC_GEN_2`|The object is stored as generation 2.| |`COR_PRF_GC_LARGE_OBJECT_HEAP`|The object is stored in the large-object heap.| +|`COR_PRF_GC_PINNED_OBJECT_HEAP`|The object is stored in the pinned-object heap.| ## Remarks - The garbage collector improves memory management performance by dividing objects into generations based on age. The garbage collector currently uses three generations, numbered 0, 1, and 2, plus a special heap segment that is used for large objects. Objects whose size is larger than a particular value are stored in the large-object heap. Other allocated objects start out belonging to generation 0. All objects that exist after garbage collection occurs in generation 0 are promoted to generation 1. Objects that exist after garbage collection occurs in generation 1 move into generation 2. + The garbage collector improves memory management performance by dividing objects into generations based on age. The garbage collector currently uses three generations, numbered 0, 1, and 2, and two special heap segments, one for large objects and one for pinned objects. + + Objects whose size is larger than a threshold value are stored in the large-object heap. Pinned objects can be allocated to the pinned-object heap to avoid the performance cost of allocating them on the normal heaps. Other allocated objects start out belonging to generation 0. All objects that exist after garbage collection occurs in generation 0 are promoted to generation 1. Objects that exist after garbage collection occurs in generation 1 move into generation 2. The use of generations means that the garbage collector has to work with only a subset of the allocated objects at any one time. diff --git a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md index e66e75636fb0b..5b683381cb1ee 100644 --- a/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md +++ b/docs/standard/data/xml/xml-schema-xsd-validation-with-xmlschemaset.md @@ -8,32 +8,33 @@ dev_langs: - "cpp" ms.assetid: 359b10eb-ec05-4cc6-ac96-c2b060afc4de --- -# XML Schema (XSD) Validation with XmlSchemaSet +# XML schema (XSD) validation with XmlSchemaSet + XML documents can be validated against an XML schema definition language (XSD) schema in an . -## Validating XML Documents +## Validate XML documents XML documents are validated by the method of the class. To validate an XML document, construct an object that contains an XML schema definition language (XSD) schema with which to validate the XML document. > [!NOTE] > The namespace contains extension methods that make it easy to validate an XML tree against an XSD file when using [LINQ to XML (C#)](../../../csharp/programming-guide/concepts/linq/linq-to-xml-overview.md) and [LINQ to XML (Visual Basic)](../../../visual-basic/programming-guide/concepts/linq/linq-to-xml.md). For more information on validating XML documents with LINQ to XML, see [How to validate using XSD (LINQ to XML) (C#)](../../../csharp/programming-guide/concepts/linq/how-to-validate-using-xsd-linq-to-xml.md) and [How to: Validate Using XSD (LINQ to XML) (Visual Basic)](../../../visual-basic/programming-guide/concepts/linq/how-to-validate-using-xsd-linq-to-xml.md). - An individual schema or a set of schemas (as an ) can be added to an by passing either one as a parameter to the method of . Note that when validating a document the target namespace of the document must match the target namespace of the schema in the schema set. + An individual schema or a set of schemas (as an ) can be added to an by passing either one as a parameter to the method of . When validating a document the target namespace of the document must match the target namespace of the schema in the schema set. The following is an example XML document. - [!code-xml[XSDInference Examples#5](../../../../samples/snippets/xml/VS_Snippets_Data/XSDInference Examples/XML/contosoBooks.xml#5)] + [!code-xml[XSDInference Examples #5](../../../../samples/snippets/xml/VS_Snippets_Data/XSDInference Examples/XML/contosoBooks.xml#5)] The following is the schema that validates the example XML document. - [!code-xml[XSDInference Examples#6](../../../../samples/snippets/xml/VS_Snippets_Data/XSDInference Examples/XML/contosoBooks.xsd#6)] + [!code-xml[XSDInference Examples #6](../../../../samples/snippets/xml/VS_Snippets_Data/XSDInference Examples/XML/contosoBooks.xsd#6)] In the code example that follows, the schema above is added to the property of the object. The object is passed as a parameter to the method of the object, which validates the XML document above. The property of the object is set to `Schema` to enforce validation of the XML document by the method of the object. A is added to the object to handle any or events raised by errors found during the validation process of both the XML document and the schema. - [!code-cpp[XmlSchemaSetOverall Example#1](../../../../samples/snippets/cpp/VS_Snippets_Data/XmlSchemaSetOverall Example/CPP/xmlschemasetexample.cpp#1)] - [!code-csharp[XmlSchemaSetOverall Example#1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaSetOverall Example/CS/xmlschemasetexample.cs#1)] - [!code-vb[XmlSchemaSetOverall Example#1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaSetOverall Example/VB/xmlschemasetexample.vb#1)] + [!code-cpp[XmlSchemaSetOverall Example #1](../../../../samples/snippets/cpp/VS_Snippets_Data/XmlSchemaSetOverall Example/CPP/xmlschemasetexample.cpp#1)] + [!code-csharp[XmlSchemaSetOverall Example #1](../../../../samples/snippets/csharp/VS_Snippets_Data/XmlSchemaSetOverall Example/CS/xmlschemasetexample.cs#1)] + [!code-vb[XmlSchemaSetOverall Example #1](../../../../samples/snippets/visualbasic/VS_Snippets_Data/XmlSchemaSetOverall Example/VB/xmlschemasetexample.vb#1)] ## See also diff --git a/docs/standard/memory-and-spans/memory-t-usage-guidelines.md b/docs/standard/memory-and-spans/memory-t-usage-guidelines.md index ac423069b8bf8..465f659492266 100644 --- a/docs/standard/memory-and-spans/memory-t-usage-guidelines.md +++ b/docs/standard/memory-and-spans/memory-t-usage-guidelines.md @@ -17,7 +17,7 @@ Since buffers can be passed around between APIs, and since buffers can sometimes - **Ownership**. The owner of a buffer instance is responsible for lifetime management, including destroying the buffer when it's no longer in use. All buffers have a single owner. Generally the owner is the component that created the buffer or that received the buffer from a factory. Ownership can also be transferred; **Component-A** can relinquish control of the buffer to **Component-B**, at which point **Component-A** may no longer use the buffer, and **Component-B** becomes responsible for destroying the buffer when it's no longer in use. -- **Consumption**. The consumer of a buffer instance is allowed to use the buffer instance by reading from it and possibly writing to it. Buffers can have one consumer at a time unless some external synchronization mechanism is provided. Note that the active consumer of a buffer isn't necessarily the buffer's owner. +- **Consumption**. The consumer of a buffer instance is allowed to use the buffer instance by reading from it and possibly writing to it. Buffers can have one consumer at a time unless some external synchronization mechanism is provided. The active consumer of a buffer isn't necessarily the buffer's owner. - **Lease**. The lease is the length of time that a particular component is allowed to be the consumer of the buffer. @@ -80,7 +80,7 @@ In this code: - The `WriteInt32ToBuffer` and `DisplayBufferToConsole` methods accept as a public API. Therefore, they are consumers of the buffer. And they only consume it one at a time. -Although the `WriteInt32ToBuffer` method is intended to write a value to the buffer, the `DisplayBufferToConsole` method isn't. To reflect this, it could have accepted an argument of type . For additional information on , see [Rule #2: Use ReadOnlySpan\ or ReadOnlyMemory\ if the buffer should be read-only](#rule-2). +Although the `WriteInt32ToBuffer` method is intended to write a value to the buffer, the `DisplayBufferToConsole` method isn't. To reflect this, it could have accepted an argument of type . For more information on , see [Rule #2: Use ReadOnlySpan\ or ReadOnlyMemory\ if the buffer should be read-only](#rule-2). ### "Ownerless" Memory\ instances @@ -104,7 +104,7 @@ Because a memory block is owned but is intended to be passed to multiple compone - While the stack-allocated nature of optimizes performance and makes the preferred type for operating on a memory block, it also subjects to some major restrictions. It is important to know when to use a and when to use . -The following are our recommendations for successfully using and its related types. Note that guidance that applies to and also applies to and unless we explicitly note otherwise. +The following are our recommendations for successfully using and its related types. Guidance that applies to and also applies to and unless we explicitly note otherwise. **Rule #1: For a synchronous API, use Span\ instead of Memory\ as a parameter if possible.** diff --git a/docs/whats-new/2019-10.md b/docs/whats-new/2019-10.md index 7d0b26646fc11..2058d475761bf 100644 --- a/docs/whats-new/2019-10.md +++ b/docs/whats-new/2019-10.md @@ -10,7 +10,7 @@ Welcome to what's new in .NET docs for October 2019. This article lists some of ## Architecture guides -- [Modules, handlers, and middleware](../architecture/blazor-for-web-forms-developers/middleware.md) - Add middleware chapter to blazor ebook +- [Modules, handlers, and middleware](../architecture/blazor-for-web-forms-developers/middleware.md) - Add middleware chapter to Blazor ebook ## .NET Core @@ -36,8 +36,8 @@ Welcome to what's new in .NET docs for October 2019. This article lists some of ### New articles -- [Reference assemblies](../standard/assembly/reference-assemblies.md) - Add reference assemblies topic -- [System.IO.Pipelines in .NET](../standard/io/pipelines.md) - pipeline doc - +- [Reference assemblies](../standard/assembly/reference-assemblies.md) - Add reference assemblies article +- [System.IO.Pipelines in .NET](../standard/io/pipelines.md) - Pipeline article ### Updated articles diff --git a/includes/core-changes/corefx/3.0/move-invalidasynchronousstateexception.md b/includes/core-changes/corefx/3.0/move-invalidasynchronousstateexception.md index 46b16b52d2865..9bf4214c72e00 100644 --- a/includes/core-changes/corefx/3.0/move-invalidasynchronousstateexception.md +++ b/includes/core-changes/corefx/3.0/move-invalidasynchronousstateexception.md @@ -14,7 +14,7 @@ Starting with .NET Core 3.0, it is found in the *System.ComponentModel.Primitive #### Recommended action -This change only affects applications that use reflection to load the by calling a method such as or an overload of that assumes the type is in a particular assembly. If that is the case, the assembly the assembly referenced in the method call should be updated to reflect the type's new assembly location. +This change only affects applications that use reflection to load the by calling a method such as or an overload of that assumes the type is in a particular assembly. If that is the case, update the assembly referenced in the method call to reflect the type's new assembly location. #### Category diff --git a/includes/core-changes/corefx/3.0/net-core-3-0-follows-unicode-utf8-best-practices.md b/includes/core-changes/corefx/3.0/net-core-3-0-follows-unicode-utf8-best-practices.md index 11397b213485d..b7f50eae6a04f 100644 --- a/includes/core-changes/corefx/3.0/net-core-3-0-follows-unicode-utf8-best-practices.md +++ b/includes/core-changes/corefx/3.0/net-core-3-0-follows-unicode-utf8-best-practices.md @@ -1,6 +1,6 @@ -### .NET Core 3.0 follows Unicode best practices when replacing ill-formed UTF-8 byte sequences +### Replacing ill-formed UTF-8 byte sequences follows Unicode guidelines -When the class encounters an ill-formed UTF-8 byte sequence during a byte-to-character transcoding operation, it will replace that sequence with a '�' (U+FFFD REPLACEMENT CHARACTER) character in the output string. .NET Core 3.0 differs from previous versions of .NET Core and the .NET Framework by following the Unicode best practice for performing this replacement during the transcoding operation. +When the class encounters an ill-formed UTF-8 byte sequence during a byte-to-character transcoding operation, it replaces that sequence with a '�' (U+FFFD REPLACEMENT CHARACTER) character in the output string. .NET Core 3.0 differs from previous versions of .NET Core and the .NET Framework by following the Unicode best practice for performing this replacement during the transcoding operation. This is part of a larger effort to improve UTF-8 handling throughout .NET, including by the new and types. The type was given improved error handling mechanics so that it produces output consistent with the newly introduced types. @@ -8,15 +8,15 @@ This is part of a larger effort to improve UTF-8 handling throughout .NET, inclu Starting with .NET Core 3.0, when transcoding bytes to characters, the class performs character substitution based on Unicode best practices. The substitution mechanism used is described by [The Unicode Standard, Version 12.0, Sec. 3.9 (PDF)](https://www.unicode.org/versions/Unicode12.0.0/ch03.pdf) in the heading titled _U+FFFD Substitution of Maximal Subparts_. -This behavior _only_ applies when the input byte sequence contains ill-formed UTF-8 data. Additionally, if the instance has been constructed with `throwOnInvalidBytes: true` (see the [UTF8Encoding constructor documentation](, the `UTF8Encoding` instance will continue to throw on invalid input rather than perform U+FFFD replacement. +This behavior _only_ applies when the input byte sequence contains ill-formed UTF-8 data. Additionally, if the instance has been constructed with `throwOnInvalidBytes: true`, the `UTF8Encoding` instance will continue to throw on invalid input rather than perform U+FFFD replacement. For more information about the `UTF8Encoding` constructor, see . -The following illustrates the impact of this change with an invalid 3-byte input: +The following table illustrates the impact of this change with an invalid 3-byte input: -|Ill-formed 3-byte input|Output before .NET Core 3.0|Output starting with .NET Core 3.0| -|---|---|---| -| `[ ED A0 90 ]` | `[ FFFD FFFD ]` (2-character output)| `[ FFFD FFFD FFFD ]` (3-character output)| +| Ill-formed 3-byte input | Output before .NET Core 3.0 | Output starting with .NET Core 3.0 | +|-------------------------|--------------------------------------|-------------------------------------------| +| `[ ED A0 90 ]` | `[ FFFD FFFD ]` (2-character output) | `[ FFFD FFFD FFFD ]` (3-character output) | -This 3-char output is the preferred output, according to _Table 3-9_ of the previously linked Unicode Standard PDF. +The 3-char output is the preferred output, according to _Table 3-9_ of the previously linked Unicode Standard PDF. #### Version introduced diff --git a/includes/core-changes/windowsforms/5.0/invalid-args-cause-argumentexception.md b/includes/core-changes/windowsforms/5.0/invalid-args-cause-argumentexception.md new file mode 100644 index 0000000000000..540400da4756a --- /dev/null +++ b/includes/core-changes/windowsforms/5.0/invalid-args-cause-argumentexception.md @@ -0,0 +1,40 @@ +### WinForms methods now throw ArgumentException + +Some Windows Forms methods now throw an for invalid arguments, where previously they did not. + +#### Change description + +Previously, passing arguments of an unexpected or incorrect type to certain Windows Forms methods would result in an indeterminate state. Starting in .NET 5.0, these methods now throw an when passed invalid arguments. + +Throwing an conforms to the behavior of the .NET runtime. It also improves the debugging experience by clearly communicating which argument is invalid. + +The following table lists the affected methods and parameters: + +| Method | Parameter name | Condition | Version added | +|-|-|-| +| | `item` | Argument is not of type . | 5.0 Preview 1 | + +#### Version introduced + +.NET 5.0 Preview 1 + +#### Recommended action + +- Update the code to prevent passing invalid arguments. +- If necessary, handle an when calling the method. + +#### Category + +Windows Forms + +#### Affected APIs + +- + + diff --git a/includes/core-changes/windowsforms/5.0/null-args-cause-argumentnullexception.md b/includes/core-changes/windowsforms/5.0/null-args-cause-argumentnullexception.md index 5b93dbab03936..e1c0954dc0f96 100644 --- a/includes/core-changes/windowsforms/5.0/null-args-cause-argumentnullexception.md +++ b/includes/core-changes/windowsforms/5.0/null-args-cause-argumentnullexception.md @@ -1,4 +1,4 @@ -### WinForms APIs now throw ArgumentNullException +### WinForms methods now throw ArgumentNullException Some Windows Forms methods now throw an for null arguments, where previously they threw a .