From 6a7c7298a873f51d270ff4723bfb574e44ff62a7 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Thu, 1 Jul 2021 22:12:55 +0000 Subject: [PATCH 01/27] Remove irrelevant section from trimming docs This looks like someone was documenting a workaround for trimming issues they encountered in previous versions: https://github.com/dotnet/runtime/issues/44260 It doesn't belong in these docs, and the analysis warnings should prevent such issues going forward. --- docs/core/deploying/trim-self-contained.md | 33 ---------------------- 1 file changed, 33 deletions(-) diff --git a/docs/core/deploying/trim-self-contained.md b/docs/core/deploying/trim-self-contained.md index 80ef67d064905..097c272b77482 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -36,39 +36,6 @@ When the code is indirectly referencing an assembly through reflection, you can ``` -### Support for SSL certificates - -If your app loads SSL certificates, such as in an ASP.NET Core app, you'll want to ensure that when trimming you prevent trimming assemblies that will help with loading SSL certificates. - -We can update our project file to include the following for ASP.NET Core 3.1: - -```xml - - ... - - - - - - - ... - -``` - -If we're using .Net 5.0, we can update our project file to include the following: - -```xml - - ... - - - - - - ... - -``` - ## Trim your app - CLI Trim your application using the [dotnet publish](../tools/dotnet-publish.md) command. When you publish your app, set the following properties: From dc4d3afcd9fa61aa3b9612a512feebcd52182405 Mon Sep 17 00:00:00 2001 From: Jamshed Damkewala Date: Thu, 1 Jul 2021 17:42:43 -0700 Subject: [PATCH 02/27] Update windows.md --- docs/core/install/windows.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/core/install/windows.md b/docs/core/install/windows.md index 7337a9a9bf50b..50bdefd4af0c9 100644 --- a/docs/core/install/windows.md +++ b/docs/core/install/windows.md @@ -44,6 +44,7 @@ Windows 10 versions end-of-service dates are segmented by edition. Only **Home** | Windows 7 SP1 [ESU][esu] | ✔️ | ✔️ | ✔️ | | Windows Server 2019
Windows Server 2016
Windows Server 2012 R2
| ✔️ | ✔️ | ✔️ | | Windows Server Core 2012 R2 | ✔️ | ✔️ | ✔️ | +| Windows Server Core 2012 | ✔️ | ✔️ | ✔️ | | Nano Server, Version 1809+ | ✔️ | ✔️ | ✔️ | | Nano Server, Version 1803 | ✔️ | ✔️ | ❌ | From 2ff59e22699a2246e697dec7341914541f032958 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Thu, 1 Jul 2021 18:31:13 -0700 Subject: [PATCH 03/27] Fix linter (#24961) --- docs/csharp/language-reference/attributes/general.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/csharp/language-reference/attributes/general.md b/docs/csharp/language-reference/attributes/general.md index e70b0a6cc1b5f..0eb6d32d2418f 100644 --- a/docs/csharp/language-reference/attributes/general.md +++ b/docs/csharp/language-reference/attributes/general.md @@ -47,7 +47,6 @@ In C# 10, you can use constant string interpolation and the `nameof` operator to :::code language="csharp" source="snippets/ObsoleteExample.cs" id="Snippet2" ::: - ## `AttributeUsage` attribute The `AttributeUsage` attribute determines how a custom attribute class can be used. is an attribute you apply to custom attribute definitions. The `AttributeUsage` attribute enables you to control: From 955bf2cfa6a9ad1e5a75912d9ad15499b20373ad Mon Sep 17 00:00:00 2001 From: Sourabh Shirhatti Date: Fri, 2 Jul 2021 07:56:33 -0700 Subject: [PATCH 04/27] Info on when counters were first introduced (#24956) * Info on when counters were first introduced * Update available-counters.md * Update docs/core/diagnostics/available-counters.md Co-authored-by: Bill Wagner --- docs/core/diagnostics/available-counters.md | 192 ++++++++++---------- 1 file changed, 96 insertions(+), 96 deletions(-) diff --git a/docs/core/diagnostics/available-counters.md b/docs/core/diagnostics/available-counters.md index c5113fe00136c..c1b3e5a755372 100644 --- a/docs/core/diagnostics/available-counters.md +++ b/docs/core/diagnostics/available-counters.md @@ -13,128 +13,128 @@ The .NET runtime and libraries implement and publish several [`EventCounter`](./ The following counters are published as part of .NET runtime (CoreCLR) and are maintained in the [`RuntimeEventSource.cs`](https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/Diagnostics/Tracing/RuntimeEventSource.cs). -| Counter | Description | -|--|--| -| :::no-loc text="% Time in GC since last GC"::: (`time-in-gc`) | The percent of time in GC since the last GC | -| :::no-loc text="Allocation Rate"::: (`alloc-rate`) | The number of bytes allocated per update interval | -| :::no-loc text="CPU Usage"::: (`cpu-usage`) | The percent of the process's CPU usage relative to all of the system CPU resources | -| :::no-loc text="Exception Count"::: (`exception-count`) | The number of exceptions that have occurred | -| :::no-loc text="GC Heap Size"::: (`gc-heap-size`) | The number of bytes thought to be allocated based on | -| :::no-loc text="Gen 0 GC Count"::: (`gen-0-gc-count`) | The number of times GC has occurred for Gen 0 per update interval | -| :::no-loc text="Gen 0 Size"::: (`gen-0-size`) | The number of bytes for Gen 0 GC | -| :::no-loc text="Gen 1 GC Count"::: (`gen-1-gc-count`) | The number of times GC has occurred for Gen 1 per update interval | -| :::no-loc text="Gen 1 Size"::: (`gen-1-size`) | The number of bytes for Gen 1 GC | -| :::no-loc text="Gen 2 GC Count"::: (`gen-2-gc-count`) | The number of times GC has occurred for Gen 2 per update interval | -| :::no-loc text="Gen 2 Size"::: (`gen-2-size`) | The number of bytes for Gen 2 GC | -| :::no-loc text="LOH Size"::: (`loh-size`) | The number of bytes for the large object heap | -| :::no-loc text="POH Size"::: (`poh-size`) | The number of bytes for the pinned object heap (available on .NET 5 and later versions) | -| :::no-loc text="GC Fragmentation"::: (`gc-fragmentation`) | The GC Heap Fragmentation (available on .NET 5 and later versions) | -| :::no-loc text="Monitor Lock Contention Count"::: (`monitor-lock-contention-count`) | The number of times there was contention when trying to take the monitor's lock, based on | -| :::no-loc text="Number of Active Timers"::: (`active-timer-count`) | The number of instances that are currently active, based on | -| :::no-loc text="Number of Assemblies Loaded"::: (`assembly-count`) | The number of instances loaded into a process at a point in time | -| :::no-loc text="ThreadPool Completed Work Item Count"::: (`threadpool-completed-items-count`) | The number of work items that have been processed so far in the | -| :::no-loc text="ThreadPool Queue Length"::: (`threadpool-queue-length`) | The number of work items that are currently queued to be processed in the | -| :::no-loc text="ThreadPool Thread Count"::: (`threadpool-thread-count`) | The number of thread pool threads that currently exist in the , based on | -| :::no-loc text="Working Set"::: (`working-set`) | The amount of physical memory mapped to the process context at a point in time base on | -| :::no-loc text="IL Bytes Jitted"::: (`il-bytes-jitted`) | The total size of ILs that are JIT-compiled, in bytes (available on .NET 5 and later versions) | -| :::no-loc text="Method Jitted Count"::: (`method-jitted-count`) | The number of methods that are JIT-compiled (available on .NET 5 and later versions) | -| :::no-loc text="GC Committed Bytes"::: (`gc-committed-bytes`) | The number of bytes committed by the GC (available on .NET 6 and later versions) | +| Counter | Description | First available in | +|--|--|--| +| :::no-loc text="% Time in GC since last GC"::: (`time-in-gc`) | The percent of time in GC since the last GC | .NET Core 3.1 | +| :::no-loc text="Allocation Rate"::: (`alloc-rate`) | The number of bytes allocated per update interval | .NET Core 3.1 | +| :::no-loc text="CPU Usage"::: (`cpu-usage`) | The percent of the process's CPU usage relative to all of the system CPU resources | .NET Core 3.1 | +| :::no-loc text="Exception Count"::: (`exception-count`) | The number of exceptions that have occurred | .NET Core 3.1 | +| :::no-loc text="GC Heap Size"::: (`gc-heap-size`) | The number of bytes thought to be allocated based on | .NET Core 3.1 | +| :::no-loc text="Gen 0 GC Count"::: (`gen-0-gc-count`) | The number of times GC has occurred for Gen 0 per update interval | .NET Core 3.1 | +| :::no-loc text="Gen 0 Size"::: (`gen-0-size`) | The number of bytes for Gen 0 GC | .NET Core 3.1 | +| :::no-loc text="Gen 1 GC Count"::: (`gen-1-gc-count`) | The number of times GC has occurred for Gen 1 per update interval | .NET Core 3.1 | +| :::no-loc text="Gen 1 Size"::: (`gen-1-size`) | The number of bytes for Gen 1 GC | .NET Core 3.1 | +| :::no-loc text="Gen 2 GC Count"::: (`gen-2-gc-count`) | The number of times GC has occurred for Gen 2 per update interval | .NET Core 3.1 | +| :::no-loc text="Gen 2 Size"::: (`gen-2-size`) | The number of bytes for Gen 2 GC | .NET Core 3.1 | +| :::no-loc text="LOH Size"::: (`loh-size`) | The number of bytes for the large object heap | .NET Core 3.1 | +| :::no-loc text="POH Size"::: (`poh-size`) | The number of bytes for the pinned object heap (available on .NET 5 and later versions) | .NET Core 3.1 | +| :::no-loc text="GC Fragmentation"::: (`gc-fragmentation`) | The GC Heap Fragmentation (available on .NET 5 and later versions) | .NET Core 3.1 | +| :::no-loc text="Monitor Lock Contention Count"::: (`monitor-lock-contention-count`) | The number of times there was contention when trying to take the monitor's lock, based on | .NET Core 3.1 | +| :::no-loc text="Number of Active Timers"::: (`active-timer-count`) | The number of instances that are currently active, based on | .NET Core 3.1 | +| :::no-loc text="Number of Assemblies Loaded"::: (`assembly-count`) | The number of instances loaded into a process at a point in time | .NET Core 3.1 | +| :::no-loc text="ThreadPool Completed Work Item Count"::: (`threadpool-completed-items-count`) | The number of work items that have been processed so far in the | .NET Core 3.1 | +| :::no-loc text="ThreadPool Queue Length"::: (`threadpool-queue-length`) | The number of work items that are currently queued to be processed in the | .NET Core 3.1 | +| :::no-loc text="ThreadPool Thread Count"::: (`threadpool-thread-count`) | The number of thread pool threads that currently exist in the , based on | .NET Core 3.1 | +| :::no-loc text="Working Set"::: (`working-set`) | The amount of physical memory mapped to the process context at a point in time base on | .NET Core 3.1 | +| :::no-loc text="IL Bytes Jitted"::: (`il-bytes-jitted`) | The total size of ILs that are JIT-compiled, in bytes | .NET 5 | +| :::no-loc text="Method Jitted Count"::: (`method-jitted-count`) | The number of methods that are JIT-compiled | .NET 5 | +| :::no-loc text="GC Committed Bytes"::: (`gc-committed-bytes`) | The number of bytes committed by the GC | .NET 6 | ## "Microsoft.AspNetCore.Hosting" counters The following counters are published as part of [ASP.NET Core](/aspnet/core) and are maintained in [`HostingEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/Hosting/Hosting/src/Internal/HostingEventSource.cs). -| Counter | Description | -|--|--| -| :::no-loc text="Current Requests"::: (`current-requests`) | The total number of requests that have started, but not yet stopped | -| :::no-loc text="Failed Requests"::: (`failed-requests`) | The total number of failed requests that have occurred for the life of the app | -| :::no-loc text="Request Rate"::: (`requests-per-second`) | The number of requests that occur per update interval | -| :::no-loc text="Total Requests"::: (`total-requests`) | The total number of requests that have occurred for the life of the app | +| Counter | Description | First available in | +|--|--|--| +| :::no-loc text="Current Requests"::: (`current-requests`) | The total number of requests that have started, but not yet stopped | .NET Core 3.1 | +| :::no-loc text="Failed Requests"::: (`failed-requests`) | The total number of failed requests that have occurred for the life of the app | .NET Core 3.1 | +| :::no-loc text="Request Rate"::: (`requests-per-second`) | The number of requests that occur per update interval | .NET Core 3.1 | +| :::no-loc text="Total Requests"::: (`total-requests`) | The total number of requests that have occurred for the life of the app | .NET Core 3.1 | ## "Microsoft.AspNetCore.Http.Connections" counters The following counters are published as part of [ASP.NET Core SignalR](/aspnet/core/signalr/introduction) and are maintained in [`HttpConnectionsEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/SignalR/common/Http.Connections/src/Internal/HttpConnectionsEventSource.cs). -| Counter | Description | -|--|--| -| :::no-loc text="Average Connection Duration"::: (`connections-duration`) | The average duration of a connection in milliseconds | -| :::no-loc text="Current Connections"::: (`current-connections`) | The number of active connections that have started, but not yet stopped | -| :::no-loc text="Total Connections Started"::: (`connections-started`) | The total number of connections that have started | -| :::no-loc text="Total Connections Stopped"::: (`connections-stopped`) | The total number of connections that have stopped | -| :::no-loc text="Total Connections Timed Out"::: (`connections-timed-out`) | The total number of connections that have timed out | +| Counter | Description | First available in | +|--|--|--| +| :::no-loc text="Average Connection Duration"::: (`connections-duration`) | The average duration of a connection in milliseconds | .NET Core 3.1 | +| :::no-loc text="Current Connections"::: (`current-connections`) | The number of active connections that have started, but not yet stopped | .NET Core 3.1 | +| :::no-loc text="Total Connections Started"::: (`connections-started`) | The total number of connections that have started | .NET Core 3.1 | +| :::no-loc text="Total Connections Stopped"::: (`connections-stopped`) | The total number of connections that have stopped | .NET Core 3.1 | +| :::no-loc text="Total Connections Timed Out"::: (`connections-timed-out`) | The total number of connections that have timed out | .NET Core 3.1 | ## "Microsoft-AspNetCore-Server-Kestrel" counters The following counters are published as part of the [ASP.NET Core Kestrel web server](/aspnet/core/fundamentals/servers/kestrel) and are maintained in [`KestrelEventSource.cs`](https://github.com/dotnet/aspnetcore/blob/main/src/Servers/Kestrel/Core/src/Internal/Infrastructure/KestrelEventSource.cs). -| Counter | Description | -|--|--| -| :::no-loc text="Connection Queue Length"::: (`connection-queue-length`) | The current length of the connection queue | -| :::no-loc text="Connection Rate"::: (`connections-per-second`) | The number of connections per update interval to the web server | -| :::no-loc text="Current Connections"::: (`current-connections`) | The current number of active connections to the web server | -| :::no-loc text="Current TLS Handshakes"::: (`current-tls-handshakes`) | The current number of TLS handshakes | -| :::no-loc text="Current Upgraded Requests (WebSockets)"::: (`current-upgraded-requests`) | The current number of upgraded requests (WebSockets) | -| :::no-loc text="Failed TLS Handshakes"::: (`failed-tls-handshakes`) | The total number of failed TLS handshakes | -| :::no-loc text="Request Queue Length"::: (`request-queue-length`) | The current length of the request queue | -| :::no-loc text="TLS Handshake Rate"::: (`tls-handshakes-per-second`) | The number of TLS handshakes per update interval | -| :::no-loc text="Total Connections"::: (`total-connections`) | The total number of connections to the web server | -| :::no-loc text="Total TLS Handshakes"::: (`total-tls-handshakes`) | The total number of TLS handshakes with the web server | +| Counter | Description | First available in | +|--|--|--| +| :::no-loc text="Connection Queue Length"::: (`connection-queue-length`) | The current length of the connection queue | .NET 5 | +| :::no-loc text="Connection Rate"::: (`connections-per-second`) | The number of connections per update interval to the web server | .NET 5 | +| :::no-loc text="Current Connections"::: (`current-connections`) | The current number of active connections to the web server | .NET 5 | +| :::no-loc text="Current TLS Handshakes"::: (`current-tls-handshakes`) | The current number of TLS handshakes | .NET 5 | +| :::no-loc text="Current Upgraded Requests (WebSockets)"::: (`current-upgraded-requests`) | The current number of upgraded requests (WebSockets) | .NET 5 | +| :::no-loc text="Failed TLS Handshakes"::: (`failed-tls-handshakes`) | The total number of failed TLS handshakes | .NET 5 | +| :::no-loc text="Request Queue Length"::: (`request-queue-length`) | The current length of the request queue | .NET 5 | +| :::no-loc text="TLS Handshake Rate"::: (`tls-handshakes-per-second`) | The number of TLS handshakes per update interval | .NET 5 | +| :::no-loc text="Total Connections"::: (`total-connections`) | The total number of connections to the web server | .NET 5 | +| :::no-loc text="Total TLS Handshakes"::: (`total-tls-handshakes`) | The total number of TLS handshakes with the web server | .NET 5 | ## "System.Net.Http" counters -The following counters are published by the HTTP stack. These counters are available on .NET 5 and later versions only. +The following counters are published by the HTTP stack. -| Counter | Description | -|--|--| -| :::no-loc text="Requests Started"::: (`requests-started`) | The number of requests started since the process started | -| :::no-loc text="Requests Started Rate"::: (`requests-started-rate`) | The number of requests started per update interval | -| :::no-loc text="Requests Failed"::: (`requests-failed`) | The number of failed requests since the process started | -| :::no-loc text="Requests Failed Rate"::: (`requests-failed-rate`) | The number of failed requests per update interval | -| :::no-loc text="Current Requests"::: (`current-requests`) | Current number of active HTTP requests that have started but not yet completed or failed | -| :::no-loc text="Current HTTP 1.1 Connections"::: (`http11-connections-current-total`) | The current number of HTTP 1.1 connections that have started but not yet completed or failed | -| :::no-loc text="Current HTTP 2.0 Connections"::: (`http20-connections-current-total`) | The current number of HTTP 2.0 connections that have started but not yet completed or failed | -| :::no-loc text="HTTP 1.1 Requests Queue Duration"::: (`http11-requests-queue-duration`) | The average duration of the time HTTP 1.1 requests spent in the request queue | -| :::no-loc text="HTTP 2.0 Requests Queue Duration"::: (`http20-requests-queue-duration`) | The average duration of the time HTTP 2.0 requests spent in the request queue | +| Counter | Description | First available in | +|--|--|--| +| :::no-loc text="Requests Started"::: (`requests-started`) | The number of requests started since the process started | .NET 5 | +| :::no-loc text="Requests Started Rate"::: (`requests-started-rate`) | The number of requests started per update interval | .NET 5 | +| :::no-loc text="Requests Failed"::: (`requests-failed`) | The number of failed requests since the process started | .NET 5 | +| :::no-loc text="Requests Failed Rate"::: (`requests-failed-rate`) | The number of failed requests per update interval | .NET 5 | +| :::no-loc text="Current Requests"::: (`current-requests`) | Current number of active HTTP requests that have started but not yet completed or failed | .NET 5 | +| :::no-loc text="Current HTTP 1.1 Connections"::: (`http11-connections-current-total) | The current number of HTTP 1.1 connections that have started but not yet completed or failed | .NET 5 | +| :::no-loc text="Current HTTP 2.0 Connections"::: (`http20-connections-current-total`) | The current number of HTTP 2.0 connections that have started but not yet completed or failed | .NET 5 | +| :::no-loc text="HTTP 1.1 Requests Queue Duration"::: (`http11-requests-queue-duration`) | The average duration of the time HTTP 1.1 requests spent in the request queue | .NET 5 | +| :::no-loc text="HTTP 2.0 Requests Queue Duration"::: (`http20-requests-queue-duration`) | The average duration of the time HTTP 2.0 requests spent in the request queue | .NET 5 | ## "System.Net.NameResolution" counters -The following counters track metrics related to DNS lookups. These counters are available on .NET 5 and later versions only. +The following counters track metrics related to DNS lookups. -| Counter | Description | -|--|--| -| :::no-loc text="DNS Lookups Requested"::: (`dns-lookups-requested`) | The number of DNS lookups requested since the process started | -| :::no-loc text="Average DNS Lookup Duration"::: (`dns-lookups-duration`) | The average time taken for a DNS lookup | +| Counter | Description | First available in | +|--|--|--| +| :::no-loc text="DNS Lookups Requested"::: (`dns-lookups-requested`) | The number of DNS lookups requested since the process started | .NET 5 | +| :::no-loc text="Average DNS Lookup Duration"::: (`dns-lookups-duration`) | The average time taken for a DNS lookup | .NET 5 | ## "System.Net.Security" counters -The following counters track metrics related to the Transport Layer Security protocol. These counters are available on .NET 5 and later versions only. - -| Counter | Description | -|--|--| -| :::no-loc text="TLS handshakes completed"::: (`tls-handshake-rate`) | The number of TLS handshakes completed per update interval | -| :::no-loc text="Total TLS handshakes completed"::: (`total-tls-handshakes`) | The total number of TLS handshakes completed since the process started | -| :::no-loc text="Current TLS handshakes"::: (`current-tls-handshakes`) | The current number of TLS handshakes that have started but not yet completed | -| :::no-loc text="Total TLS handshakes failed"::: (`failed-tls-handshakes`) | The total number of failed TLS handshakes since the process started | -| :::no-loc text="All TLS Sessions Active"::: (`all-tls-sessions-open`) | The number of active TLS sessions of any version | -| :::no-loc text="TLS 1.0 Sessions Active"::: (`tls10-sessions-open`) | The number of active TLS 1.0 sessions | -| :::no-loc text="TLS 1.1 Sessions Active"::: (`tls11-sessions-open`) | The number of active TLS 1.1 sessions | -| :::no-loc text="TLS 1.2 Sessions Active"::: (`tls12-sessions-open`) | The number of active TLS 1.2 sessions | -| :::no-loc text="TLS 1.3 Sessions Active"::: (`tls13-sessions-open`) | The number of active TLS 1.3 sessions | -| :::no-loc text="TLS Handshake Duration"::: (`all-tls-handshake-duration`) | The average duration of all TLS handshakes | -| :::no-loc text="TLS 1.0 Handshake Duration"::: (`tls10-handshake-duration`) | The average duration of TLS 1.0 handshakes | -| :::no-loc text="TLS 1.1 Handshake Duration"::: (`tls11-handshake-duration`) | The average duration of TLS 1.1 handshakes | -| :::no-loc text="TLS 1.2 Handshake Duration"::: (`tls12-handshake-duration`) | The average duration of TLS 1.2 handshakes | -| :::no-loc text="TLS 1.3 Handshake Duration"::: (`tls13-handshake-duration`) | The average duration of TLS 1.3 handshakes | - -## "System.Net.Sockets" counters (available on .NET 5 and later versions) +The following counters track metrics related to the Transport Layer Security protocol. + +| Counter | Description | First available in | +|--|--|--| +| :::no-loc text="TLS handshakes completed"::: (`tls-handshake-rate`) | The number of TLS handshakes completed per update interval | .NET 5 | +| :::no-loc text="Total TLS handshakes completed"::: (`total-tls-handshakes`) | The total number of TLS handshakes completed since the process started | .NET 5 | +| :::no-loc text="Current TLS handshakes"::: (`current-tls-handshakes`) | The current number of TLS handshakes that have started but not yet completed | .NET 5 | +| :::no-loc text="Total TLS handshakes failed"::: (`failed-tls-handshakes`) | The total number of failed TLS handshakes since the process started | .NET 5 | +| :::no-loc text="All TLS Sessions Active"::: (`all-tls-sessions-open`) | The number of active TLS sessions of any version | .NET 5 | +| :::no-loc text="TLS 1.0 Sessions Active"::: (`tls10-sessions-open`) | The number of active TLS 1.0 sessions | .NET 5 | +| :::no-loc text="TLS 1.1 Sessions Active"::: (`tls11-sessions-open`) | The number of active TLS 1.1 sessions | .NET 5 | +| :::no-loc text="TLS 1.2 Sessions Active"::: (`tls12-sessions-open`) | The number of active TLS 1.2 sessions | .NET 5 | +| :::no-loc text="TLS 1.3 Sessions Active"::: (`tls13-sessions-open`) | The number of active TLS 1.3 sessions | .NET 5 | +| :::no-loc text="TLS Handshake Duration"::: (`all-tls-handshake-duration`) | The average duration of all TLS handshakes | .NET 5 | +| :::no-loc text="TLS 1.0 Handshake Duration"::: (`tls10-handshake-duration`) | The average duration of TLS 1.0 handshakes | .NET 5 | +| :::no-loc text="TLS 1.1 Handshake Duration"::: (`tls11-handshake-duration`) | The average duration of TLS 1.1 handshakes | .NET 5 | +| :::no-loc text="TLS 1.2 Handshake Duration"::: (`tls12-handshake-duration`) | The average duration of TLS 1.2 handshakes | .NET 5 | +| :::no-loc text="TLS 1.3 Handshake Duration"::: (`tls13-handshake-duration`) | The average duration of TLS 1.3 handshakes | .NET 5 | + +## "System.Net.Sockets" counters The following counters track metrics related to . -| Counter | Description | -|--|--| -| :::no-loc text="Outgoing Connections Established"::: (`outgoing-connections-established`) | The total number of outgoing connections established since the process started | -| :::no-loc text="Incoming Connections Established"::: (`incoming-connections-established`) | The total number of incoming connections established since the process started | -| :::no-loc text="Bytes Received"::: (`bytes-received`) | The total number of bytes received since the process started | -| :::no-loc text="Bytes Sent"::: (`bytes-sent`) | The total number of bytes sent since the process started | -| :::no-loc text="Datagrams Received"::: (`datagrams-received`) | The total number of datagrams received since the process started | -| :::no-loc text="Datagrams Sent"::: (`datagrams-sent`) | The total number of datagrams sent since the process started | +| Counter | Description | First available in | +|--|--|--| +| :::no-loc text="Outgoing Connections Established"::: (`outgoing-connections-established`) | The total number of outgoing connections established since the process started | .NET 5 | +| :::no-loc text="Incoming Connections Established"::: (`incoming-connections-established`) | The total number of incoming connections established since the process started | .NET 5 | +| :::no-loc text="Bytes Received"::: (`bytes-received`) | The total number of bytes received since the process started | .NET 5 | +| :::no-loc text="Bytes Sent"::: (`bytes-sent`) | The total number of bytes sent since the process started | .NET 5 | +| :::no-loc text="Datagrams Received"::: (`datagrams-received`) | The total number of datagrams received since the process started | .NET 5 | +| :::no-loc text="Datagrams Sent"::: (`datagrams-sent`) | The total number of datagrams sent since the process started | .NET 5 | From d242f20053d1db94ace0755e8fb6adc7ef51fc4e Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Fri, 2 Jul 2021 07:59:19 -0700 Subject: [PATCH 05/27] Add info about the default option matching (#24960) * Update regular-expression-options.md * Update regular-expression-options.md --- docs/standard/base-types/regular-expression-options.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/standard/base-types/regular-expression-options.md b/docs/standard/base-types/regular-expression-options.md index bce5f380d350d..6c40941c0d9d9 100644 --- a/docs/standard/base-types/regular-expression-options.md +++ b/docs/standard/base-types/regular-expression-options.md @@ -113,7 +113,7 @@ The option, or the `s` inline option, causes the regular expression engine to treat the input string as if it consists of a single line. It does this by changing the behavior of the period (`.`) language element so that it matches every character, instead of matching every character except for the newline character `\n` or \u000A. +The option, or the `s` inline option, causes the regular expression engine to treat the input string as if it consists of a single line. It does this by changing the behavior of the period (`.`) language element so that it matches every character, instead of matching every character except for the newline character `\n` or `\u000A`. + +The `$` language element will match the end of the string or a trailing newline character `\n`. The following example illustrates how the behavior of the `.` language element changes when you use the option. The regular expression `^.+` starts at the beginning of the string and matches every character. By default, the match ends at the end of the first line; the regular expression pattern matches the carriage return character, `\r` or \u000D, but it does not match `\n`. Because the option interprets the entire input string as a single line, it matches every character in the input string, including `\n`. From e43936c7226761604181afc4c27aa536842c8f2e Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Fri, 2 Jul 2021 11:04:20 -0400 Subject: [PATCH 06/27] Clarify description of object initializers (#24968) * Clarify description of object initializers The statement "without calling the constructor" could be easily misinterpreted as claiming that no constructor is executed. That is incorrect. * Remove missing anchors Fixes build warnings found in #24968 --- docs/core/additional-tools/self-signed-certificates-guide.md | 4 ++-- docs/csharp/fundamentals/object-oriented/index.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/additional-tools/self-signed-certificates-guide.md b/docs/core/additional-tools/self-signed-certificates-guide.md index ea7392e48b8ed..4a28842d38573 100644 --- a/docs/core/additional-tools/self-signed-certificates-guide.md +++ b/docs/core/additional-tools/self-signed-certificates-guide.md @@ -41,7 +41,7 @@ Navigate to the repository locally and open up the workspace in an editor. > [!NOTE] > If you're looking to use dotnet publish parameters to *trim* the deployment, you should make sure that the appropriate dependencies are included for supporting SSL certificates. -Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trim-self-contained.md#support-for-ssl-certificates) when using trimming for self-contained deployments. +Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trim-self-contained.md) when using trimming for self-contained deployments. Make sure the `aspnetapp.csproj` includes the appropriate target framework: @@ -143,7 +143,7 @@ Make sure the `aspnetapp.csproj` includes the appropriate target framework: > [!NOTE] > If you want to use `dotnet publish` parameters to *trim* the deployment, make sure that the appropriate dependencies are included for supporting SSL certificates. -Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trim-self-contained.md#support-for-ssl-certificates) when using trimming for self-contained deployments. +Update the [dotnet-docker\samples\aspnetapp\aspnetapp.csproj](https://github.com/dotnet/dotnet-docker/blob/main/samples/aspnetapp/aspnetapp/aspnetapp.csproj) to ensure that the appropriate assemblies are included in the container. For reference, check how to update the .csproj file to [support ssl certificates](../deploying/trim-self-contained.md) when using trimming for self-contained deployments. Make sure you're pointing to the sample app. diff --git a/docs/csharp/fundamentals/object-oriented/index.md b/docs/csharp/fundamentals/object-oriented/index.md index ece85b0b6b87c..bd4cf7e2dc0e6 100644 --- a/docs/csharp/fundamentals/object-oriented/index.md +++ b/docs/csharp/fundamentals/object-oriented/index.md @@ -76,7 +76,7 @@ You can define part of a class, struct, or method in one code file and another p ## Object Initializers -You can instantiate and initialize class or struct objects, and collections of objects, without explicitly calling their constructor with an ending `()` after the type. +You can instantiate and initialize class or struct objects, and collections of objects, by assigning values to its properties. ## Anonymous Types From 970adc3d8e51799408597f8cc301348ff9c72892 Mon Sep 17 00:00:00 2001 From: Der-Kraken <41434285+Der-Kraken@users.noreply.github.com> Date: Fri, 2 Jul 2021 18:08:14 +0200 Subject: [PATCH 07/27] Update dotnet-new.md (#24965) The example showed how to create a VB-project. But the headline descriped how to create a netstandard project. --- docs/core/tools/dotnet-new.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/tools/dotnet-new.md b/docs/core/tools/dotnet-new.md index 893669c6d1537..6ee6d8ce1830b 100644 --- a/docs/core/tools/dotnet-new.md +++ b/docs/core/tools/dotnet-new.md @@ -133,10 +133,10 @@ Each template may have additional options defined. For more information, see [.N dotnet new console --language "F#" ``` -- Create a .NET Standard class library project in the specified directory: +- Create a .NET Standard 2.0 class library project in the specified directory: ```dotnetcli - dotnet new classlib --language VB -o MyLibrary + dotnet new classlib --framework "netstandard2.0" -o MyLibrary ``` - Create a new ASP.NET Core C# MVC project in the current directory with no authentication: From 753ed6b5cd3057fce3a9674ff19c400c639d52aa Mon Sep 17 00:00:00 2001 From: Stephen Bonikowsky Date: Fri, 2 Jul 2021 13:00:18 -0700 Subject: [PATCH 08/27] Migration docs revamp. (#24630) * Update with the minimal changes needed to align existing content to the new TOC. * Adding the new page 'tooling-requirements.md' and adding initial content to resolve #24568 * Created additional pages needed for Phase 1 modifying the TOC as needed. * Created additional pages needed for Phase 1 modifying the TOC as needed. * Update docs/core/porting/premigration-needed-changes.md * Update docs/core/porting/premigration-needed-changes.md * Add breaking change page. * Add breaking change page. * Update tooling requirements page based on feedback. * Update breaking changes page. * Update breaking changes page. * Rename and move thepage about sdk, msbuild and vs versioning. * Rename and move thepage about sdk, msbuild and vs versioning. * Latest round of feedback updates. * Latest round of feedback updates. * Update docs/core/porting/breaking-changes.md Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> * Update breaking-changes.md * Update versioning....md * Upgrade porting-approaches.md * Upgrade premigration-needed-changes.md * Upgrade project-structure.md * Upgrade unsupported-apis.md * TOC naming changes * Update docs/core/porting/project-structure.md Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> * Update docs/core/porting/project-structure.md Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> * Update porting-approaches.md * Update premigration-needed-changes.md Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> Co-authored-by: Andy De George (adegeo) --- docs/core/porting/breaking-changes.md | 47 +++++++++ docs/core/porting/porting-approaches.md | 98 +++++++++++++++++++ .../porting/premigration-needed-changes.md | 42 ++++++++ docs/core/porting/project-structure.md | 61 ++++++------ docs/core/porting/third-party-deps.md | 7 +- docs/core/porting/unsupported-apis.md | 30 ++++++ .../core/porting/versioning-sdk-msbuild-vs.md | 47 +++++++++ docs/fundamentals/toc.yml | 82 ++++++++++------ 8 files changed, 348 insertions(+), 66 deletions(-) create mode 100644 docs/core/porting/breaking-changes.md create mode 100644 docs/core/porting/porting-approaches.md create mode 100644 docs/core/porting/premigration-needed-changes.md create mode 100644 docs/core/porting/unsupported-apis.md create mode 100644 docs/core/porting/versioning-sdk-msbuild-vs.md diff --git a/docs/core/porting/breaking-changes.md b/docs/core/porting/breaking-changes.md new file mode 100644 index 0000000000000..91aec9f372e7a --- /dev/null +++ b/docs/core/porting/breaking-changes.md @@ -0,0 +1,47 @@ +--- +title: Breaking changes can affect porting your app +description: Breaking changes can occur when porting your code from .NET framework to .NET and between versions of .NET. This article describes categories of breaking changes, ways a change can affect compatibility and how to find breaking changes. +author: StephenBonikowsky +ms.author: stebon +ms.date: 06/14/2021 +--- +# Breaking changes may occur when porting code + +Changes that affect compatibility, otherwise known as breaking changes, will occur between versions of .NET. Changes are impactful when porting from .NET Framework to .NET because of certain technologies not being available. Also, you can come across breaking changes simply because .NET is a cross-platform technology and .NET Framework isn't. + +Microsoft strives to maintain a high level of compatibility between .NET versions, so while breaking changes do occur, they're carefully considered. + +Before upgrading major versions, check the breaking changes documentation for changes that might affect you. + +## Categories of breaking changes + +There are several types of breaking changes... + +- modifications to the public contract +- behavioral changes +- Platform support +- Internal implementation changes +- Code changes + +For more information about what is allowed or disallowed, see [Changes that affect compatibility](../compatibility/index.md) + +## Types of compatibility + +Compatibility refers to the ability to compile or run code on a .NET implementation other than the one with which the code was originally developed. + +There are six different ways a change can affect compatibility... + +- Behavioral changes +- Binary compatibility +- Source compatibility +- Design-time compatibility +- Backwards compatibility +- Forward compatibility + +For more information, see [How code changes can affect compatibility](../compatibility/categories.md) + +## Find breaking changes + +Changes that affect compatibility are documented and should be reviewed before porting from .NET Framework to .NET or when upgrading to a newer version of .NET. + +For more information, see [Breaking changes reference overview](../compatibility/breaking-changes.md) diff --git a/docs/core/porting/porting-approaches.md b/docs/core/porting/porting-approaches.md new file mode 100644 index 0000000000000..34e4c32da9f9c --- /dev/null +++ b/docs/core/porting/porting-approaches.md @@ -0,0 +1,98 @@ +--- +title: Porting approaches +description: Create a porting plan that best reflects your project and context. +author: StephenBonikowsky +ms.author: stebon +ms.date: 06/10/2021 +--- +# Create a porting plan + +Before you jump straight into the code, take the time to go through the recommended pre-migration steps. This article gives you insight into the kinds of issues you may come across, and helps you decide on an approach that makes the most sense. + +## Port your code + +Make sure that you follow the [prerequisites to porting code](premigration-needed-changes.md) before you continue any further. Be ready to decide on the best approach for you and begin porting code. + +### Deal primarily with the compiler + +This approach works well for small projects or projects that don't use many .NET Framework APIs. The approach is simple: + +01. Optionally, run **ApiPort** on your project. If you run **ApiPort**, gain knowledge from the report on issues you'll need to address. +01. Copy all of your code over into a new .NET project. +01. While referring to the portability report (if generated), solve compiler errors until the project fully compiles. + +Although it's unstructured, this code-focused approach often resolves issues quickly. A project that contains only data models might be an ideal candidate for this approach. + +### Stay on the .NET Framework until portability issues are resolved + +This approach might be the best if you prefer to have code that compiles during the entire process. The approach is as follows: + +01. Run **ApiPort** on a project. +01. Address issues by using different APIs that are portable. +01. Take note of any areas where you're prevented from using a direct alternative. +01. Repeat the prior steps for all projects you're porting until you're confident each is ready to be copied over into a new .NET project. +01. Copy the code into a new .NET project. +01. Work out any issues where you noted that a direct alternative doesn't exist. + +This careful approach is more structured than simply working out compiler errors, but it's still relatively code-focused and has the benefit of always having code that compiles. The way you resolve certain issues that couldn't be addressed by just using another API varies greatly. You may find that you need to develop a more comprehensive plan for certain projects, which is covered in the next approach. + +### Develop a comprehensive plan of attack + +This approach might be best for larger and more complex projects, where restructuring code or completely rewriting certain areas of code might be necessary to support .NET. The approach is as follows: + +01. Run **ApiPort** on a project. +01. Understand where each non-portable type is used and how that affects overall portability. + + - Understand the nature of those types. Are they small in number but used frequently? Are they large in number but used infrequently? Is their use concentrated, or is it spread throughout your code? + - Is it easy to isolate code that isn't portable so that you can deal with it more effectively? + - Do you need to refactor your code? + - For those types that aren't portable, are there alternative APIs that accomplish the same task? For example, if you're using the class, use the class instead. + - Are there different portable APIs available to accomplish a task, even if it's not a drop-in replacement? For example, if you're using to parse XML but don't require XML schema discovery, you could use APIs and implement parsing yourself instead of relying on an API. + +01. If you have assemblies that are difficult to port, is it worth leaving them on .NET Framework for now? Here are some things to consider: + + - You may have some functionality in your library that's incompatible with .NET because it relies too heavily on .NET Framework or Windows-specific functionality. Is it worth leaving that functionality behind for now and releasing a temporary .NET version of your library with fewer features until resources are available to port the features? + - Would a refactor help? + +01. Is it reasonable to write your own implementation of an unavailable .NET Framework API? + + You could consider copying, modifying, and using code from the [.NET Framework reference source](https://github.com/Microsoft/referencesource). The reference source code is licensed under the [MIT License](https://github.com/Microsoft/referencesource/blob/master/LICENSE.txt), so you have significant freedom to use the source as a basis for your own code. Just be sure to properly attribute Microsoft in your code. + +01. Repeat this process as needed for different projects. + +The analysis phase could take some time depending on the size of your codebase. Spending time in this phase to thoroughly understand the scope of changes needed and to develop a plan usually saves you time in the end, particularly if you have a complex codebase. + +Your plan could involve making significant changes to your codebase while still targeting .NET Framework 4.7.2. This is a more structured version of the previous approach. How you go about executing your plan is dependent on your codebase. + +### Mixed approach + +It's likely that you'll mix the above approaches on a per-project basis. Do what makes the most sense to you and for your codebase. + +## Port your tests + +The best way to make sure everything works when you've ported your code is to test your code as you port it to .NET. To do this, you'll need to use a testing framework that builds and runs tests for .NET. Currently, you have three options: + +- [xUnit](https://xunit.net/) + - [Getting Started](https://xunit.net/docs/getting-started/netcore/cmdline) + - [Tool to convert an MSTest project to xUnit](https://github.com/dotnet/codeformatter/tree/main/src/XUnitConverter) +- [NUnit](https://nunit.org/) + - [Getting Started](https://github.com/nunit/docs/wiki/Installation) + - [Blog post about migrating from MSTest to NUnit](https://www.florian-rappl.de/News/Page/275/convert-mstest-to-nunit) +- [MSTest](/visualstudio/test/unit-test-basics) + +## Recommended approach + +Ultimately, the porting effort depends heavily on how your .NET Framework code is structured. A good way to port your code is to begin with the *base* of your library, which is the foundational components of your code. This might be data models or some other foundational classes and methods that everything else uses directly or indirectly. + +01. Port the test project that tests the layer of your library that you're currently porting. +01. Copy over the base of your library into a new .NET project and select the version of .NET Standard you wish to support. +01. Make any changes needed to get the code to compile. Much of this may require adding NuGet package dependencies to your *csproj* file. +01. Run the tests and make any needed adjustments. +01. Pick the next layer of code to port over and repeat the prior steps. + +If you start with the base of your library and move outward from the base and test each layer as needed, porting is a systematic process where problems are isolated to one layer of code at a time. + +## Next steps + +- [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md) +- [Organize your project to support both .NET Framework and .NET Core](project-structure.md) diff --git a/docs/core/porting/premigration-needed-changes.md b/docs/core/porting/premigration-needed-changes.md new file mode 100644 index 0000000000000..82a9457225d15 --- /dev/null +++ b/docs/core/porting/premigration-needed-changes.md @@ -0,0 +1,42 @@ +--- +title: Prerequisites to port from .NET Framework +description: Before porting your code from .NET Framework to .NET, you must use the correct developer environment and update your project files as required. +author: StephenBonikowsky +ms.author: stebon +ms.date: 06/10/2021 +--- +# Prerequisites to porting code + +Make the needed changes to build and run a .NET application before beginning the work to port your code. These changes can be done while still building and running a .NET Framework application. + +## Upgrade to required tooling + +Upgrade to a version of MSBuild/Visual Studio that supports the version of .NET you will be targeting. See [Versioning relationship between the .NET SDK, MSBuild and VS](versioning-sdk-msbuild-vs.md) for more info. + +## Update .NET Framework target version + +We recommended that you target your .NET Framework app to version 4.7.2 or higher. This ensures the availability of the latest API alternatives for cases where .NET Standard doesn't support existing APIs. + +For each of the projects you wish to port, do the following in Visual Studio: + +01. Right-click on the project and select **Properties**. +01. In the **Target Framework** dropdown, select **.NET Framework 4.7.2**. +01. Recompile the project. + +Because your projects now target .NET Framework 4.7.2, use that version of the .NET Framework as your base for porting code. + +## Change to PackageReference format + +Convert all references to the [PackageReference](/nuget/consume-packages/package-references-in-project-files) format. + +## Convert to SDK style project format + +Convert your projects to the [SDK-style format](../project-sdk/overview.md). + +## Update dependencies + +Update dependencies to their latest version available, and to .NET Standard version where possible. + +## Next steps + +- [Create a porting plan](porting-approaches.md) diff --git a/docs/core/porting/project-structure.md b/docs/core/porting/project-structure.md index 9a3e9574119fe..20dd782ff3c51 100644 --- a/docs/core/porting/project-structure.md +++ b/docs/core/porting/project-structure.md @@ -1,62 +1,61 @@ --- -title: Organize projects for .NET Framework and .NET Core -description: Help for project owners who want to compile their solution against .NET Framework and .NET Core side-by-side. +title: Organize projects for .NET Framework and .NET +description: Help for project owners who want to compile their solution against .NET Framework and .NET side by side. author: conniey -ms.date: 12/07/2018 +ms.date: 07/02/2021 --- -# Organize your project to support both .NET Framework and .NET Core +# Organize your project to support both .NET Framework and .NET -You can create a solution that compiles for both .NET Framework and .NET Core side-by-side. This article covers several project-organization options to help you achieve this goal. Here are some typical scenarios to consider when you're deciding how to set up your project layout with .NET Core. The list may not cover everything you want; prioritize based on your project's needs. +You can create a solution that compiles for both .NET Framework and .NET side by side. This article covers several project-organization options to help you achieve this goal. Here are some typical scenarios to consider when you're deciding how to set up your project layout with .NET. The list may not cover everything you want. -- [**Combine existing projects and .NET Core projects into single projects**](#replace-existing-projects-with-a-multi-targeted-net-core-project) +- [Combine existing projects and .NET projects into a single project](#replace-existing-projects-with-a-multi-targeted-net-project) + + **Benefits**: - *What this is good for:* - Simplifies your build process by compiling a single project rather than multiple projects that each target a different .NET Framework version or platform. - - Simplifies source file management for multi-targeted projects because you must manage a single project file. When adding or removing source files, the alternatives require you to manually sync these with your other projects. + - Simplifies source file management for multi-targeted projects because you must manage a single project file. When adding or removing source files, the alternatives require you to manually sync these files with your other projects. - Easily generate a NuGet package for consumption. - - Allows you to write code for a specific .NET Framework version in your libraries through the use of compiler directives. + - Allows you to write code for a specific .NET Framework version by using compiler directives. - *Unsupported scenarios:* - - Requires developers to use Visual Studio 2017 or a later version to open existing projects. To support older versions of Visual Studio, [keeping your project files in different folders](#support-vs) is a better option. + **Drawback**: -- [**Keep existing projects and new .NET Core projects separate**](#keep-existing-projects-and-create-a-net-core-project) + - Requires developers to use Visual Studio 2019 or a later version to open existing projects. To support older versions of Visual Studio, [keeping your project files in different folders](#support-vs) is a better option. - *What this is good for:* - - Supports development on existing projects for developers and contributors who may not have Visual Studio 2017 or a later version. - - Decreases the possibility of creating new bugs in existing projects because no code churn is required in those projects. +- [Keep all projects separate](#keep-existing-projects-and-create-a-net-project) -## Example + **Benefits**: -Consider the repository below: + - Supports development on existing projects for developers and contributors who may not have Visual Studio 2019 or a later version. + - Lowers the possibility of creating new bugs in existing projects because no code churn is required in those projects. -![Existing project](./media/project-structure/existing-project-structure.png) +Consider [this example GitHub repository](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library/). The figure below shows how this repository is laid out: -[**Source Code**](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library/) +:::image type="content" source="media/project-structure/existing-project-structure.png" alt-text="Existing project structure diagram"::: -The following describes several ways to add support for .NET Core for this repository depending on the constraints and complexity of the existing projects. +The following sections describe several ways to add support for .NET based on the example repository. -## Replace existing projects with a multi-targeted .NET Core project +## Replace existing projects with a multi-targeted .NET project -Reorganize the repository so that any existing *\*.csproj* files are removed and a single *\*.csproj* file is created that targets multiple frameworks. This is a great option, because a single project is able to compile for different frameworks. It also has the power to handle different compilation options and dependencies per targeted framework. +Reorganize the repository so that any existing *\*.csproj* files are removed and a single *\*.csproj* file is created that targets multiple frameworks. This is a great option, because a single project can compile for different frameworks. It also has the power to handle different compilation options and dependencies per targeted framework. -![Create a csproj that targets multiple frameworks](./media/project-structure/multi-targeted-project.png) +:::image type="content" source="media/project-structure/multi-targeted-project.png" alt-text="project that targets multiple frameworks diagram"::: -[**Source Code**](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj/) +For example code, see [GitHub](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj/). Changes to note are: -- Replacement of *packages.config* and *\*.csproj* with a new [.NET Core *\*.csproj*](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj/src/Car/Car.csproj). NuGet packages are specified with ` ItemGroup`. +- Replacement of *packages.config* and *\*.csproj* with a new [.NET *\*.csproj*](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj/src/Car/Car.csproj). NuGet packages are specified with ` ItemGroup`. -## Keep existing projects and create a .NET Core project +## Keep existing projects and create a .NET project -If there are existing projects that target older frameworks, you may want to leave these projects untouched and use a .NET Core project to target future frameworks. +If there are existing projects that target older frameworks, you may want to leave these projects untouched and use a .NET project to target future frameworks. -![.NET Core project with existing project in different folder](./media/project-structure/separate-projects-same-source.png) +:::image type="content" source="media/project-structure/separate-projects-same-source.png" alt-text=".NET project with existing projects in a different folder diagram"::: -[**Source Code**](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj-keep-existing/) +For example code, see [GitHub](https://github.com/dotnet/samples/tree/main/framework/libraries/migrate-library-csproj-keep-existing/). -The .NET Core and existing projects are kept in separate folders. Keeping projects in separate folders avoids forcing you to have Visual Studio 2017 or later versions. You can create a separate solution that only opens the old projects. +The .NET and existing projects are kept in separate folders. Keeping projects in separate folders avoids forcing you to have Visual Studio 2019 or later versions. You can create a separate solution that only opens the old projects. ## See also -- [.NET Core porting documentation](index.md) +- [.NET porting documentation](index.md) diff --git a/docs/core/porting/third-party-deps.md b/docs/core/porting/third-party-deps.md index 8ff65bee1ccff..1e8fad06f9f98 100644 --- a/docs/core/porting/third-party-deps.md +++ b/docs/core/porting/third-party-deps.md @@ -1,12 +1,13 @@ --- title: Analyze dependencies to port code description: Learn how to analyze external dependencies to port your project from .NET Framework to .NET. -author: cartermp -ms.date: 03/04/2021 +author: StephenBonikowsky +ms.author: stebon +ms.date: 06/14/2021 --- # Analyze your dependencies to port code from .NET Framework to .NET -To port your code to .NET or .NET Standard, you must understand your dependencies. External dependencies are the NuGet packages or `.dll` files you reference in your project, but that you don't build yourself. +To identify the unsupported third-party dependencies in your project, you must first understand your dependencies. External dependencies are the NuGet packages or `.dll` files you reference in your project, but that you don't build yourself. Porting your code to .NET Standard 2.0 or below ensures that it can be used with both .NET Framework and .NET. However, if you don't need to use the library with .NET Framework, consider targeting the latest version of .NET. diff --git a/docs/core/porting/unsupported-apis.md b/docs/core/porting/unsupported-apis.md new file mode 100644 index 0000000000000..86e55f6704209 --- /dev/null +++ b/docs/core/porting/unsupported-apis.md @@ -0,0 +1,30 @@ +--- +title: Discover unsupported APIs in your app +description: Learn about how to find unsupported APIs your app might be using, and what to do about them. +author: StephenBonikowsky +ms.author: stebon +ms.date: 06/10/2021 +--- +# Find unsupported APIs in your code + +APIs in your .NET Framework code may not be supported in .NET for many reasons. These reasons range from the simple to fix, such as a namespace change, to the more challenging to fix, such as an entire technology not being supported. The first step is to determine which of your APIs are no longer supported and then identify the proper fix. + +## .NET Portability Analyzer + +The .NET Portability Analyzer is a tool that analyzes assemblies and provides a detailed report on .NET APIs that are missing for the applications or libraries to be portable on your specified targeted .NET platforms. + +To use the .NET Portability Analyzer in Visual Studio, install the [extension from the marketplace](https://marketplace.visualstudio.com/items?itemName=ConnieYau.NETPortabilityAnalyzer). + +For more information, see [The .NET Portability Analyzer](../../standard/analyzers/portability-analyzer.md). + +## Upgrade assistant + +The [.NET Upgrade Assistant](upgrade-assistant-overview.md) is a command-line tool that can be run on different kinds of .NET Framework apps. It's designed to assist with upgrading .NET Framework apps to .NET 5. After running the tool, in most cases, the app will **require more effort to complete the migration**. The tool includes the installation of analyzers that can assist with completing the migration. This tool works on the following types of .NET Framework applications: + +- Windows Forms +- WPF +- ASP.NET MVC +- Console +- Class libraries + +This tool uses the **.NET Portability Analyzer** among other tools, and guides the migration process. For more information about the tool, see [Overview of the .NET Upgrade Assistant](upgrade-assistant-overview.md). diff --git a/docs/core/porting/versioning-sdk-msbuild-vs.md b/docs/core/porting/versioning-sdk-msbuild-vs.md new file mode 100644 index 0000000000000..634ae99df9445 --- /dev/null +++ b/docs/core/porting/versioning-sdk-msbuild-vs.md @@ -0,0 +1,47 @@ +--- +title: .NET SDK, MSBuild, and Visual Studio versioning +description: Learn about the versioning relationship between the .NET SDK and MSBuild/VS. +author: StephenBonikowsky +ms.author: stebon +ms.date: 06/10/2021 +--- +# Overview of .NET, MSBuild, and Visual Studio versioning + +Understanding the versioning of the SDK and how it relates to Visual Studio and MSBuild can frequently be confusing. MSBuild versions with VS but is also included in the SDK. The SDK has a minimum version of MSBuild that it works with and it won't load in a VS that is older than it supports. + +## Versioning + +The first part of the SDK matches the .NET version that it includes, runs on, and targets by default. The feature band starts at 1 and increases for each quarterly VS minor release. The patch version increments with each month's servicing updates. + +For example, 5.0.203 ships with .NET 5.0, is the second minor VS release since 5.0.100 first came out, and is the third patch since 5.0.200 released. + +## Lifecycle + +The support timeframe for the SDK typically matches the VS it's included in. + +| SDK Version | MSBuild/VS version | Minimum required MSBuild/VS Version | Ship date | Lifecycle | +|------------------|--------------------|-------------------------------------|--------------|-----------| +| 2.1.5xx | 15.9 | 15.3 | Nov '18 | Aug '21* | +| 2.1.8xx | 16.2 (No VS) | 16.0 | July '19 | Aug '21 | +| 3.1.1xx | 16.4 | 16.3 | Dec '19 | Dec '22 | +| 3.1.4xx | 16.7 | 16.7 | Aug '20 | Dec '22 | +| 5.0.1xx | 16.8 | 16.8 | November '20 | Mar '21 | +| 5.0.2xx | 16.9 | 16.8 | March '21 | Aug '22 | +| 5.0.3xx | 16.10 | 16.8 | May '21 | Aug '21 | +| 5.0.4xx | 16.11 | 16.8 | Aug '21 | Feb '22* | +| 6.0.100-preview4 | 16.10 (No VS) | 16.10-preview3 | May '21 | N/A | +| 6.0.100-preview5 | 17.0-preview 1 | 16.10 | June '21 | N/A | +| 6.0.100 | 17.0 | 16.10** | Nov. '21 | | + +> \* MSbuild/VS supported for longer +> +> \*\* You shouldn't have to upgrade to 17.0 on the day .NET 6 releases. This is the current version and will likely be 16.11 at release. + +Expect breaking changes that require a new MSBuild and VS version at least once a year, for each major SDK release. There shouldn't be breaking changes in SDK feature (patch) updates. + +## Reference + +- [Overview of how .NET is versioned](../versions/index.md) +- [.NET and .NET Core official support policy](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) +- [Microsoft .NET and .NET Core](/lifecycle/products/microsoft-net-and-net-core) +- [.NET Downloads (Windows, Linux, and macOS)](https://dotnet.microsoft.com/download/dotnet) diff --git a/docs/fundamentals/toc.yml b/docs/fundamentals/toc.yml index 917208605f981..105eb70d60eee 100644 --- a/docs/fundamentals/toc.yml +++ b/docs/fundamentals/toc.yml @@ -2478,36 +2478,54 @@ items: items: - name: Overview href: ../core/porting/index.md - - name: .NET Upgrade Assistant tool + - name: General Information items: - - name: Overview - href: ../core/porting/upgrade-assistant-overview.md - - name: Telemetry - href: ../core/porting/upgrade-assistant-telemetry.md - - name: ASP.NET Core - href: ../core/porting/upgrade-assistant-aspnetmvc.md - - name: Windows Presentation Foundation - href: ../core/porting/upgrade-assistant-wpf-framework.md - - name: Windows Forms - href: ../core/porting/upgrade-assistant-winforms-framework.md - - name: Breaking changes - displayName: app compatibility - href: ../core/compatibility/ - - name: Analyze third-party dependencies - href: ../core/porting/third-party-deps.md - - name: Port libraries - href: ../core/porting/libraries.md - - name: Organize projects for .NET - href: ../core/porting/project-structure.md - - name: Unavailable technologies - href: ../core/porting/net-framework-tech-unavailable.md?toc=/dotnet/fundamentals/toc.json&bc=/dotnet/breadcrumb/toc.json - - name: Use the Windows Compatibility Pack - href: ../core/porting/windows-compat-pack.md - - name: Port Windows Forms projects - href: /dotnet/desktop/winforms/migration/?view=netdesktop-5.0 - - name: Port WPF projects - href: /dotnet/desktop/wpf/migration/convert-project-from-net-framework?view=netdesktop-5.0 - - name: Port C++/CLI projects - href: ../core/porting/cpp-cli.md - - name: Choose between .NET 5 and .NET Framework for server apps - href: ../standard/choosing-core-framework-server.md + - name: About .NET + items: + - name: Versioning info for .NET SDK, MSBuild, and Visual Studio + href: ../core/porting/versioning-sdk-msbuild-vs.md + - name: Choose between .NET 5 and .NET Framework for server apps + href: ../standard/choosing-core-framework-server.md + - name: .NET Upgrade Assistant tool + items: + - name: Overview + href: ../core/porting/upgrade-assistant-overview.md + - name: Windows Presentation Foundation + href: ../core/porting/upgrade-assistant-wpf-framework.md + - name: Windows Forms + href: ../core/porting/upgrade-assistant-winforms-framework.md + - name: ASP.NET Core + href: ../core/porting/upgrade-assistant-aspnetmvc.md + - name: Breaking changes + displayName: app compatibility + href: ../core/porting/breaking-changes.md + - name: Pre-Migration + items: + - name: Asses the portability of your project + items: + - name: Unsupported Dependencies + href: ../core/porting/third-party-deps.md + - name: Use the Windows Compatibility Pack + href: ../core/porting/windows-compat-pack.md + - name: Unavailable technologies + href: ../core/porting/net-framework-tech-unavailable.md?toc=/dotnet/fundamentals/toc.json&bc=/dotnet/breadcrumb/toc.json + - name: Unsupported APIs + href: ../core/porting/unsupported-apis.md + - name: Needed changes before porting code + href: ../core/porting/premigration-needed-changes.md + - name: Migration + items: + - name: Create a porting plan + items: + - name: Approaches + href: ../core/porting/porting-approaches.md + - name: Project structure + href: ../core/porting/project-structure.md + - name: Application Porting Guides + items: + - name: Windows Forms + href: /dotnet/desktop/winforms/migration/?view=netdesktop-5.0 + - name: Windows Presentation Foundation + href: /dotnet/desktop/wpf/migration/convert-project-from-net-framework?view=netdesktop-5.0 + - name: Port C++/CLI projects + href: ../core/porting/cpp-cli.md From 7814398e1e1b5bd7262f1932b743e9a30caef2c5 Mon Sep 17 00:00:00 2001 From: Sven Boemer Date: Sun, 4 Jul 2021 17:15:17 -0700 Subject: [PATCH 09/27] Recommend setting publish options in project file (#24740) --- docs/core/deploying/single-file.md | 33 ++++++++++----- docs/core/deploying/trim-self-contained.md | 35 ++++++++++------ docs/core/deploying/trimming-options.md | 49 ++++++++++++++++++++-- docs/core/tools/dotnet-publish.md | 45 ++++++++++---------- 4 files changed, 114 insertions(+), 48 deletions(-) diff --git a/docs/core/deploying/single-file.md b/docs/core/deploying/single-file.md index ba1cd8701081b..019138f2047f6 100644 --- a/docs/core/deploying/single-file.md +++ b/docs/core/deploying/single-file.md @@ -123,9 +123,9 @@ Here's a sample project file that specifies single-file publishing: These properties have the following functions: -* `PublishSingleFile` - Enables single-file publishing. +* `PublishSingleFile` - Enables single-file publishing. Also enables single-file warnings during `dotnet build`. * `SelfContained` - Determines whether the app will be self-contained or framework-dependent. -* `RuntimeIdentifier` - Specifies the [OS and CPU type](../rid-catalog.md) you are targeting. +* `RuntimeIdentifier` - Specifies the [OS and CPU type](../rid-catalog.md) you are targeting. Also sets `true` by default. * `PublishTrimmed` - Enables use of [assembly trimming](trim-self-contained.md), which is only supported for self-contained apps. * `PublishReadyToRun` - Enables [ahead-of-time (AOT) compilation](ready-to-run.md). @@ -136,18 +136,29 @@ These properties have the following functions: ## Publish a single file app - CLI -Publish a single file application using the [dotnet publish](../tools/dotnet-publish.md) command. When you publish your app, set the following properties: +Publish a single file application using the [dotnet publish](../tools/dotnet-publish.md) command. -- Publish for a specific runtime: `-r win-x64` -- Publish as a single-file: `-p:PublishSingleFile=true` +01. Add `true` to your project file. -The following example publishes an app for Windows as a self-contained single file application. + This will produce a single-file app on self-contained publish. It also shows single-file compatibility warnings during build. -```dotnetcli -dotnet publish -r win-x64 -p:PublishSingleFile=true --self-contained true -``` + ```xml + + true + + ``` + +01. Publish the app as for a specific runtime identifier using `dotnet publish -r ` + + The following example publishes the app for Windows as a self-contained single file application. -The following example publishes an app for Linux as a framework dependent single file application. + `dotnet publish -r win-x64` + + The following example publishes the app for Linux as a framework dependent single file application. + + `dotnet publish -r linux-x64 --self-contained false` + +`` should be set in the project file to enable single-file analysis during build, but it is also possible to pass these options as `dotnet publish` arguments: ```dotnetcli dotnet publish -r linux-x64 -p:PublishSingleFile=true --self-contained false @@ -159,6 +170,8 @@ For more information, see [Publish .NET Core apps with .NET Core CLI](deploy-wit Visual Studio creates reusable publishing profiles that control how your application is published. +01. Add `true` to your project file. + 01. On the **Solution Explorer** pane, right-click on the project you want to publish. Select **Publish**. :::image type="content" source="media/single-file/visual-studio-solution-explorer.png" alt-text="Solution Explorer with a right-click menu highlighting the Publish option."::: diff --git a/docs/core/deploying/trim-self-contained.md b/docs/core/deploying/trim-self-contained.md index 097c272b77482..3871ed3540109 100644 --- a/docs/core/deploying/trim-self-contained.md +++ b/docs/core/deploying/trim-self-contained.md @@ -38,37 +38,48 @@ When the code is indirectly referencing an assembly through reflection, you can ## Trim your app - CLI -Trim your application using the [dotnet publish](../tools/dotnet-publish.md) command. When you publish your app, set the following properties: +Trim your application using the [dotnet publish](../tools/dotnet-publish.md) command. -- Publish as a self-contained app for a specific runtime: `-r win-x64` -- Enable trimming: `/p:PublishTrimmed=true` +01. Add `true` to your project file. -The following example publishes an app for Windows as self-contained and trims the output. + This will produce a trimmed app on self-contained publish. It also turns off trim-incompatible features and shows trim compatibility warnings during build. -```xml - - win-x64 - true - -``` + ```xml + + true + + ``` + +01. Publish a self-contained app for a specific runtime identifier using `dotnet publish -r ` -The following example publishes an app in the aggressive trim mode where unused code within assemblies will be trimmed and trimmer warnings enabled. + The following example publishes the app for Windows as trimmed self-contained application. + + `dotnet publish -r win-x64` + + Note that trimming is only supported for self-contained apps. + +The following example configures an app in the aggressive trim mode where unused code within assemblies will be trimmed and trimmer warnings enabled. ```xml - win-x64 true link false ``` +`` should be set in the project file so that trim-incompatible features are disabled during `dotnet build`, but it is also possible to pass these options as `dotnet publish` arguments: + +`dotnet publish -r win-x64 -p:PublishTrimmed=true` + For more information, see [Publish .NET Core apps with .NET Core CLI](deploy-with-cli.md). ## Trim your app - Visual Studio Visual Studio creates reusable publishing profiles that control how your application is published. +01. Add `true` to your project file. + 01. On the **Solution Explorer** pane, right-click on the project you want to publish. Select **Publish...**. :::image type="content" source="media/trim-self-contained/visual-studio-solution-explorer.png" alt-text="Solution Explorer with a right-click menu highlighting the Publish option."::: diff --git a/docs/core/deploying/trimming-options.md b/docs/core/deploying/trimming-options.md index 7b376bd139fe0..1ac6c83315ab4 100644 --- a/docs/core/deploying/trimming-options.md +++ b/docs/core/deploying/trimming-options.md @@ -16,13 +16,17 @@ Trimming with `PublishTrimmed` was introduced in .NET Core 3.0. The other option - `true` - Enable trimming during publish, with the default settings defined by the SDK. + Enable trimming during publish. This also turns off trim-incompatible features and enables [trim analysis](#roslyn-analyzer) during build. -This will trim any assemblies which have been configured for trimming. With `Microsoft.NET.Sdk` in .NET 6, this includes the any assemblies with `[AssemblyMetadata("IsTrimmable", "True")]`, which is the case for framework assemblies. In .NET 5, framework assemblies from the netcoreapp runtime pack are configured for trimming via `` MSBuild metadata. Other SDKs may define different defaults. +Place this in the project file to ensure that the setting applies during `dotnet build`, not just `dotnet publish`. + +This will trim any assemblies that have been configured for trimming. With `Microsoft.NET.Sdk` in .NET 6, this includes the any assemblies with `[AssemblyMetadata("IsTrimmable", "True")]`, which is the case for framework assemblies. In .NET 5, framework assemblies from the netcoreapp runtime pack are configured for trimming via `` MSBuild metadata. Other SDKs may define different defaults. + +Starting in .NET 6, this setting also enables the trim compatibility [Roslyn analyzer](#roslyn-analyzer), and disables [features that are incompatible with trimming](#framework-features-disabled-when-trimming). ## Trimming granularity -The following granularity settings control how aggressively unused IL is discarded. This can be set as a property affecting all trimmer input assemblies, or as metadata on an [individual assembly](#trimmed-assemblies) which overrides the property setting. +The following granularity settings control how aggressively unused IL is discarded. This can be set as a property affecting all trimmer input assemblies, or as metadata on an [individual assembly](#trimmed-assemblies), which overrides the property setting. - `link` @@ -173,6 +177,10 @@ The SDK also makes it possible to disable debugger support using the property `D Several feature areas of the framework libraries come with linker directives that make it possible to remove the code for disabled features. +- `false` (default) + + Remove code that creates autorelease pools on supported platforms. See [AutoreleasePool for managed threads](../run-time-config/threading.md#autoreleasepool-for-managed-threads). This is the default for the .NET SDK. + - `false` Remove code that enables better debugging experiences. This will also [remove symbols](#remove-symbols). @@ -197,8 +205,43 @@ Several feature areas of the framework libraries come with linker directives tha Remove globalization specific code and data. For more information, see [Invariant mode](../run-time-config/globalization.md#invariant-mode). +- `false` + + Remove metadata update specific logic related to hot reload. + +- `true` + + Use the default platform implementation of HttpMessageHandler for Android/iOS and remove the managed implementation. + - `true` Strip exception messages for `System.*` assemblies. When an exception is thrown from a `System.*` assembly, the message will be a simplified resource ID instead of the full message. These properties will cause the related code to be trimmed and will also disable features via the [runtimeconfig](../run-time-config/index.md) file. For more information about these properties, including the corresponding runtimeconfig options, see [feature switches](https://github.com/dotnet/runtime/blob/main/docs/workflow/trimming/feature-switches.md). Some SDKs may have default values for these properties. + +## Framework features disabled when trimming + +The following features are incompatible with trimming because they require code that is not statically referenced. These are disabled by default in trimmed apps. + +> [!WARNING] +> Enable these features at your own risk. They are likely to break trimmed apps without extra work to preserve the dynamically referenced code. + +- `` + + Built-in COM support is disabled. + +- `` + + Use of custom resource types is not supported. ResourceManager code paths that use reflection for custom resource types is trimmed. + +- `` + + C++/CLI host activation is disabled. + +- `` + + [`DesigntimeLicenceContextSerializer`](https://docs.microsoft.com/dotnet/api/system.componentmodel.design.designtimelicensecontextserializer?view=net-5.0) use of BinaryFormatter serialization is disabled. + +- `` + + Running code before `Main` with `DOTNET_STARTUP_HOOKS` is not supported. For more information, see [host startup hook](https://github.com/dotnet/runtime/blob/main/docs/design/features/host-startup-hook.md). diff --git a/docs/core/tools/dotnet-publish.md b/docs/core/tools/dotnet-publish.md index 252fec2c74a82..9efde78903b5b 100644 --- a/docs/core/tools/dotnet-publish.md +++ b/docs/core/tools/dotnet-publish.md @@ -18,7 +18,6 @@ dotnet publish [|] [-c|--configuration ] [-f|--framework ] [--force] [--interactive] [--manifest ] [--no-build] [--no-dependencies] [--no-restore] [--nologo] [-o|--output ] - [-p:PublishReadyToRun=true] [-p:PublishSingleFile=true] [-p:PublishTrimmed=true] [-r|--runtime ] [--self-contained [true|false]] [--no-self-contained] [-v|--verbosity ] [--version-suffix ] @@ -57,6 +56,28 @@ dotnet publish -p:PublishProfile=FolderProfile The preceding example uses the *FolderProfile.pubxml* file that is found in the *\/Properties/PublishProfiles* folder. If you specify a path and file extension when setting the `PublishProfile` property, they are ignored. MSBuild by default looks in the *Properties/PublishProfiles* folder and assumes the *pubxml* file extension. To specify the path and filename including extension, set the `PublishProfileFullPath` property instead of the `PublishProfile` property. +The following MSBuild properties change the output of `dotnet publish`. + +- `PublishReadyToRun` + + Compiles application assemblies as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation. For more information, see [ReadyToRun images](../deploying/ready-to-run.md). Available since .NET Core 3.0 SDK. + + To see warnings about missing dependencies that could cause runtime failures, use `PublishReadyToRunShowWarning=true`. + + We recommend that you specify `PublishReadyToRun` in a publish profile rather than on the command line. + +- `PublishSingleFile` + + Packages the app into a platform-specific single-file executable. For more information about single-file publishing, see the [single-file bundler design document](https://github.com/dotnet/designs/blob/main/accepted/2020/single-file/design.md). Available since .NET Core 3.0 SDK. + + We recommend that you specify this option in the project file rather than on the command line. + +- `PublishTrimmed` + + Trims unused libraries to reduce the deployment size of an app when publishing a self-contained executable. For more information, see [Trim self-contained deployments and executables](../deploying/trim-self-contained.md). Available since .NET Core 3.0 SDK as a preview feature. + + We recommend that you specify this option in the project file rather than on the command line. + For more information, see the following resources: - [MSBuild command-line reference](/visualstudio/msbuild/msbuild-command-line-reference) @@ -139,28 +160,6 @@ For more information, see the following resources: If you specify a relative path when publishing a solution, each project's output goes into a separate folder relative to the project file location. If you specify an absolute path when publishing a solution, all publish output for all projects goes into the specified folder. -- **`-p:PublishReadyToRun=true`** - - Compiles application assemblies as ReadyToRun (R2R) format. R2R is a form of ahead-of-time (AOT) compilation. For more information, see [ReadyToRun images](../deploying/ready-to-run.md). Available since .NET Core 3.0 SDK. - - To see warnings about missing dependencies that could cause runtime failures, use `-p:PublishReadyToRunShowWarnings=true`. - - We recommend that you specify this option in a publish profile rather than on the command line. For more information, see [MSBuild](#msbuild). - -- **`-p:PublishSingleFile=true`** - - Packages the app into a platform-specific single-file executable. The executable is self-extracting and contains all dependencies (including native) that are required to run the app. When the app is first run, the application is extracted to a directory based on the app name and build identifier. Startup is faster when the application is run again. The application doesn't need to extract itself a second time unless a new version is used. Available since .NET Core 3.0 SDK. - - For more information about single-file publishing, see the [single-file bundler design document](https://github.com/dotnet/designs/blob/main/accepted/2020/single-file/design.md). - - We recommend that you specify this option in a publish profile rather than on the command line. For more information, see [MSBuild](#msbuild). - -- **`-p:PublishTrimmed=true`** - - Trims unused libraries to reduce the deployment size of an app when publishing a self-contained executable. For more information, see [Trim self-contained deployments and executables](../deploying/trim-self-contained.md). Available since .NET Core 3.0 SDK as a preview feature. - - We recommend that you specify this option in a publish profile rather than on the command line. For more information, see [MSBuild](#msbuild). - - **`--self-contained [true|false]`** Publishes the .NET runtime with your application so the runtime doesn't need to be installed on the target machine. Default is `true` if a runtime identifier is specified and the project is an executable project (not a library project). For more information, see [.NET application publishing](../deploying/index.md) and [Publish .NET apps with the .NET CLI](../deploying/deploy-with-cli.md). From f47aa43c0990cd75d7d2eacd21dc168954787152 Mon Sep 17 00:00:00 2001 From: Naidile P N Date: Tue, 6 Jul 2021 17:28:23 +0530 Subject: [PATCH 10/27] Update relational-vs-nosql-data.md (#24996) Correcting the typo - from Moden to Modern --- docs/architecture/cloud-native/relational-vs-nosql-data.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/cloud-native/relational-vs-nosql-data.md b/docs/architecture/cloud-native/relational-vs-nosql-data.md index 6712f9c69d77d..fe7bdfd8a7118 100644 --- a/docs/architecture/cloud-native/relational-vs-nosql-data.md +++ b/docs/architecture/cloud-native/relational-vs-nosql-data.md @@ -58,7 +58,7 @@ NoSQL databases typically support high availability and partition tolerance. The If data replicas were to lose connectivity in a "highly available" NoSQL database cluster, you could still complete a write operation to the database. The database cluster would allow the write operation and update each data replica as it becomes available. NoSQL databases that support multiple writable replicas can further strengthen high availability by avoiding the need for failover when optimizing recovery time objective. -Moden NoSQL databases typically implement partitioning capabilities as a feature of their system design. Partition management is often built-in to the database, and routing is achieved through placement hints - often called partition keys. A flexible data models enables the NoSQL databases to lower the burden of schema management and improve availablity when deploying application updates that require data model changes. +Modern NoSQL databases typically implement partitioning capabilities as a feature of their system design. Partition management is often built-in to the database, and routing is achieved through placement hints - often called partition keys. A flexible data models enables the NoSQL databases to lower the burden of schema management and improve availablity when deploying application updates that require data model changes. High availability and massive scalability are often more critical to the business than relational table joins and referential integrity. Developers can implement techniques and patterns such as Sagas, CQRS, and asynchronous messaging to embrace eventual consistency. From c9a92fc93b77d650eb2f9df3fed0b23527e7d068 Mon Sep 17 00:00:00 2001 From: v-hearya Date: Tue, 6 Jul 2021 18:39:25 +0530 Subject: [PATCH 11/27] frequently-asked-questions.md converted into YML (#24870) * frequently-asked-questions.md converted into YML * Update docs/framework/data/adonet/sql/linq/frequently-asked-questions.yml Co-authored-by: Youssef Victor * Updated questions [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] replaced with LINQ to SQ in Questions only as they don't support [!INCLUDE]. * link tag removed from Questions as they don't support it Co-authored-by: Youssef Victor --- .../sql/linq/frequently-asked-questions.md | 228 ---------------- .../sql/linq/frequently-asked-questions.yml | 252 ++++++++++++++++++ .../data/adonet/sql/linq/reference.md | 2 +- .../sql/linq/security-in-linq-to-sql.md | 2 +- docs/framework/data/adonet/sql/linq/toc.yml | 2 +- .../data/adonet/sql/linq/troubleshooting.md | 4 +- 6 files changed, 257 insertions(+), 233 deletions(-) delete mode 100644 docs/framework/data/adonet/sql/linq/frequently-asked-questions.md create mode 100644 docs/framework/data/adonet/sql/linq/frequently-asked-questions.yml diff --git a/docs/framework/data/adonet/sql/linq/frequently-asked-questions.md b/docs/framework/data/adonet/sql/linq/frequently-asked-questions.md deleted file mode 100644 index 15b7f032aa180..0000000000000 --- a/docs/framework/data/adonet/sql/linq/frequently-asked-questions.md +++ /dev/null @@ -1,228 +0,0 @@ ---- -description: "Learn more about: Frequently Asked Questions" -title: "Frequently Asked Questions" -ms.date: "03/30/2017" -dev_langs: - - "csharp" - - "vb" -ms.assetid: 252ed666-0679-4eea-b71b-2f14117ef443 ---- -# Frequently Asked Questions - -The following sections answer some common issues that you might encounter when you implement LINQ. - -Additional issues are addressed in [Troubleshooting](troubleshooting.md). - -## Cannot Connect - -Q. I cannot connect to my database. - -A. Make sure your connection string is correct and that your SQL Server instance is running. Note also that [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] requires the Named Pipes protocol to be enabled. For more information, see [Learning by Walkthroughs](learning-by-walkthroughs.md). - -## Changes to Database Lost - -Q. I made a change to data in the database, but when I reran my application, the change was no longer there. - -A. Make sure that you call to save results to the database. - -## Database Connection: Open How Long? - -Q. How long does my database connection remain open? - -A. A connection typically remains open until you consume the query results. If you expect to take time to process all the results and are not opposed to caching the results, apply to the query. In common scenarios where each object is processed only one time, the streaming model is superior in both `DataReader` and [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)]. - -The exact details of connection usage depend on the following: - -- Connection status if the is constructed with a connection object. - -- Connection string settings (for example, enabling Multiple Active Result Sets (MARS). For more information, see [Multiple Active Result Sets (MARS)](../multiple-active-result-sets-mars.md). - -## Updating Without Querying - -Q. Can I update table data without first querying the database? - -A. Although [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] does not have set-based update commands, you can use either of the following techniques to update without first querying: - -- Use to send SQL code. - -- Create a new instance of the object and initialize all the current values (fields) that affect the update. Then attach the object to the by using and modify the field you want to change. - -## Unexpected Query Results - -Q. My query is returning unexpected results. How can I inspect what is occurring? - -A. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] provides several tools for inspecting the SQL code it generates. One of the most important is . For more information, see [Debugging Support](debugging-support.md). - -## Unexpected Stored Procedure Results - -Q. I have a stored procedure whose return value is calculated by `MAX()`. When I drag the stored procedure to the O/R Designer surface, the return value is not correct. - -A. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] provides two ways to return database-generated values by way of stored procedures: - -- By naming the output result. - -- By explicitly specifying an output parameter. - -The following is an example of incorrect output. Because [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] cannot map the results, it always returns 0: - -```sql -create procedure proc2 - -as - -begin - -select max(i) from t where name like 'hello' - -end -``` - -The following is an example of correct output by using an output parameter: - -```sql -create procedure proc2 - -@result int OUTPUT - -as - -select @result = MAX(i) from t where name like 'hello' - -go -``` - -The following is an example of correct output by naming the output result: - -```sql -create procedure proc2 - -as - -begin - -select nax(i) AS MaxResult from t where name like 'hello' - -end -``` - -For more information, see [Customizing Operations By Using Stored Procedures](customizing-operations-by-using-stored-procedures.md). - -## Serialization Errors - -Q. When I try to serialize, I get the following error: "Type 'System.Data.Linq.ChangeTracker+StandardChangeTracker' ... is not marked as serializable." - -A. Code generation in [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] supports serialization. It does not support or . For more information, see [Serialization](serialization.md). - -## Multiple DBML Files - -Q. When I have multiple DBML files that share some tables in common, I get a compiler error. - -A. Set the **Context Namespace** and **Entity Namespace** properties from the Object Relational Designer to a distinct value for each DBML file. This approach eliminates the name/namespace collision. - -## Avoiding Explicit Setting of Database-Generated Values on Insert or Update - -Q. I have a database table with a `DateCreated` column that defaults to SQL `Getdate()`. When I try to insert a new record by using [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)], the value gets set to `NULL`. I would expect it to be set to the database default. - -A. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] handles this situation automatically for identity (auto-increment) and rowguidcol (database-generated GUID) and timestamp columns. In other cases, you should manually set =`true` and =// properties. - -## Multiple DataLoadOptions - -Q. Can I specify additional load options without overwriting the first? - -A. Yes. The first is not overwritten, as in the following example: - -```vb -Dim dlo As New DataLoadOptions() -dlo.LoadWith(Of Order)(Function(o As Order) o.Customer) -dlo.LoadWith(Of Order)(Function(o As Order) o.OrderDetails) -``` - -```csharp -DataLoadOptions dlo = new DataLoadOptions(); -dlo.LoadWith(o => o.Customer); -dlo.LoadWith(o => o.OrderDetails); -``` - -## Errors Using SQL Compact 3.5 - -Q. I get an error when I drag tables out of a SQL Server Compact 3.5 database. - -A. The Object Relational Designer does not support SQL Server Compact 3.5, although the [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] runtime does. In this situation, you must create your own entity classes and add the appropriate attributes. - -## Errors in Inheritance Relationships - -Q. I used the toolbox inheritance shape in the Object Relational Designer to connect two entities, but I get errors. - -A. Creating the relationship is not enough. You must provide information such as the discriminator column, base class discriminator value, and derived class discriminator value. - -## Provider Model - -Q. Is a public provider model available? - -A. No public provider model is available. At this time, [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] supports SQL Server and SQL Server Compact 3.5 only. - -## SQL-Injection Attacks - -Q. How is [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] protected from SQL-injection attacks? - -A. SQL injection has been a significant risk for traditional SQL queries formed by concatenating user input. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] avoids such injection by using in queries. User input is turned into parameter values. This approach prevents malicious commands from being used from customer input. - -## Changing Read-only Flag in DBML Files - -Q. How do I eliminate setters from some properties when I create an object model from a DBML file? - -A. Take the following steps for this advanced scenario: - -1. In the .dbml file, modify the property by changing the flag to `True`. - -2. Add a partial class. Create a constructor with parameters for the read-only members. - -3. Review the default value () to determine whether that is the correct value for your application. - - > [!CAUTION] - > If you are using the Object Relational Designer in Visual Studio, your changes might be overwritten. - -## APTCA - -Q. Is System.Data.Linq marked for use by partially trusted code? - -A. Yes, the System.Data.Linq.dll assembly is among those .NET Framework assemblies marked with the attribute. Without this marking, assemblies in the .NET Framework are intended for use only by fully trusted code. - -The principal scenario in [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] for allowing partially trusted callers is to enable the [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] assembly to be accessed from Web applications, where the *trust* configuration is Medium. - -## Mapping Data from Multiple Tables - -Q. The data in my entity comes from multiple tables. How do I map it? - -A. You can create a view in a database and map the entity to the view. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] generates the same SQL for views as it does for tables. - -> [!NOTE] -> The use of views in this scenario has limitations. This approach works most safely when the operations performed on are supported by the underlying view. Only you know which operations are intended. For example, most applications are read-only, and another sizeable number perform `Create`/`Update`/`Delete` operations only by using stored procedures against views. - -## Connection Pooling - -Q. Is there a construct that can help with pooling? - -A. Do not try to reuse instances of . Each maintains state (including an identity cache) for one particular edit/query session. To obtain new instances based on the current state of the database, use a new . - -You can still use underlying ADO.NET connection pooling. For more information, see [SQL Server Connection Pooling (ADO.NET)](../../sql-server-connection-pooling.md). - -## Second DataContext Is Not Updated - -Q. I used one instance of to store values in the database. However, a second on the same database does not reflect the updated values. The second instance seems to return cached values. - -A. This behavior is by design. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] continues to return the same instances/values that you saw in the first instance. When you make updates, you use optimistic concurrency. The original data is used to check against the current database state to assert that it is in fact still unchanged. If it has changed, a conflict occurs and your application must resolve it. One option of your application is to reset the original state to the current database state and to try the update again. For more information, see [How to: Manage Change Conflicts](how-to-manage-change-conflicts.md). - -You can also set to false, which turns off caching and change tracking. You can then retrieve the latest values every time that you query. - -## Cannot Call SubmitChanges in Read-only Mode - -Q. When I try to call in read-only mode, I get an error. - -A. Read-only mode turns off the ability of the context to track changes. - -## See also - -- [Reference](reference.md) -- [Troubleshooting](troubleshooting.md) -- [Security in LINQ to SQL](security-in-linq-to-sql.md) diff --git a/docs/framework/data/adonet/sql/linq/frequently-asked-questions.yml b/docs/framework/data/adonet/sql/linq/frequently-asked-questions.yml new file mode 100644 index 0000000000000..e354bbea984ec --- /dev/null +++ b/docs/framework/data/adonet/sql/linq/frequently-asked-questions.yml @@ -0,0 +1,252 @@ +### YamlMime:FAQ +metadata: + description: "Learn more about: Frequently Asked Questions" + title: "Frequently Asked Questions" + ms.date: "03/30/2017" + dev_langs: + - "csharp" + - "vb" + +title: Frequently Asked Questions +summary: | + The following sections answer some common issues that you might encounter when you implement LINQ. + + Additional issues are addressed in [Troubleshooting](troubleshooting.md). + + +sections: + - name: Cannot Connect + questions: + - question: | + I cannot connect to my database. + answer: | + Make sure your connection string is correct and that your SQL Server instance is running. Note also that [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] requires the Named Pipes protocol to be enabled. For more information, see [Learning by Walkthroughs](learning-by-walkthroughs.md). + + - name: Changes to Database Lost + questions: + - question: | + I made a change to data in the database, but when I reran my application, the change was no longer there. + answer: | + Make sure that you call to save results to the database. + + - name: "Database Connection: Open How Long?" + questions: + - question: | + How long does my database connection remain open? + answer: | + A connection typically remains open until you consume the query results. If you expect to take time to process all the results and are not opposed to caching the results, apply to the query. In common scenarios where each object is processed only one time, the streaming model is superior in both `DataReader` and [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)]. + + The exact details of connection usage depend on the following: + + - Connection status if the is constructed with a connection object. + + - Connection string settings (for example, enabling Multiple Active Result Sets (MARS). For more information, see [Multiple Active Result Sets (MARS)](../multiple-active-result-sets-mars.md). + + - name: Updating Without Querying + questions: + - question: | + Can I update table data without first querying the database? + answer: | + Although [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] does not have set-based update commands, you can use either of the following techniques to update without first querying: + + - Use to send SQL code. + + - Create a new instance of the object and initialize all the current values (fields) that affect the update. Then attach the object to the by using and modify the field you want to change. + + - name: Unexpected Query Results + questions: + - question: | + My query is returning unexpected results. How can I inspect what is occurring? + answer: | + [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] provides several tools for inspecting the SQL code it generates. One of the most important is . For more information, see [Debugging Support](debugging-support.md). + + - name: Unexpected Stored Procedure Results + questions: + - question: | + I have a stored procedure whose return value is calculated by `MAX()`. When I drag the stored procedure to the O/R Designer surface, the return value is not correct. + answer: | + [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] provides two ways to return database-generated values by way of stored procedures: + + - By naming the output result. + + - By explicitly specifying an output parameter. + + The following is an example of incorrect output. Because [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] cannot map the results, it always returns 0: + + ```sql + create procedure proc2 + + as + + begin + + select max(i) from t where name like 'hello' + + end + ``` + + The following is an example of correct output by using an output parameter: + + ```sql + create procedure proc2 + + @result int OUTPUT + + as + + select @result = MAX(i) from t where name like 'hello' + + go + ``` + + The following is an example of correct output by naming the output result: + + ```sql + create procedure proc2 + + as + + begin + + select nax(i) AS MaxResult from t where name like 'hello' + + end + ``` + + For more information, see [Customizing Operations By Using Stored Procedures](customizing-operations-by-using-stored-procedures.md). + + - name: Serialization Errors + questions: + - question: | + When I try to serialize, I get the following error: "Type 'System.Data.Linq.ChangeTracker+StandardChangeTracker' ... is not marked as serializable." + answer: | + Code generation in [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] supports serialization. It does not support or . For more information, see [Serialization](serialization.md). + + - name: Multiple DBML Files + questions: + - question: | + When I have multiple DBML files that share some tables in common, I get a compiler error. + answer: | + Set the **Context Namespace** and **Entity Namespace** properties from the Object Relational Designer to a distinct value for each DBML file. This approach eliminates the name/namespace collision. + + - name: Avoiding Explicit Setting of Database-Generated Values on Insert or Update + questions: + - question: | + I have a database table with a `DateCreated` column that defaults to SQL `Getdate()`. When I try to insert a new record by using LINQ to SQL, the value gets set to `NULL`. I would expect it to be set to the database default. + answer: | + [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] handles this situation automatically for identity (auto-increment) and rowguidcol (database-generated GUID) and timestamp columns. In other cases, you should manually set =`true` and =// properties. + + - name: Multiple DataLoadOptions + questions: + - question: | + Can I specify additional load options without overwriting the first? + answer: | + Yes. The first is not overwritten, as in the following example: + + ```vb + Dim dlo As New DataLoadOptions() + dlo.LoadWith(Of Order)(Function(o As Order) o.Customer) + dlo.LoadWith(Of Order)(Function(o As Order) o.OrderDetails) + ``` + + ```csharp + DataLoadOptions dlo = new DataLoadOptions(); + dlo.LoadWith(o => o.Customer); + dlo.LoadWith(o => o.OrderDetails); + ``` + + - name: Errors Using SQL Compact 3.5 + questions: + - question: | + I get an error when I drag tables out of a SQL Server Compact 3.5 database. + answer: | + The Object Relational Designer does not support SQL Server Compact 3.5, although the [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] runtime does. In this situation, you must create your own entity classes and add the appropriate attributes. + + - name: Errors in Inheritance Relationships + questions: + - question: | + I used the toolbox inheritance shape in the Object Relational Designer to connect two entities, but I get errors. + answer: | + Creating the relationship is not enough. You must provide information such as the discriminator column, base class discriminator value, and derived class discriminator value. + + - name: Provider Model + questions: + - question: | + Is a public provider model available? + answer: | + No public provider model is available. At this time, [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] supports SQL Server and SQL Server Compact 3.5 only. + + - name: SQL-Injection Attacks + questions: + - question: | + How is LINQ to SQL protected from SQL-injection attacks? + answer: | + SQL injection has been a significant risk for traditional SQL queries formed by concatenating user input. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] avoids such injection by using in queries. User input is turned into parameter values. This approach prevents malicious commands from being used from customer input. + + - name: Changing Read-only Flag in DBML Files + questions: + - question: | + How do I eliminate setters from some properties when I create an object model from a DBML file? + answer: | + Take the following steps for this advanced scenario: + + 1. In the .dbml file, modify the property by changing the flag to `True`. + + 2. Add a partial class. Create a constructor with parameters for the read-only members. + + 3. Review the default value () to determine whether that is the correct value for your application. + + > [!CAUTION] + > If you are using the Object Relational Designer in Visual Studio, your changes might be overwritten. + + - name: APTCA + questions: + - question: | + Is System.Data.Linq marked for use by partially trusted code? + answer: | + Yes, the System.Data.Linq.dll assembly is among those .NET Framework assemblies marked with the attribute. Without this marking, assemblies in the .NET Framework are intended for use only by fully trusted code. + + The principal scenario in [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] for allowing partially trusted callers is to enable the [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] assembly to be accessed from Web applications, where the *trust* configuration is Medium. + + - name: Mapping Data from Multiple Tables + questions: + - question: | + The data in my entity comes from multiple tables. How do I map it? + answer: | + You can create a view in a database and map the entity to the view. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] generates the same SQL for views as it does for tables. + + > [!NOTE] + > The use of views in this scenario has limitations. This approach works most safely when the operations performed on are supported by the underlying view. Only you know which operations are intended. For example, most applications are read-only, and another sizeable number perform `Create`/`Update`/`Delete` operations only by using stored procedures against views. + + - name: Connection Pooling + questions: + - question: | + Is there a construct that can help with DataContext pooling? + answer: | + Do not try to reuse instances of . Each maintains state (including an identity cache) for one particular edit/query session. To obtain new instances based on the current state of the database, use a new . + + You can still use underlying ADO.NET connection pooling. For more information, see [SQL Server Connection Pooling (ADO.NET)](../../sql-server-connection-pooling.md). + + - name: Second DataContext Is Not Updated + questions: + - question: | + I used one instance of DataContext to store values in the database. However, a second DataContext on the same database does not reflect the updated values. The second DataContext instance seems to return cached values. + answer: | + This behavior is by design. [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] continues to return the same instances/values that you saw in the first instance. When you make updates, you use optimistic concurrency. The original data is used to check against the current database state to assert that it is in fact still unchanged. If it has changed, a conflict occurs and your application must resolve it. One option of your application is to reset the original state to the current database state and to try the update again. For more information, see [How to: Manage Change Conflicts](how-to-manage-change-conflicts.md). + + You can also set to false, which turns off caching and change tracking. You can then retrieve the latest values every time that you query. + + - name: Cannot Call SubmitChanges in Read-only Mode + questions: + - question: | + When I try to call SubmitChanges in read-only mode, I get an error. + answer: | + Read-only mode turns off the ability of the context to track changes. + +additionalContent: | + + ## See also + + - [Reference](reference.md) + - [Troubleshooting](troubleshooting.md) + - [Security in LINQ to SQL](security-in-linq-to-sql.md) diff --git a/docs/framework/data/adonet/sql/linq/reference.md b/docs/framework/data/adonet/sql/linq/reference.md index 52a9c6c3f3ea2..0eebd6238caaa 100644 --- a/docs/framework/data/adonet/sql/linq/reference.md +++ b/docs/framework/data/adonet/sql/linq/reference.md @@ -24,7 +24,7 @@ This section provides reference information for [!INCLUDE[vbtecdlinq](../../../. [External Mapping](external-mapping.md) Describes the [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] external-mapping approach to mapping a [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] object model to a SQL Server database. Provides the XSD schema definition for mapping files. - [Frequently Asked Questions](frequently-asked-questions.md) + [Frequently Asked Questions](frequently-asked-questions.yml) Provides answers to common questions regarding [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)]. [SQL Server Compact and LINQ to SQL](sql-server-compact-and-linq-to-sql.md) diff --git a/docs/framework/data/adonet/sql/linq/security-in-linq-to-sql.md b/docs/framework/data/adonet/sql/linq/security-in-linq-to-sql.md index db64ab1192219..0c617200cebea 100644 --- a/docs/framework/data/adonet/sql/linq/security-in-linq-to-sql.md +++ b/docs/framework/data/adonet/sql/linq/security-in-linq-to-sql.md @@ -35,4 +35,4 @@ Security risks are always present when you connect to a database. Although LINQ ## See also - [Background Information](background-information.md) -- [Frequently Asked Questions](frequently-asked-questions.md) +- [Frequently Asked Questions](frequently-asked-questions.yml) diff --git a/docs/framework/data/adonet/sql/linq/toc.yml b/docs/framework/data/adonet/sql/linq/toc.yml index 3bd08002ac165..b8498a679b0da 100644 --- a/docs/framework/data/adonet/sql/linq/toc.yml +++ b/docs/framework/data/adonet/sql/linq/toc.yml @@ -328,7 +328,7 @@ - name: External Mapping href: external-mapping.md - name: Frequently Asked Questions - href: frequently-asked-questions.md + href: frequently-asked-questions.yml - name: SQL Server Compact and LINQ to SQL href: sql-server-compact-and-linq-to-sql.md - name: Standard Query Operator Translation diff --git a/docs/framework/data/adonet/sql/linq/troubleshooting.md b/docs/framework/data/adonet/sql/linq/troubleshooting.md index bc9a17e7e2a03..cdcae1e0349dd 100644 --- a/docs/framework/data/adonet/sql/linq/troubleshooting.md +++ b/docs/framework/data/adonet/sql/linq/troubleshooting.md @@ -8,7 +8,7 @@ ms.assetid: 8cd4401c-b12c-4116-a421-f3dcffa65670 The following information exposes some issues you might encounter in your [!INCLUDE[vbtecdlinq](../../../../../../includes/vbtecdlinq-md.md)] applications, and provides suggestions to avoid or otherwise reduce the effect of these issues. - Additional issues are addressed in [Frequently Asked Questions](frequently-asked-questions.md). + Additional issues are addressed in [Frequently Asked Questions](frequently-asked-questions.yml). ## Unsupported Standard Query Operators @@ -79,4 +79,4 @@ The following information exposes some issues you might encounter in your [!INCL ## See also - [Debugging Support](debugging-support.md) -- [Frequently Asked Questions](frequently-asked-questions.md) +- [Frequently Asked Questions](frequently-asked-questions.yml) From ebd354a2a87b9a842e6e64ec0bc176e40d571e6c Mon Sep 17 00:00:00 2001 From: Azure SDK Bot <53356347+azure-sdk@users.noreply.github.com> Date: Tue, 6 Jul 2021 07:10:38 -0700 Subject: [PATCH 12/27] Update package index with latest published versions (#24970) --- docs/azure/includes/dotnet-all.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 7c58763589cc8..43c2f91beabbd 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -448,7 +448,7 @@ | Management - Container Instances Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerInstance.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/containerinstance) | | | Management - Container Registry | NuGet [5.0.0-preview.5](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerRegistry/5.0.0-preview.5) | | GitHub [5.0.0-preview.5](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ContainerRegistry_5.0.0-preview.5/sdk/containerregistry/Microsoft.Azure.Management.ContainerRegistry/) | | Management - Container Registry Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerRegistry.Fluent/1.37.1) | | | -| Management - Container Service | NuGet [1.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerService/1.1.0) | | GitHub [1.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ContainerService_1.1.0/sdk/containerservice/Microsoft.Azure.Management.ContainerService/) | +| Management - Container Service | NuGet [1.2.0](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerService/1.2.0) | | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.ContainerService_1.2.0/sdk/containerservice/Microsoft.Azure.Management.ContainerService/) | | Management - Container Service Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.ContainerService.Fluent/1.37.1) | | | | Management - Content Delivery Network | NuGet [6.1.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Cdn/6.1.0) | | GitHub [6.1.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Cdn_6.1.0/sdk/cdn/Microsoft.Azure.Management.Cdn/) | | Management - Content Delivery Network Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Cdn.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/cdn) | | @@ -514,7 +514,7 @@ | Management - Media Services | NuGet [4.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Media/4.0.0) | | GitHub [4.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Media_4.0.0/sdk/mediaservices/Microsoft.Azure.Management.Media/) | | Management - Migrate Resource Mover | NuGet [2.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.Migrate.ResourceMover/2.0.0) | | | | Management - Mixed Reality | NuGet [3.0.0](https://www.nuget.org/packages/Microsoft.Azure.Management.MixedReality/3.0.0) | [docs](/dotnet/api/overview/azure/mixed-reality) | GitHub [3.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.MixedReality_3.0.0/sdk/mixedreality/Microsoft.Azure.Management.MixedReality/) | -| Management - Monitor | NuGet [0.25.3-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Monitor/0.25.3-preview) | | GitHub [0.25.3-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Monitor_0.25.3-preview/sdk/monitor/Microsoft.Azure.Management.Monitor/) | +| Management - Monitor | NuGet [0.25.4-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.Monitor/0.25.4-preview) | | GitHub [0.25.4-preview](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.Monitor_0.25.4-preview/sdk/monitor/Microsoft.Azure.Management.Monitor/) | | Management - Monitor Fluent | NuGet [1.37.1](https://www.nuget.org/packages/Microsoft.Azure.Management.Monitor.Fluent/1.37.1) | [docs](/dotnet/api/overview/azure/monitor) | | | Management - MySQL | NuGet [0.1.0-preview](https://www.nuget.org/packages/Microsoft.Azure.Management.MySQL/0.1.0-preview) | | | | Management - NetApp | NuGet [1.12.0](https://www.nuget.org/packages/Microsoft.Azure.Management.NetApp/1.12.0) | | GitHub [1.12.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Management.NetApp_1.12.0/sdk/netapp/Microsoft.Azure.Management.NetApp/) | From b484976670d77fd852b381df24145a5dbe11fe7c Mon Sep 17 00:00:00 2001 From: Steve Berdy <86739818+steveberdy@users.noreply.github.com> Date: Tue, 6 Jul 2021 10:11:14 -0400 Subject: [PATCH 13/27] Update how-to-implement-a-lightweight-class-with-auto-implemented-properties.md (#24975) Added semicolon to code example --- ...ment-a-lightweight-class-with-auto-implemented-properties.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/csharp/programming-guide/classes-and-structs/how-to-implement-a-lightweight-class-with-auto-implemented-properties.md b/docs/csharp/programming-guide/classes-and-structs/how-to-implement-a-lightweight-class-with-auto-implemented-properties.md index 2f3b7d26c1425..7514850ca3941 100644 --- a/docs/csharp/programming-guide/classes-and-structs/how-to-implement-a-lightweight-class-with-auto-implemented-properties.md +++ b/docs/csharp/programming-guide/classes-and-structs/how-to-implement-a-lightweight-class-with-auto-implemented-properties.md @@ -42,7 +42,7 @@ class Contact //public void ChangeName(string newName) => Name = newName; // Address is assignable here. - public void ChangeAddress(string newAddress) => Address = newAddress + public void ChangeAddress(string newAddress) => Address = newAddress; } ``` From b994265a306c35491e7b91eca69fbf29d4147d45 Mon Sep 17 00:00:00 2001 From: Youssef Victor Date: Tue, 6 Jul 2021 16:12:58 +0200 Subject: [PATCH 14/27] Add missing semicolon (#24989) --- docs/core/extensions/logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/extensions/logging.md b/docs/core/extensions/logging.md index 48b16379af79f..9b0ed02b87a93 100644 --- a/docs/core/extensions/logging.md +++ b/docs/core/extensions/logging.md @@ -358,7 +358,7 @@ public void Test(string id) { _logger.LogWarning( AppLogEvents.Error, ex, - "Failed to process iteration: {Id}", id) + "Failed to process iteration: {Id}", id); } } ``` From b01057e5266eb8222a92cd022f8ac820cde5f02d Mon Sep 17 00:00:00 2001 From: Sipke Schoorstra Date: Tue, 6 Jul 2021 16:14:35 +0200 Subject: [PATCH 15/27] Fix small typo in name of Elsa Workflows (#24990) --- docs/core/dotnet-five.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/dotnet-five.md b/docs/core/dotnet-five.md index 248ce3e52a666..ecc77f5a80199 100644 --- a/docs/core/dotnet-five.md +++ b/docs/core/dotnet-five.md @@ -44,7 +44,7 @@ There are no plans to port the following technologies from .NET Framework to .NE | Technology | Recommended alternative | |-----------------------|-------------------------------------------------------------------------------------------------| | Web Forms | ASP.NET Core [Blazor](/aspnet/core/blazor) or [Razor Pages](/aspnet/core/tutorials/razor-pages) | -| Windows Workflow (WF) | [Open-source CoreWF](https://github.com/UiPath-Open/corewf) or [Elsa-Workflow](https://github.com/elsa-workflows/elsa-core) | +| Windows Workflow (WF) | [Open-source CoreWF](https://github.com/UiPath-Open/corewf) or [Elsa-Workflows](https://github.com/elsa-workflows/elsa-core) | ### Windows Communication Foundation From c7d02a73f5736abdd00f9997ae6e64536d4f6068 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 6 Jul 2021 12:16:37 -0400 Subject: [PATCH 16/27] add closing tick (#24997) The missing backtick meant the table syntax was invalid. --- docs/core/diagnostics/available-counters.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/diagnostics/available-counters.md b/docs/core/diagnostics/available-counters.md index c1b3e5a755372..0405c2c45f9a3 100644 --- a/docs/core/diagnostics/available-counters.md +++ b/docs/core/diagnostics/available-counters.md @@ -91,7 +91,7 @@ The following counters are published by the HTTP stack. | :::no-loc text="Requests Failed"::: (`requests-failed`) | The number of failed requests since the process started | .NET 5 | | :::no-loc text="Requests Failed Rate"::: (`requests-failed-rate`) | The number of failed requests per update interval | .NET 5 | | :::no-loc text="Current Requests"::: (`current-requests`) | Current number of active HTTP requests that have started but not yet completed or failed | .NET 5 | -| :::no-loc text="Current HTTP 1.1 Connections"::: (`http11-connections-current-total) | The current number of HTTP 1.1 connections that have started but not yet completed or failed | .NET 5 | +| :::no-loc text="Current HTTP 1.1 Connections"::: (`http11-connections-current-total`) | The current number of HTTP 1.1 connections that have started but not yet completed or failed | .NET 5 | | :::no-loc text="Current HTTP 2.0 Connections"::: (`http20-connections-current-total`) | The current number of HTTP 2.0 connections that have started but not yet completed or failed | .NET 5 | | :::no-loc text="HTTP 1.1 Requests Queue Duration"::: (`http11-requests-queue-duration`) | The average duration of the time HTTP 1.1 requests spent in the request queue | .NET 5 | | :::no-loc text="HTTP 2.0 Requests Queue Duration"::: (`http20-requests-queue-duration`) | The average duration of the time HTTP 2.0 requests spent in the request queue | .NET 5 | From 0063cc23afe870f750dd3637e0da6e271bc78dac Mon Sep 17 00:00:00 2001 From: Kevin Locke Date: Tue, 6 Jul 2021 16:23:34 +0000 Subject: [PATCH 17/27] Fix RegexOptions.IgnorePatternWhitespace # to EOL (#24936) * Fix RegexOptions.IgnorePatternWhitespace # to EOL * Update regular-expression-options.md Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> --- docs/standard/base-types/regular-expression-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/standard/base-types/regular-expression-options.md b/docs/standard/base-types/regular-expression-options.md index 6c40941c0d9d9..2ec8cbb42e123 100644 --- a/docs/standard/base-types/regular-expression-options.md +++ b/docs/standard/base-types/regular-expression-options.md @@ -253,7 +253,7 @@ The option: From 105f0b1951aeff7e57a872a3dc4746ac22db9f23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rubens=20Vinicius=20Apolin=C3=A1rio?= Date: Tue, 6 Jul 2021 13:33:56 -0300 Subject: [PATCH 18/27] Add example for Retreving Array Elements (#24993) * Add example for Retreving Array Elements * Update docs/csharp/programming-guide/arrays/single-dimensional-arrays.md Co-authored-by: Bill Wagner * Taking off the example of exception as sugested Co-authored-by: Bill Wagner --- .../arrays/single-dimensional-arrays.md | 6 +++ .../arrays/snippets/RetrevingArrayElements.cs | 39 +++++++++++++++++++ 2 files changed, 45 insertions(+) create mode 100644 docs/csharp/programming-guide/arrays/snippets/RetrevingArrayElements.cs diff --git a/docs/csharp/programming-guide/arrays/single-dimensional-arrays.md b/docs/csharp/programming-guide/arrays/single-dimensional-arrays.md index 9418e4d9f2f7f..1fa6df27586e6 100644 --- a/docs/csharp/programming-guide/arrays/single-dimensional-arrays.md +++ b/docs/csharp/programming-guide/arrays/single-dimensional-arrays.md @@ -44,6 +44,12 @@ Consider the following array declaration: :::code language="csharp" source="snippets/SingleDimensionArrays.cs" id="FinalInstantiation"::: The result of this statement depends on whether `SomeType` is a value type or a reference type. If it's a value type, the statement creates an array of 10 elements, each of which has the type `SomeType`. If `SomeType` is a reference type, the statement creates an array of 10 elements, each of which is initialized to a null reference. In both instances, the elements are initialized to the default value for the element type. For more information about value types and reference types, see [Value types](../../language-reference/builtin-types/value-types.md) and [Reference types](../../language-reference/keywords/reference-types.md). + +## Retreving data from Array + +You can retrieve the data of an array by use an index. For example: + +:::code language="csharp" source="snippets/RetrevingArrayElements.cs" id="RetrevingDataArray" interactive="try-dotnet-method"::: ## See also diff --git a/docs/csharp/programming-guide/arrays/snippets/RetrevingArrayElements.cs b/docs/csharp/programming-guide/arrays/snippets/RetrevingArrayElements.cs new file mode 100644 index 0000000000000..ce0c012fb7385 --- /dev/null +++ b/docs/csharp/programming-guide/arrays/snippets/RetrevingArrayElements.cs @@ -0,0 +1,39 @@ +using System; +using System.Collections.Generic; +using System.Text; + +namespace arrays +{ + public class RetrevingArrayElements + { + public static void Examples() + { + Retreving(); + } + + private static void Retreving() + { + // + string[] weekDays2 = { "Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat" }; + + Console.WriteLine(weekDays2[0]); + Console.WriteLine(weekDays2[1]); + Console.WriteLine(weekDays2[2]); + Console.WriteLine(weekDays2[3]); + Console.WriteLine(weekDays2[4]); + Console.WriteLine(weekDays2[5]); + Console.WriteLine(weekDays2[6]); + + /*Output: + Sun + Mon + Tue + Wed + Thu + Fri + Sat + */ + // + } + } +} From 36e7991d153f2a750801f6ade6952dbaa73773b7 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 6 Jul 2021 14:05:26 -0400 Subject: [PATCH 19/27] initial docs on async method builders (#24973) Add and update the description of AsyncMethodBuilder, and the new feature that it can be applied to a method. --- .../language-reference/attributes/general.md | 81 ++++++++++++++----- .../concepts/async/async-return-types.md | 28 ++++--- 2 files changed, 78 insertions(+), 31 deletions(-) diff --git a/docs/csharp/language-reference/attributes/general.md b/docs/csharp/language-reference/attributes/general.md index 0eb6d32d2418f..4e99b4c3cd177 100644 --- a/docs/csharp/language-reference/attributes/general.md +++ b/docs/csharp/language-reference/attributes/general.md @@ -1,6 +1,6 @@ --- title: "C# reserved attributes: Miscellaneous" -ms.date: 03/18/2021 +ms.date: 07/02/2021 description: "Learn about attributes that affect code generated by the compiler: the Conditional, Obsolete, AttributeUsage, ModuleInitializer, and SkipLocalsInit attributes." --- # Reserved attributes: Miscellaneous @@ -19,33 +19,33 @@ If the `TRACE_ON` identifier isn't defined, the trace output isn't displayed. Ex The `Conditional` attribute is often used with the `DEBUG` identifier to enable trace and logging features for debug builds but not in release builds, as shown in the following example: -:::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetConditional" ::: +:::code language="csharp" source="snippets/ConditionalExamples.cs" ID="SnippetConditional" ::: -When a method marked conditional is called, the presence or absence of the specified preprocessing symbol determines whether the call is included or omitted. If the symbol is defined, the call is included; otherwise, the call is omitted. A conditional method must be a method in a class or struct declaration and must have a `void` return type. Using `Conditional` is cleaner, more elegant, and less error-prone than enclosing methods inside `#if…#endif` blocks. +When a method marked conditional is called, the presence or absence of the specified preprocessing symbol determines whether the compiler includes or omits calls to the method. If the symbol is defined, the call is included; otherwise, the call is omitted. A conditional method must be a method in a class or struct declaration and must have a `void` return type. Using `Conditional` is cleaner, more elegant, and less error-prone than enclosing methods inside `#if…#endif` blocks. -If a method has multiple `Conditional` attributes, a call to the method is included if at one or more conditional symbols is defined (the symbols are logically linked together by using the OR operator). In the following example, the presence of either `A` or `B` results in a method call: +If a method has multiple `Conditional` attributes, compiler includes calls to the method if one or more conditional symbols are defined (the symbols are logically linked together by using the OR operator). In the following example, the presence of either `A` or `B` results in a method call: -:::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetMultipleConditions" ::: +:::code language="csharp" source="snippets/ConditionalExamples.cs" ID="SnippetMultipleConditions" ::: ### Using `Conditional` with attribute classes The `Conditional` attribute can also be applied to an attribute class definition. In the following example, the custom attribute `Documentation` will only add information to the metadata if `DEBUG` is defined. -:::code language="csharp" source="snippets/ConditionalExamples.cs" id="SnippetConditionalConditionalAttribute" ::: +:::code language="csharp" source="snippets/ConditionalExamples.cs" ID="SnippetConditionalConditionalAttribute" ::: ## `Obsolete` attribute The `Obsolete` attribute marks a code element as no longer recommended for use. Use of an entity marked obsolete generates a warning or an error. The `Obsolete` attribute is a single-use attribute and can be applied to any entity that allows attributes. `Obsolete` is an alias for . -In the following example the `Obsolete` attribute is applied to class `A` and to method `B.OldMethod`. Because the second argument of the attribute constructor applied to `B.OldMethod` is set to `true`, this method will cause a compiler error, whereas using class `A` will just produce a warning. Calling `B.NewMethod`, however, produces no warning or error. For example, when you use it with the previous definitions, the following code generates two warnings and one error: +In the following example, the `Obsolete` attribute is applied to class `A` and to method `B.OldMethod`. Because the second argument of the attribute constructor applied to `B.OldMethod` is set to `true`, this method will cause a compiler error, whereas using class `A` will just produce a warning. Calling `B.NewMethod`, however, produces no warning or error. For example, when you use it with the previous definitions, the following code generates two warnings and one error: -:::code language="csharp" source="snippets/ObsoleteExample.cs" id="Snippet1" interactive="try-dotnet" ::: +:::code language="csharp" source="snippets/ObsoleteExample.cs" ID="Snippet1" interactive="try-dotnet" ::: The string provided as the first argument to the attribute constructor will be displayed as part of the warning or error. Two warnings for class `A` are generated: one for the declaration of the class reference, and one for the class constructor. The `Obsolete` attribute can be used without arguments, but including an explanation what to use instead is recommended. In C# 10, you can use constant string interpolation and the `nameof` operator to ensure the names match: -:::code language="csharp" source="snippets/ObsoleteExample.cs" id="Snippet2" ::: +:::code language="csharp" source="snippets/ObsoleteExample.cs" ID="Snippet2" ::: ## `AttributeUsage` attribute @@ -66,36 +66,81 @@ The `AttributeUsage` attribute determines how a custom attribute class can be us The default settings look like the following example when applied explicitly: -:::code language="csharp" source="snippets/NewAttribute.cs" id="SnippetUsageFirst" ::: +:::code language="csharp" source="snippets/NewAttribute.cs" ID="SnippetUsageFirst" ::: In this example, the `NewAttribute` class can be applied to any supported program element. But it can be applied only once to each entity. The attribute is inherited by derived classes when applied to a base class. The and arguments are optional, so the following code has the same effect: -:::code language="csharp" source="snippets/NewAttribute.cs" id="SnippetUsageSecond" ::: +:::code language="csharp" source="snippets/NewAttribute.cs" ID="SnippetUsageSecond" ::: The first argument must be one or more elements of the enumeration. Multiple target types can be linked together with the OR operator, like the following example shows: -:::code language="csharp" source="snippets/NewPropertyOrFieldAttribute.cs" id="SnippetDefinePropertyAttribute" ::: +:::code language="csharp" source="snippets/NewPropertyOrFieldAttribute.cs" ID="SnippetDefinePropertyAttribute" ::: Beginning in C# 7.3, attributes can be applied to either the property or the backing field for an auto-implemented property. The attribute applies to the property, unless you specify the `field` specifier on the attribute. Both are shown in the following example: -:::code language="csharp" source="snippets/NewPropertyOrFieldAttribute.cs" id="SnippetUsePropertyAttribute" ::: +:::code language="csharp" source="snippets/NewPropertyOrFieldAttribute.cs" ID="SnippetUsePropertyAttribute" ::: If the argument is `true`, then the resulting attribute can be applied more than once to a single entity, as shown in the following example: -:::code language="csharp" source="snippets/MultiUseAttribute.cs" id="SnippetMultiUse" ::: +:::code language="csharp" source="snippets/MultiUseAttribute.cs" ID="SnippetMultiUse" ::: In this case, `MultiUseAttribute` can be applied repeatedly because `AllowMultiple` is set to `true`. Both formats shown for applying multiple attributes are valid. If is `false`, then the attribute isn't inherited by classes derived from an attributed class. For example: -:::code language="csharp" source="snippets/NonInheritedAttribute.cs" id="SnippetNonInherited" ::: +:::code language="csharp" source="snippets/NonInheritedAttribute.cs" ID="SnippetNonInherited" ::: In this case `NonInheritedAttribute` isn't applied to `DClass` via inheritance. You can also use these keywords to specify where an attribute should be applied. For example, you can use the `field:` specifier to add an attribute to the backing field of an [auto-implemented property](../../programming-guide/classes-and-structs/properties.md#auto-implemented-properties). Or you can use the `field:`, `property:` or `param:` specifier to apply an attribute to any of the elements generated from a positional record. For an example, see [Positional syntax for property definition](../builtin-types/record.md#positional-syntax-for-property-definition). +## `AsyncMethodBuilder` attribute + +Beginning with C# 7, you add the attribute to a type that can be an async return type. The attribute specifies the type that builds the async method implementation when the specified type is returned from an async method. The `AsyncMethodBuilder` attribute can be applied to a type that: + +* Has an accessible `GetAwaiter` method. +* The object returned by the `GetAwaiter` method implements the interface. + +The constructor to the `AsyncMethodBuilder` attribute specifies the type of the associated builder. The builder must implement the following accessible members: + +* a static `Create()` method that returns the type of the builder. +* a readable `Task` property that returns the async return type. +* a `void SetException(Exception)` method that sets the exception when a task faults. +* a `void SetResult()` or `void SetResult(T result)` method that marks the task as completed and optionally sets the task's result +* a `Start` method with the following API signature: + + ```csharp + void Start(ref TStateMachine stateMachine) + where TStateMachine : System.Runtime.CompilerServices.IAsyncStateMachine + ``` + +* An `AwaitOnCompleted` method with the following signature: + + ```csharp + public void AwaitOnCompleted(ref TAwaiter awaiter, ref TStateMachine stateMachine) + where TAwaiter : System.Runtime.CompilerServices.INotifyCompletion + where TStateMachine : System.Runtime.CompilerServices.IAsyncStateMachine + ``` + +* An `AwaitUnsafeOnCompleted` method with the following signature: + + ```csharp + public void AwaitUnsafeOnCompleted(ref TAwaiter awaiter, ref TStateMachine stateMachine) + where TAwaiter : System.Runtime.CompilerServices.ICriticalNotifyCompletion + where TStateMachine : System.Runtime.CompilerServices.IAsyncStateMachine + ``` + +You can learn about async method builders by reading about the following builders supplied by .NET: + +- +- +- +- + +In C# 10.0 and later, the `AsyncMethodBuilder` attribute can be applied to an async method to override the builder for that type. + ## `ModuleInitializer` attribute Starting with C# 9, the `ModuleInitializer` attribute marks a method that the runtime calls when the assembly loads. `ModuleInitializer` is an alias for . @@ -118,19 +163,19 @@ The following example illustrates use of multiple module initializer methods. Th :::code language="csharp" source="snippets/ModuleInitializerExampleModule.cs" ::: -Source code generators sometimes need to generate initialization code. Module initializers provide a standard place for that code to reside. +Source code generators sometimes need to generate initialization code. Module initializers provide a standard place for that code. ## `SkipLocalsInit` attribute Starting in C# 9, the `SkipLocalsInit` attribute prevents the compiler from setting the `.locals init` flag when emitting to metadata. The `SkipLocalsInit` attribute is a single-use attribute and can be applied to a method, a property, a class, a struct, an interface, or a module, but not to an assembly. `SkipLocalsInit` is an alias for . -The `.locals init` flag causes the CLR to initialize all of the local variables declared in a method to their default values. Since the compiler also makes sure that you never use a variable before assigning some value to it, `.locals init` is typically not necessary. However, the extra zero-initialization may have measurable performance impact in some scenarios, such as when you use [stackalloc](../operators/stackalloc.md) to allocate an array on the stack. In those cases, you can add the `SkipLocalsInit` attribute. If applied to a method directly, the attribute affects that method and all its nested functions, including lambdas and local functions. If applied to a type or module, it affects all methods nested inside. This attribute does not affect abstract methods, but it does affect code generated for the implementation. +The `.locals init` flag causes the CLR to initialize all of the local variables declared in a method to their default values. Since the compiler also makes sure that you never use a variable before assigning some value to it, `.locals init` is typically not necessary. However, the extra zero-initialization may have measurable performance impact in some scenarios, such as when you use [stackalloc](../operators/stackalloc.md) to allocate an array on the stack. In those cases, you can add the `SkipLocalsInit` attribute. If applied to a method directly, the attribute affects that method and all its nested functions, including lambdas and local functions. If applied to a type or module, it affects all methods nested inside. This attribute doesn't affect abstract methods, but it does affect code generated for the implementation. This attribute requires the [AllowUnsafeBlocks](../compiler-options/language.md#allowunsafeblocks) compiler option. This is to signal that in some cases code could view unassigned memory (for example, reading from uninitialized stack-allocated memory). The following example illustrates the effect of `SkipLocalsInit` attribute on a method that uses `stackalloc`. The method displays whatever was in memory when the array of integers was allocated. -:::code language="csharp" source="snippets/SkipLocalsInitExample.cs" id="ReadUninitializedMemory"::: +:::code language="csharp" source="snippets/SkipLocalsInitExample.cs" ID="ReadUninitializedMemory"::: To try this code yourself, set the `AllowUnsafeBlocks` compiler option in your *.csproj* file: diff --git a/docs/csharp/programming-guide/concepts/async/async-return-types.md b/docs/csharp/programming-guide/concepts/async/async-return-types.md index a4243d33398bd..d602d83d39a12 100644 --- a/docs/csharp/programming-guide/concepts/async/async-return-types.md +++ b/docs/csharp/programming-guide/concepts/async/async-return-types.md @@ -1,7 +1,7 @@ --- title: Async return types (C#) -description: Learn about the return types that async methods can have in C# with code examples for each type and additional resources. -ms.date: 08/19/2020 +description: Learn about the return types that async methods can have in C# with code examples for each type. +ms.date: 07/02/2021 ms.assetid: ddb2539c-c898-48c1-ad92-245e4a996df8 --- @@ -20,8 +20,8 @@ For more information about async methods, see [Asynchronous programming with asy Several other types also exist that are specific to Windows workloads: - , for async operations limited to Windows. -- , for async actions in UWP that do not return a value. -- , for async actions in UWP that report progress but do not return a value. +- , for async actions in UWP that don't return a value. +- , for async actions in UWP that report progress but don't return a value. - , for async operations in UWP that return a value. - , for async operations in UWP that report progress and return a value. @@ -31,7 +31,7 @@ Async methods that don't contain a `return` statement or that contain a `return` In the following example, the `WaitAndApologizeAsync` method doesn't contain a `return` statement, so the method returns a object. Returning a `Task` enables `WaitAndApologizeAsync` to be awaited. The type doesn't include a `Result` property because it has no return value. -:::code language="csharp" source="snippets/async-return-types/async-returns2.cs" id="TaskReturn"::: +:::code language="csharp" source="snippets/async-return-types/async-returns2.cs" ID="TaskReturn"::: `WaitAndApologizeAsync` is awaited by using an await statement instead of an await expression, similar to the calling statement for a synchronous void-returning method. The application of an await operator in this case doesn't produce a value. When the right operand of an `await` is a , the `await` expression produces a result of `T`. When the right operand of an `await` is a , the `await` and its operand are a statement. @@ -39,15 +39,15 @@ You can separate the call to `WaitAndApologizeAsync` from the application of an The following code separates calling the `WaitAndApologizeAsync` method from awaiting the task that the method returns. -:::code language="csharp" source="snippets/async-return-types/async-returns2a.cs" id="AwaitTask"::: +:::code language="csharp" source="snippets/async-return-types/async-returns2a.cs" ID="AwaitTask"::: ## Task\ return type The return type is used for an async method that contains a [return](../../../language-reference/keywords/return.md) statement in which the operand is `TResult`. -In the following example, the `GetLeisureHoursAsync` method contains a `return` statement that returns an integer. Therefore, the method declaration must specify a return type of `Task`. The async method is a placeholder for an operation that returns a . +In the following example, the `GetLeisureHoursAsync` method contains a `return` statement that returns an integer. The method declaration must specify a return type of `Task`. The async method is a placeholder for an operation that returns a . -:::code language="csharp" source="snippets/async-return-types/async-returns1.cs" id="LeisureHours"::: +:::code language="csharp" source="snippets/async-return-types/async-returns1.cs" ID="LeisureHours"::: When `GetLeisureHoursAsync` is called from within an await expression in the `ShowTodaysInfo` method, the await expression retrieves the integer value (the value of `leisureHours`) that's stored in the task returned by the `GetLeisureHours` method. For more information about await expressions, see [await](../../../language-reference/operators/await.md). @@ -58,13 +58,13 @@ You can better understand how `await` retrieves the result from a `Task` by s > > The previous example retrieved the value of the property to block the main thread so that the `Main` method could print the `message` to the console before the application ended. -:::code language="csharp" source="snippets/async-return-types/async-returns1a.cs" id="StoreTask"::: +:::code language="csharp" source="snippets/async-return-types/async-returns1a.cs" ID="StoreTask"::: ## Void return type You use the `void` return type in asynchronous event handlers, which require a `void` return type. For methods other than event handlers that don't return a value, you should return a instead, because an async method that returns `void` can't be awaited. Any caller of such a method must continue to completion without waiting for the called async method to finish. The caller must be independent of any values or exceptions that the async method generates. -The caller of a void-returning async method can't catch exceptions thrown from the method, and such unhandled exceptions are likely to cause your application to fail. If a method that returns a or throws an exception, the exception is stored in the returned task. The exception is rethrown when the task is awaited. Therefore, make sure that any async method that can produce an exception has a return type of or and that calls to the method are awaited. +The caller of a void-returning async method can't catch exceptions thrown from the method. Such unhandled exceptions are likely to cause your application to fail. If a method that returns a or throws an exception, the exception is stored in the returned task. The exception is rethrown when the task is awaited. Make sure that any async method that can produce an exception has a return type of or and that calls to the method are awaited. For more information about how to catch exceptions in async methods, see the [Exceptions in async methods](../../../language-reference/keywords/try-catch.md#exceptions-in-async-methods) section of the [try-catch](../../../language-reference/keywords/try-catch.md) article. @@ -74,7 +74,7 @@ The following example shows the behavior of an async event handler. In the examp ## Generalized async return types and ValueTask\ -Starting with C# 7.0, an async method can return any type that has an accessible `GetAwaiter` method that returns an instance of an *awaiter type*. In addition, the type returned from the `GetAwaiter` method must have the attribute. You can learn more in the feature spec for [Task like return types](~/_csharplang/proposals/csharp-7.0/task-types.md). +Starting with C# 7.0, an async method can return any type that has an accessible `GetAwaiter` method that returns an instance of an *awaiter type*. In addition, the type returned from the `GetAwaiter` method must have the attribute. You can learn more in the article on [Attributes read by the compiler](../../../language-reference/attributes/general.md#asyncmethodbuilder-attribute) or the feature spec for [Task like return types](~/_csharplang/proposals/csharp-7.0/task-types.md). This feature is the complement to [awaitable expressions](~/_csharplang/spec/expressions.md#awaitable-expressions), which describes the requirements for the operand of `await`. Generalized async return types enable the compiler to generate `async` methods that return different types. Generalized async return types enabled performance improvements in the .NET libraries. Because and are reference types, memory allocation in performance-critical paths, particularly when allocations occur in tight loops, can adversely affect performance. Support for generalized return types means that you can return a lightweight value type instead of a reference type to avoid additional memory allocations. @@ -82,13 +82,15 @@ This feature is the complement to [awaitable expressions](~/_csharplang/spec/exp :::code language="csharp" source="snippets/async-return-types/async-valuetask.cs"::: -Writing a generalized async return type is an advanced scenario, and is targeted for use in very specific environments. Consider using the `Task`, `Task` and `ValueTask` types instead, which cover most scenarios for asynchronous code. +Writing a generalized async return type is an advanced scenario, and is targeted for use in specialized environments. Consider using the `Task`, `Task`, and `ValueTask` types instead, which cover most scenarios for asynchronous code. + +In C# 10.0 and later, you can apply the `AsyncMethodBuilder` attribute to an async method (instead of the async return type declaration) to override the builder for that type. Typically you'd apply this attribute to use a different builder provided in the .NET runtime. ## Async streams with IAsyncEnumerable\ Starting with C# 8.0, an async method may return an *async stream*, represented by . An async stream provides a way to enumerate items read from a stream when elements are generated in chunks with repeated asynchronous calls. The following example shows an async method that generates an async stream: -:::code language="csharp" source="snippets/async-return-types/AsyncStreams.cs" id="GenerateAsyncStream"::: +:::code language="csharp" source="snippets/async-return-types/AsyncStreams.cs" ID="GenerateAsyncStream"::: The preceding example reads lines from a string asynchronously. Once each line is read, the code enumerates each word in the string. Callers would enumerate each word using the `await foreach` statement. The method awaits when it needs to asynchronously read the next line from the source string. From f4489ec3366cce2c4808691c699e012bd4d9657d Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 6 Jul 2021 14:12:23 -0400 Subject: [PATCH 20/27] promote the standard in TOC (#24974) * promote the standard in TOC Fixes #24959 * breadcrumb and parent node - update the breadcrumb config - add "specifications" parent node. * use single C# TOC * typo in folder names * one more time. * fix nit on "specification" Many of the feature proposals aren't labeled internally as a "specification". --- docs/breadcrumb/toc.yml | 21 ++- .../language-reference/proposals/toc.yml | 124 ------------- .../language-reference/specification/toc.yml | 40 ----- docs/csharp/toc.yml | 168 +++++++++++++++++- 4 files changed, 178 insertions(+), 175 deletions(-) delete mode 100644 docs/csharp/language-reference/proposals/toc.yml delete mode 100644 docs/csharp/language-reference/specification/toc.yml diff --git a/docs/breadcrumb/toc.yml b/docs/breadcrumb/toc.yml index 1007639f17901..53bfa65c597a3 100644 --- a/docs/breadcrumb/toc.yml +++ b/docs/breadcrumb/toc.yml @@ -439,27 +439,32 @@ items: - name: Compiler messages tocHref: /dotnet/csharp/language-reference/compiler-messages/ topicHref: /dotnet/csharp/language-reference/compiler-messages/index + - name: Compiler messages + tocHref: /dotnet/csharp/misc + topicHref: /dotnet/csharp/language-reference/compiler-messages/index + - name: Specification + items: - name: C# 6.0 draft specification tocHref: /dotnet/csharp/language-reference/language-specification/ topicHref: /dotnet/csharp/language-reference/language-specification/index - - name: C# 7.0 language proposals + - name: C# 7.0 feature specifications tocHref: /dotnet/csharp/language-reference/proposals/csharp-7.0/ topicHref: /dotnet/csharp/language-reference/proposals/csharp-7.0/index - - name: C# 7.1 language proposals + - name: C# 7.1 feature specifications tocHref: /dotnet/csharp/language-reference/proposals/csharp-7.1/ topicHref: /dotnet/csharp/language-reference/proposals/csharp-7.1/index - - name: C# 7.2 language proposals + - name: C# 7.2 feature specifications tocHref: /dotnet/csharp/language-reference/proposals/csharp-7.2/ topicHref: /dotnet/csharp/language-reference/proposals/csharp-7.2/index - - name: C# 7.3 language proposals + - name: C# 7.3 feature specifications tocHref: /dotnet/csharp/language-reference/proposals/csharp-7.3/ topicHref: /dotnet/csharp/language-reference/proposals/csharp-7.3/index - - name: C# 8.0 language proposals + - name: C# 8.0 feature specifications tocHref: /dotnet/csharp/language-reference/proposals/csharp-8.0/ topicHref: /dotnet/csharp/language-reference/proposals/csharp-8.0/index - - name: Compiler messages - tocHref: /dotnet/csharp/misc - topicHref: /dotnet/csharp/language-reference/compiler-messages/index + - name: C# 9.0 feature specifications + tocHref: /dotnet/csharp/language-reference/proposals/csharp-9.0/ + topicHref: /dotnet/csharp/language-reference/proposals/csharp-9.0/index - name: F# guide tocHref: /dotnet/fsharp/ topicHref: /dotnet/fsharp/index diff --git a/docs/csharp/language-reference/proposals/toc.yml b/docs/csharp/language-reference/proposals/toc.yml deleted file mode 100644 index f964accd0cc00..0000000000000 --- a/docs/csharp/language-reference/proposals/toc.yml +++ /dev/null @@ -1,124 +0,0 @@ -- name: Latest feature specifications - items: - - name: C# 7.0 specification proposals - items: - - name: Pattern matching - href: ../../../../_csharplang/proposals/csharp-7.0/pattern-matching.md - - name: Local functions - href: ../../../../_csharplang/proposals/csharp-7.0/local-functions.md - - name: Out variable declarations - href: ../../../../_csharplang/proposals/csharp-7.0/out-var.md - - name: Throw expressions - href: ../../../../_csharplang/proposals/csharp-7.0/throw-expression.md - - name: Binary literals - href: ../../../../_csharplang/proposals/csharp-7.0/binary-literals.md - - name: Digit separators - href: ../../../../_csharplang/proposals/csharp-7.0/digit-separators.md - - name: Async task types - href: ../../../../_csharplang/proposals/csharp-7.0/task-types.md - - name: C# 7.1 specification proposals - items: - - name: Async main method - href: ../../../../_csharplang/proposals/csharp-7.1/async-main.md - - name: Default expressions - href: ../../../../_csharplang/proposals/csharp-7.1/target-typed-default.md - - name: Infer tuple names - href: ../../../../_csharplang/proposals/csharp-7.1/infer-tuple-names.md - - name: Pattern matching with generics - href: ../../../../_csharplang/proposals/csharp-7.1/generics-pattern-match.md - - name: C# 7.2 specification proposals - items: - - name: Readonly references - href: ../../../../_csharplang/proposals/csharp-7.2/readonly-ref.md - - name: Compile-time safety for ref-like types - href: ../../../../_csharplang/proposals/csharp-7.2/span-safety.md - - name: Non-trailing named arguments - href: ../../../../_csharplang/proposals/csharp-7.2/non-trailing-named-arguments.md - - name: Private protected - href: ../../../../_csharplang/proposals/csharp-7.2/private-protected.md - - name: Conditional ref - href: ../../../../_csharplang/proposals/csharp-7.2/conditional-ref.md - - name: Leading digit separator - href: ../../../../_csharplang/proposals/csharp-7.2/leading-separator.md - - name: C# 7.3 specification proposals - items: - - name: Unmanaged generic type constraints - href: ../../../../_csharplang/proposals/csharp-7.3/blittable.md - - name: Indexing `fixed` fields should not require pinning regardless of the movable/unmovable context - href: ../../../../_csharplang/proposals/csharp-7.3/indexing-movable-fixed-fields.md - - name: Pattern-based `fixed` statement - href: ../../../../_csharplang/proposals/csharp-7.3/pattern-based-fixed.md - - name: Ref local reassignment - href: ../../../../_csharplang/proposals/csharp-7.3/ref-local-reassignment.md - - name: Stackalloc array initializers - href: ../../../../_csharplang/proposals/csharp-7.3/stackalloc-array-initializers.md - - name: Auto-implemented property field-targeted attributes - href: ../../../../_csharplang/proposals/csharp-7.3/auto-prop-field-attrs.md - - name: Expression variables in initializers - href: ../../../../_csharplang/proposals/csharp-7.3/expression-variables-in-initializers.md - - name: Tuple equality (==) and inequality (!=) - href: ../../../../_csharplang/proposals/csharp-7.3/tuple-equality.md - - name: Improved overload candidates - href: ../../../../_csharplang/proposals/csharp-7.3/improved-overload-candidates.md - - name: C# 8.0 specification proposal - items: - - name: Nullable reference types - proposal - href: ../../../../_csharplang/proposals/csharp-8.0/nullable-reference-types.md - - name: Nullable reference types - specification - href: ../../../../_csharplang/proposals/csharp-9.0/nullable-reference-types-specification.md - - name: Recursive pattern matching - href: ../../../../_csharplang/proposals/csharp-8.0/patterns.md - - name: Default interface methods - href: ../../../../_csharplang/proposals/csharp-8.0/default-interface-methods.md - - name: Async streams - href: ../../../../_csharplang/proposals/csharp-8.0/async-streams.md - - name: Ranges - href: ../../../../_csharplang/proposals/csharp-8.0/ranges.md - - name: Pattern based using and using declarations - href: ../../../../_csharplang/proposals/csharp-8.0/using.md - - name: Static local functions - href: ../../../../_csharplang/proposals/csharp-8.0/static-local-functions.md - - name: Null coalescing assignment - href: ../../../../_csharplang/proposals/csharp-8.0/null-coalescing-assignment.md - - name: Readonly instance members - href: ../../../../_csharplang/proposals/csharp-8.0/readonly-instance-members.md - - name: Nested stackalloc - href: ../../../../_csharplang/proposals/csharp-8.0/nested-stackalloc.md - - name: C# 9.0 specification proposal - items: - - name: Records - href: ../../../../_csharplang/proposals/csharp-9.0/records.md - - name: Top-level statements - href: ../../../../_csharplang/proposals/csharp-9.0/top-level-statements.md - - name: Nullable reference types - specification - href: ../../../../_csharplang/proposals/csharp-9.0/nullable-reference-types-specification.md - - name: Pattern matching enhancements - href: ../../../../_csharplang/proposals/csharp-9.0/patterns3.md - - name: Init only setters - href: ../../../../_csharplang/proposals/csharp-9.0/init.md - - name: Target-typed new expressions - href: ../../../../_csharplang/proposals/csharp-9.0/target-typed-new.md - - name: Module initializers - href: ../../../../_csharplang/proposals/csharp-9.0/module-initializers.md - - name: Extending partial methods - href: ../../../../_csharplang/proposals/csharp-9.0/extending-partial-methods.md - - name: Static anonymous functions - href: ../../../../_csharplang/proposals/csharp-9.0/static-anonymous-functions.md - - name: Target-typed conditional expression - href: ../../../../_csharplang/proposals/csharp-9.0/target-typed-conditional-expression.md - - name: Covariant return types - href: ../../../../_csharplang/proposals/csharp-9.0/covariant-returns.md - - name: Extension GetEnumerator in foreach loops - href: ../../../../_csharplang/proposals/csharp-9.0/extension-getenumerator.md - - name: Lambda discard parameters - href: ../../../../_csharplang/proposals/csharp-9.0/lambda-discard-parameters.md - - name: Attributes on local functions - href: ../../../../_csharplang/proposals/csharp-9.0/local-function-attributes.md - - name: Native sized integers - href: ../../../../_csharplang/proposals/csharp-9.0/native-integers.md - - name: Function pointers - href: ../../../../_csharplang/proposals/csharp-9.0/function-pointers.md - - name: Suppress emitting localsinit flag - href: ../../../../_csharplang/proposals/csharp-9.0/skip-localsinit.md - - name: Unconstrained type parameter annotations - href: ../../../../_csharplang/proposals/csharp-9.0/unconstrained-type-parameter-annotations.md diff --git a/docs/csharp/language-reference/specification/toc.yml b/docs/csharp/language-reference/specification/toc.yml deleted file mode 100644 index 972c339d70fbc..0000000000000 --- a/docs/csharp/language-reference/specification/toc.yml +++ /dev/null @@ -1,40 +0,0 @@ -- name: C# 6.0 Draft Specification - items: - - name: Introduction - href: ../../../../_csharplang/spec/introduction.md - - name: Lexical structure - href: ../../../../_csharplang/spec/lexical-structure.md - - name: Basic concepts - href: ../../../../_csharplang/spec/basic-concepts.md - - name: Types - href: ../../../../_csharplang/spec/types.md - - name: Variables - href: ../../../../_csharplang/spec/variables.md - - name: Conversions - href: ../../../../_csharplang/spec/conversions.md - - name: Expressions - href: ../../../../_csharplang/spec/expressions.md - - name: Statements - href: ../../../../_csharplang/spec/statements.md - - name: Namespaces - href: ../../../../_csharplang/spec/namespaces.md - - name: Classes - href: ../../../../_csharplang/spec/classes.md - - name: Structs - href: ../../../../_csharplang/spec/structs.md - - name: Arrays - href: ../../../../_csharplang/spec/arrays.md - - name: Interfaces - href: ../../../../_csharplang/spec/interfaces.md - - name: Enums - href: ../../../../_csharplang/spec/enums.md - - name: Delegates - href: ../../../../_csharplang/spec/delegates.md - - name: Exceptions - href: ../../../../_csharplang/spec/exceptions.md - - name: Attributes - href: ../../../../_csharplang/spec/attributes.md - - name: Unsafe code - href: ../../../../_csharplang/spec/unsafe-code.md - - name: Documentation comments - href: ../../../../_csharplang/spec/documentation-comments.md diff --git a/docs/csharp/toc.yml b/docs/csharp/toc.yml index 15b703881c856..b9ded54fd57bd 100644 --- a/docs/csharp/toc.yml +++ b/docs/csharp/toc.yml @@ -1355,7 +1355,169 @@ items: href: language-reference/compiler-options/advanced.md - name: Compiler messages href: language-reference/compiler-messages/index.md +- name: Specifications + items: - name: C# 6.0 draft specification - href: language-reference/specification/ - - name: C# 7.0 - 9.0 proposals - href: language-reference/proposals/ + items: + - name: Introduction + href: ../../_csharplang/spec/introduction.md + - name: Lexical structure + href: ../../_csharplang/spec/lexical-structure.md + - name: Basic concepts + href: ../../_csharplang/spec/basic-concepts.md + - name: Types + href: ../../_csharplang/spec/types.md + - name: Variables + href: ../../_csharplang/spec/variables.md + - name: Conversions + href: ../../_csharplang/spec/conversions.md + - name: Expressions + href: ../../_csharplang/spec/expressions.md + - name: Statements + href: ../../_csharplang/spec/statements.md + - name: Namespaces + href: ../../_csharplang/spec/namespaces.md + - name: Classes + href: ../../_csharplang/spec/classes.md + - name: Structs + href: ../../_csharplang/spec/structs.md + - name: Arrays + href: ../../_csharplang/spec/arrays.md + - name: Interfaces + href: ../../_csharplang/spec/interfaces.md + - name: Enums + href: ../../_csharplang/spec/enums.md + - name: Delegates + href: ../../_csharplang/spec/delegates.md + - name: Exceptions + href: ../../_csharplang/spec/exceptions.md + - name: Attributes + href: ../../_csharplang/spec/attributes.md + - name: Unsafe code + href: ../../_csharplang/spec/unsafe-code.md + - name: Documentation comments + href: ../../_csharplang/spec/documentation-comments.md + - name: C# 7.0 - 9.0 features + items: + - name: C# 7.0 features + items: + - name: Pattern matching + href: ../../_csharplang/proposals/csharp-7.0/pattern-matching.md + - name: Local functions + href: ../../_csharplang/proposals/csharp-7.0/local-functions.md + - name: Out variable declarations + href: ../../_csharplang/proposals/csharp-7.0/out-var.md + - name: Throw expressions + href: ../../_csharplang/proposals/csharp-7.0/throw-expression.md + - name: Binary literals + href: ../../_csharplang/proposals/csharp-7.0/binary-literals.md + - name: Digit separators + href: ../../_csharplang/proposals/csharp-7.0/digit-separators.md + - name: Async task types + href: ../../_csharplang/proposals/csharp-7.0/task-types.md + - name: C# 7.1 features + items: + - name: Async main method + href: ../../_csharplang/proposals/csharp-7.1/async-main.md + - name: Default expressions + href: ../../_csharplang/proposals/csharp-7.1/target-typed-default.md + - name: Infer tuple names + href: ../../_csharplang/proposals/csharp-7.1/infer-tuple-names.md + - name: Pattern matching with generics + href: ../../_csharplang/proposals/csharp-7.1/generics-pattern-match.md + - name: C# 7.2 features + items: + - name: Readonly references + href: ../../_csharplang/proposals/csharp-7.2/readonly-ref.md + - name: Compile-time safety for ref-like types + href: ../../_csharplang/proposals/csharp-7.2/span-safety.md + - name: Non-trailing named arguments + href: ../../_csharplang/proposals/csharp-7.2/non-trailing-named-arguments.md + - name: Private protected + href: ../../_csharplang/proposals/csharp-7.2/private-protected.md + - name: Conditional ref + href: ../../_csharplang/proposals/csharp-7.2/conditional-ref.md + - name: Leading digit separator + href: ../../_csharplang/proposals/csharp-7.2/leading-separator.md + - name: C# 7.3 features + items: + - name: Unmanaged generic type constraints + href: ../../_csharplang/proposals/csharp-7.3/blittable.md + - name: Indexing `fixed` fields should not require pinning regardless of the movable/unmovable context + href: ../../_csharplang/proposals/csharp-7.3/indexing-movable-fixed-fields.md + - name: Pattern-based `fixed` statement + href: ../../_csharplang/proposals/csharp-7.3/pattern-based-fixed.md + - name: Ref local reassignment + href: ../../_csharplang/proposals/csharp-7.3/ref-local-reassignment.md + - name: Stackalloc array initializers + href: ../../_csharplang/proposals/csharp-7.3/stackalloc-array-initializers.md + - name: Auto-implemented property field-targeted attributes + href: ../../_csharplang/proposals/csharp-7.3/auto-prop-field-attrs.md + - name: Expression variables in initializers + href: ../../_csharplang/proposals/csharp-7.3/expression-variables-in-initializers.md + - name: Tuple equality (==) and inequality (!=) + href: ../../_csharplang/proposals/csharp-7.3/tuple-equality.md + - name: Improved overload candidates + href: ../../_csharplang/proposals/csharp-7.3/improved-overload-candidates.md + - name: C# 8.0 features + items: + - name: Nullable reference types - proposal + href: ../../_csharplang/proposals/csharp-8.0/nullable-reference-types.md + - name: Nullable reference types - specification + href: ../../_csharplang/proposals/csharp-9.0/nullable-reference-types-specification.md + - name: Recursive pattern matching + href: ../../_csharplang/proposals/csharp-8.0/patterns.md + - name: Default interface methods + href: ../../_csharplang/proposals/csharp-8.0/default-interface-methods.md + - name: Async streams + href: ../../_csharplang/proposals/csharp-8.0/async-streams.md + - name: Ranges + href: ../../_csharplang/proposals/csharp-8.0/ranges.md + - name: Pattern based using and using declarations + href: ../../_csharplang/proposals/csharp-8.0/using.md + - name: Static local functions + href: ../../_csharplang/proposals/csharp-8.0/static-local-functions.md + - name: Null coalescing assignment + href: ../../_csharplang/proposals/csharp-8.0/null-coalescing-assignment.md + - name: Readonly instance members + href: ../../_csharplang/proposals/csharp-8.0/readonly-instance-members.md + - name: Nested stackalloc + href: ../../_csharplang/proposals/csharp-8.0/nested-stackalloc.md + - name: C# 9.0 features + items: + - name: Records + href: ../../_csharplang/proposals/csharp-9.0/records.md + - name: Top-level statements + href: ../../_csharplang/proposals/csharp-9.0/top-level-statements.md + - name: Nullable reference types - specification + href: ../../_csharplang/proposals/csharp-9.0/nullable-reference-types-specification.md + - name: Pattern matching enhancements + href: ../../_csharplang/proposals/csharp-9.0/patterns3.md + - name: Init only setters + href: ../../_csharplang/proposals/csharp-9.0/init.md + - name: Target-typed new expressions + href: ../../_csharplang/proposals/csharp-9.0/target-typed-new.md + - name: Module initializers + href: ../../_csharplang/proposals/csharp-9.0/module-initializers.md + - name: Extending partial methods + href: ../../_csharplang/proposals/csharp-9.0/extending-partial-methods.md + - name: Static anonymous functions + href: ../../_csharplang/proposals/csharp-9.0/static-anonymous-functions.md + - name: Target-typed conditional expression + href: ../../_csharplang/proposals/csharp-9.0/target-typed-conditional-expression.md + - name: Covariant return types + href: ../../_csharplang/proposals/csharp-9.0/covariant-returns.md + - name: Extension GetEnumerator in foreach loops + href: ../../_csharplang/proposals/csharp-9.0/extension-getenumerator.md + - name: Lambda discard parameters + href: ../../_csharplang/proposals/csharp-9.0/lambda-discard-parameters.md + - name: Attributes on local functions + href: ../../_csharplang/proposals/csharp-9.0/local-function-attributes.md + - name: Native sized integers + href: ../../_csharplang/proposals/csharp-9.0/native-integers.md + - name: Function pointers + href: ../../_csharplang/proposals/csharp-9.0/function-pointers.md + - name: Suppress emitting localsinit flag + href: ../../_csharplang/proposals/csharp-9.0/skip-localsinit.md + - name: Unconstrained type parameter annotations + href: ../../_csharplang/proposals/csharp-9.0/unconstrained-type-parameter-annotations.md From c889d4b7672859dd3e247434f5cff53661d7a6f2 Mon Sep 17 00:00:00 2001 From: Bill Wagner Date: Tue, 6 Jul 2021 14:21:45 -0400 Subject: [PATCH 21/27] Record types can seal ToString in C# 10. (#24957) * Add information on sealed ToString Fixes #24077 Beginning in C# 10.0, records may declare a `ToString` method as `sealed`. This prevents derived records from creating an override. Effectively, that means the `ToString` output will not include the runtime type information. (All members and values are displayed, because derived records will still have a PrintMembers method generated.) * add note on ToString. * fix a build warning introduced This was introduced in an earlier PR * Update docs/csharp/language-reference/builtin-types/record.md Co-authored-by: Youssef Victor * Apply suggestions from code review Co-authored-by: Tom Dykstra Co-authored-by: Youssef Victor Co-authored-by: Tom Dykstra --- docs/csharp/language-reference/attributes/general.md | 2 +- docs/csharp/language-reference/builtin-types/record.md | 7 +++++-- docs/csharp/whats-new/tutorials/records.md | 4 +++- .../tutorials/snippets/record-types/record-types.csproj | 2 +- 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/csharp/language-reference/attributes/general.md b/docs/csharp/language-reference/attributes/general.md index 4e99b4c3cd177..30deaf8f1be05 100644 --- a/docs/csharp/language-reference/attributes/general.md +++ b/docs/csharp/language-reference/attributes/general.md @@ -45,7 +45,7 @@ The string provided as the first argument to the attribute constructor will be d In C# 10, you can use constant string interpolation and the `nameof` operator to ensure the names match: -:::code language="csharp" source="snippets/ObsoleteExample.cs" ID="Snippet2" ::: +:::code language="csharp" source="snippets/ObsoleteExample.cs" id="Snippet2" ::: ## `AttributeUsage` attribute diff --git a/docs/csharp/language-reference/builtin-types/record.md b/docs/csharp/language-reference/builtin-types/record.md index bba9566da2bb2..d468a7b8781ca 100644 --- a/docs/csharp/language-reference/builtin-types/record.md +++ b/docs/csharp/language-reference/builtin-types/record.md @@ -1,7 +1,7 @@ --- title: "Records - C# reference" description: Learn about the record type in C# -ms.date: 02/25/2021 +ms.date: 07/01/2021 f1_keywords: - "record_CSharpKeyword" helpviewer_keywords: @@ -136,7 +136,7 @@ The `ToString` override creates a object with t :::code language="csharp" source="snippets/shared/RecordType.cs" id="ToStringOverrideDefault"::: -You can provide your own implementation of `PrintMembers` or the `ToString` override. Examples are provided in the [`PrintMembers` formatting in derived records](#printmembers-formatting-in-derived-records) section later in this article. +You can provide your own implementation of `PrintMembers` or the `ToString` override. Examples are provided in the [`PrintMembers` formatting in derived records](#printmembers-formatting-in-derived-records) section later in this article. In C# 10 and later, your implementation of `ToString` may include the `sealed` modifier, which prevents the compiler from synthesizing a `ToString` implementation for any derived records. Effectively, that means the `ToString` output will not include the runtime type information. (All members and values are displayed, because derived records will still have a PrintMembers method generated.) ## Inheritance @@ -185,6 +185,9 @@ Here is an example of code that replaces the synthesized `PrintMembers` methods, :::code language="csharp" source="snippets/shared/RecordType.cs" id="PrintMembersImplementation"::: +> [!NOTE] +> In C# 10.0 and later, the compiler will synthesize `PrintMembers` when a base record has sealed the `ToString` method. You can also create your own implementation of `PrintMembers`. + ### Deconstructor behavior in derived records The `Deconstruct` method of a derived record returns the values of all positional properties of the compile-time type. If the variable type is a base record, only the base record properties are deconstructed unless the object is cast to the derived type. The following example demonstrates calling a deconstructor on a derived record. diff --git a/docs/csharp/whats-new/tutorials/records.md b/docs/csharp/whats-new/tutorials/records.md index dd58a59807abf..9894f653d4390 100644 --- a/docs/csharp/whats-new/tutorials/records.md +++ b/docs/csharp/whats-new/tutorials/records.md @@ -1,7 +1,7 @@ --- title: Use record types - C# tutorial description: Learn about how to use record types, build hierarchies of records, and when to choose records over classes. -ms.date: 11/12/2020 +ms.date: 07/01/2021 --- # Create record types @@ -125,6 +125,8 @@ You declare a `PrintMembers` method in the `DegreeDays` record that doesn't prin The signature declares a `virtual protected` method to match the compiler's version. Don't worry if you get the accessors wrong; the language enforces the correct signature. If you forget the correct modifiers for any synthesized method, the compiler issues warnings or errors that help you get the right signature. +In C# 10.0 and later, you can declare the `ToString` method as `sealed` in a record type. That prevents derived records from providing a new implementation. Derived records will still contain the `PrintMembers` override. You would do this if you didn't want the `ToString` method to display the runtime type of the record. In the preceding example, you'd lose the information on where the record was measuring heating or cooling degree days. + ## Non-destructive mutation The synthesized members in a positional record don't modify the state of the record. The goal is that you can more easily create immutable records. Look again at the preceding declarations for `HeatingDegreeDays` and `CoolingDegreeDays`. The members added perform computations on the values for the record, but don't mutate state. Positional records make it easier for you to create immutable reference types. diff --git a/docs/csharp/whats-new/tutorials/snippets/record-types/record-types.csproj b/docs/csharp/whats-new/tutorials/snippets/record-types/record-types.csproj index 5d38b2381cbf9..0a4163c9e5e77 100644 --- a/docs/csharp/whats-new/tutorials/snippets/record-types/record-types.csproj +++ b/docs/csharp/whats-new/tutorials/snippets/record-types/record-types.csproj @@ -2,7 +2,7 @@ Exe - net5.0 + net6.0 record_types From bed2c376509167dc36e2206ec3bf5fcc131d7490 Mon Sep 17 00:00:00 2001 From: Yan Reznikov Date: Tue, 6 Jul 2021 15:07:34 -0700 Subject: [PATCH 22/27] Update linux installation instructions to cleanup packages-microsoft-prod.deb after installation (#24756) * Update linux installation instructions to cleanup packages-microsoft-prod.deb after installation Currently instructions leave packages-microsoft-prod.deb in current folder after installation. Adding removal to cleanup leftovers * Update linux-debian.md Co-authored-by: Andy (Steve) De George <67293991+adegeo@users.noreply.github.com> --- docs/core/install/linux-debian.md | 1 + docs/core/install/linux-ubuntu.md | 11 +++++++++++ 2 files changed, 12 insertions(+) diff --git a/docs/core/install/linux-debian.md b/docs/core/install/linux-debian.md index 30ef0722eb831..6e10b05596af1 100644 --- a/docs/core/install/linux-debian.md +++ b/docs/core/install/linux-debian.md @@ -45,6 +45,7 @@ The following versions of .NET are no longer supported. The downloads for these ```bash wget https://packages.microsoft.com/config/debian/10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-50](includes/linux-install-50-apt.md)] diff --git a/docs/core/install/linux-ubuntu.md b/docs/core/install/linux-ubuntu.md index 0996fa198e6de..80746ce7584c8 100644 --- a/docs/core/install/linux-ubuntu.md +++ b/docs/core/install/linux-ubuntu.md @@ -53,6 +53,7 @@ The following versions of .NET are no longer supported. The downloads for these ```bash wget https://packages.microsoft.com/config/ubuntu/21.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-50](includes/linux-install-50-apt.md)] @@ -64,6 +65,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/20.10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-50](includes/linux-install-50-apt.md)] @@ -75,6 +77,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/20.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-50](includes/linux-install-50-apt.md)] @@ -88,6 +91,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/19.10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-31](includes/linux-install-31-apt.md)] @@ -101,6 +105,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/19.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-31](includes/linux-install-31-apt.md)] @@ -114,6 +119,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/18.10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-21](includes/linux-install-21-apt.md)] @@ -125,6 +131,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-50](includes/linux-install-50-apt.md)] @@ -138,6 +145,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/17.10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-21](includes/linux-install-21-apt.md)] @@ -151,6 +159,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/17.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-21](includes/linux-install-21-apt.md)] @@ -164,6 +173,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/16.10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-21](includes/linux-install-21-apt.md)] @@ -175,6 +185,7 @@ sudo dpkg -i packages-microsoft-prod.deb ```bash wget https://packages.microsoft.com/config/ubuntu/16.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb +rm packages-microsoft-prod.deb ``` [!INCLUDE [linux-apt-install-50](includes/linux-install-50-apt.md)] From ac52aa87a2de56d7dd40a8c8e1f8120f6d460690 Mon Sep 17 00:00:00 2001 From: Tom Dykstra Date: Tue, 6 Jul 2021 15:37:05 -0700 Subject: [PATCH 23/27] Fix text that was causing translation error (#21749) (#25008) --- .../tutorials/debugging-with-visual-studio-code.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/core/tutorials/debugging-with-visual-studio-code.md b/docs/core/tutorials/debugging-with-visual-studio-code.md index b551998db44ef..a8076fb6456bf 100644 --- a/docs/core/tutorials/debugging-with-visual-studio-code.md +++ b/docs/core/tutorials/debugging-with-visual-studio-code.md @@ -42,15 +42,7 @@ The breakpoint is located after a `Console.ReadLine` method call. The **Debug Co 1. Open *.vscode/launch.json*. -1. Change the `console` setting to `integratedTerminal`. - - From: - - ```json - "console": "internalConsole", - ``` - - To: +1. Change the `console` setting from `internalConsole` to `integratedTerminal`: ```json "console": "integratedTerminal", From 6d355e0a06177984777735449b9e2f718cfbaeef Mon Sep 17 00:00:00 2001 From: Jamshed Damkewala Date: Tue, 6 Jul 2021 17:07:44 -0700 Subject: [PATCH 24/27] Add Server 2012 to the support matrix for 3.1, 5.0 --- docs/core/install/windows.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/core/install/windows.md b/docs/core/install/windows.md index 50bdefd4af0c9..822399b6e8c41 100644 --- a/docs/core/install/windows.md +++ b/docs/core/install/windows.md @@ -42,7 +42,7 @@ Windows 10 versions end-of-service dates are segmented by edition. Only **Home** | Windows 10, Version 1607 | ✔️ | ✔️ | ✔️ | | Windows 8.1 | ✔️ | ✔️ | ✔️ | | Windows 7 SP1 [ESU][esu] | ✔️ | ✔️ | ✔️ | -| Windows Server 2019
Windows Server 2016
Windows Server 2012 R2
| ✔️ | ✔️ | ✔️ | +| Windows Server 2019
Windows Server 2016
Windows Server 2012 R2
Windows Server 2012| ✔️ | ✔️ | ✔️ | | Windows Server Core 2012 R2 | ✔️ | ✔️ | ✔️ | | Windows Server Core 2012 | ✔️ | ✔️ | ✔️ | | Nano Server, Version 1809+ | ✔️ | ✔️ | ✔️ | @@ -94,8 +94,8 @@ The following Windows versions are supported with .NET 5.0: |---------------------|---------------|-----------------| | Windows 10 Client | Version 1607+ | x64, x86, ARM64 | | Windows Client | 7 SP1+, 8.1 | x64, x86 | -| Windows Server | 2012 R2+ | x64, x86 | -| Windows Server Core | 2012 R2+ | x64, x86 | +| Windows Server | 2012 R2 | x64, x86 | +| Windows Server Core | 2012 R2 | x64, x86 | | Nano Server | Version 1809+ | x64 | For more information about .NET 5.0 supported operating systems, distributions, and lifecycle policy, see [.NET 5.0 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/5.0/5.0-supported-os.md). @@ -111,7 +111,7 @@ The following Windows versions are supported with .NET Core 3.1: | ----------------------------- | ------------------------------ | --------------- | | Windows Client | 7 SP1+, 8.1 | x64, x86 | | Windows 10 Client | Version 1607+ | x64, x86 | -| Windows Server | 2012 R2+ | x64, x86 | +| Windows Server | 2012 R2 | x64, x86 | | Nano Server | Version 1803+ | x64, ARM32 | For more information about .NET Core 3.1 supported operating systems, distributions, and lifecycle policy, see [.NET Core 3.1 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/3.1/3.1-supported-os.md). From e757a1bb85ede6085f7af94629eca9768a9b7597 Mon Sep 17 00:00:00 2001 From: Jamshed Damkewala Date: Tue, 6 Jul 2021 17:09:56 -0700 Subject: [PATCH 25/27] Updated pre-reqs to include Server 2012 --- docs/core/install/windows.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/core/install/windows.md b/docs/core/install/windows.md index 822399b6e8c41..67705f2559e65 100644 --- a/docs/core/install/windows.md +++ b/docs/core/install/windows.md @@ -194,6 +194,7 @@ More dependencies are required if you're installing the .NET SDK or runtime on t | Windows Vista SP 2 | Microsoft Visual C++ 2015-2019 Redistributable [64-bit][vcc64] / [32-bit][vcc32] | | Windows 8.1 | Microsoft Visual C++ 2015-2019 Redistributable [64-bit][vcc64] / [32-bit][vcc32] | | Windows Server 2008 R2 | Microsoft Visual C++ 2015-2019 Redistributable [64-bit][vcc64] / [32-bit][vcc32] | +| Windows Server 2012 | Microsoft Visual C++ 2015-2019 Redistributable [64-bit][vcc64] / [32-bit][vcc32] | | Windows Server 2012 R2 | Microsoft Visual C++ 2015-2019 Redistributable [64-bit][vcc64] / [32-bit][vcc32] | The previous requirements are also required if you receive an error related to either of the following dlls: From 30a6261d630762472c0536a14cb83e340a532ee4 Mon Sep 17 00:00:00 2001 From: Jamshed Damkewala Date: Tue, 6 Jul 2021 17:12:52 -0700 Subject: [PATCH 26/27] Fixes to supported OS --- docs/core/install/windows.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/install/windows.md b/docs/core/install/windows.md index 67705f2559e65..c5a4f0934ba23 100644 --- a/docs/core/install/windows.md +++ b/docs/core/install/windows.md @@ -94,8 +94,8 @@ The following Windows versions are supported with .NET 5.0: |---------------------|---------------|-----------------| | Windows 10 Client | Version 1607+ | x64, x86, ARM64 | | Windows Client | 7 SP1+, 8.1 | x64, x86 | -| Windows Server | 2012 R2 | x64, x86 | -| Windows Server Core | 2012 R2 | x64, x86 | +| Windows Server | 2012 + | x64, x86 | +| Windows Server Core | 2012 + | x64, x86 | | Nano Server | Version 1809+ | x64 | For more information about .NET 5.0 supported operating systems, distributions, and lifecycle policy, see [.NET 5.0 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/5.0/5.0-supported-os.md). @@ -111,7 +111,7 @@ The following Windows versions are supported with .NET Core 3.1: | ----------------------------- | ------------------------------ | --------------- | | Windows Client | 7 SP1+, 8.1 | x64, x86 | | Windows 10 Client | Version 1607+ | x64, x86 | -| Windows Server | 2012 R2 | x64, x86 | +| Windows Server | 2012+ | x64, x86 | | Nano Server | Version 1803+ | x64, ARM32 | For more information about .NET Core 3.1 supported operating systems, distributions, and lifecycle policy, see [.NET Core 3.1 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/3.1/3.1-supported-os.md). From 0259f7e28b288dd81cf660461c49c7c14592f042 Mon Sep 17 00:00:00 2001 From: "Andy (Steve) De George" <67293991+adegeo@users.noreply.github.com> Date: Wed, 7 Jul 2021 07:52:27 -0700 Subject: [PATCH 27/27] Update docs/core/install/windows.md --- docs/core/install/windows.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/core/install/windows.md b/docs/core/install/windows.md index c5a4f0934ba23..4203258cab8e5 100644 --- a/docs/core/install/windows.md +++ b/docs/core/install/windows.md @@ -94,8 +94,8 @@ The following Windows versions are supported with .NET 5.0: |---------------------|---------------|-----------------| | Windows 10 Client | Version 1607+ | x64, x86, ARM64 | | Windows Client | 7 SP1+, 8.1 | x64, x86 | -| Windows Server | 2012 + | x64, x86 | -| Windows Server Core | 2012 + | x64, x86 | +| Windows Server | 2012+ | x64, x86 | +| Windows Server Core | 2012+ | x64, x86 | | Nano Server | Version 1809+ | x64 | For more information about .NET 5.0 supported operating systems, distributions, and lifecycle policy, see [.NET 5.0 Supported OS Versions](https://github.com/dotnet/core/blob/main/release-notes/5.0/5.0-supported-os.md).