diff --git a/docs/azure/includes/dotnet-all.md b/docs/azure/includes/dotnet-all.md index 5914d522abe8b..78c5137e85da4 100644 --- a/docs/azure/includes/dotnet-all.md +++ b/docs/azure/includes/dotnet-all.md @@ -12,7 +12,7 @@ | Calling Server | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.CallingServer/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.CallingServer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallingServer_1.0.0-beta.3/sdk/communication/Azure.Communication.CallingServer/) | | Code Transparency | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Security.CodeTransparency/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Security.CodeTransparency-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.CodeTransparency_1.0.0-beta.2/sdk/confidentialledger/Azure.Security.CodeTransparency/) | | Communication Call Automation | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.2.0)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.CallAutomation-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.2.0/sdk/communication/Azure.Communication.CallAutomation/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.3.0-beta.1/sdk/communication/Azure.Communication.CallAutomation/) | -| Communication Chat | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Chat/1.3.0) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.3.0/sdk/communication/Azure.Communication.Chat/) | +| Communication Chat | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Communication.Chat/1.3.1) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.3.1/sdk/communication/Azure.Communication.Chat/) | | Communication Common | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Common/1.3.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Common/2.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.3.0/sdk/communication/Azure.Communication.Common/)
GitHub [2.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_2.0.0-beta.1/sdk/communication/Azure.Communication.Common/) | | Communication Email | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Email/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Email/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Email-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.0.1/sdk/communication/Azure.Communication.Email/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.1.0-beta.1/sdk/communication/Azure.Communication.Email/) | | Communication Identity | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Communication.Identity/1.3.1) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.3.1/sdk/communication/Azure.Communication.Identity/) | @@ -39,7 +39,7 @@ | Digital Twins | NuGet [1.4.0](https://www.nuget.org/packages/Azure.DigitalTwins.Core/1.4.0) | [docs](/dotnet/api/overview/azure/DigitalTwins.Core-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.DigitalTwins.Core_1.4.0/sdk/digitaltwins/Azure.DigitalTwins.Core/) | | Document Intelligence | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.DocumentIntelligence/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.DocumentIntelligence-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.DocumentIntelligence_1.0.0-beta.3/sdk/documentintelligence/Azure.AI.DocumentIntelligence/) | | Document Translation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.AI.Translation.Document/1.0.0)
NuGet [2.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Translation.Document/2.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Translation.Document-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_1.0.0/sdk/translation/Azure.AI.Translation.Document/)
GitHub [2.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_2.0.0-beta.2/sdk/translation/Azure.AI.Translation.Document/) | -| Event Grid | NuGet [4.25.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.25.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.25.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.25.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | +| Event Grid | NuGet [4.26.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.26.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.26.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.26.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | | Event Grid Namespaces | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid.Namespaces/1.0.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid.Namespaces-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid.Namespaces_1.0.0/sdk/eventgrid/Azure.Messaging.EventGrid.Namespaces/) | | Event Hubs | NuGet [5.11.5](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.11.5)
NuGet [5.12.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.12.0-beta.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme) | GitHub [5.11.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.11.5/sdk/eventhub/Azure.Messaging.EventHubs/)
GitHub [5.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.12.0-beta.1/sdk/eventhub/Azure.Messaging.EventHubs/) | | Event Hubs - Event Processor | NuGet [5.11.5](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.11.5)
NuGet [5.12.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.12.0-beta.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme) | GitHub [5.11.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.11.5/sdk/eventhub/Azure.Messaging.EventHubs.Processor/)
GitHub [5.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.12.0-beta.1/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | @@ -368,7 +368,7 @@ | Azure Stack - Azure Consistent Storage | NuGet [0.10.8-preview](https://www.nuget.org/packages/Microsoft.AzureStack.AzureConsistentStorage/0.10.8-preview) | | | | Azure.FX | NuGet [0.0.24-alpha](https://www.nuget.org/packages/Azure.FX/0.0.24-alpha) | | | | Azure.FX.Templates | NuGet [1.2.0](https://www.nuget.org/packages/Azure.FX.Templates/1.2.0) | | | -| Batch | NuGet [16.3.0](https://www.nuget.org/packages/Microsoft.Azure.Batch/16.3.0) | | GitHub [16.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Batch_16.3.0/sdk/batch/Microsoft.Azure.Batch/) | +| Batch | NuGet [16.3.1](https://www.nuget.org/packages/Microsoft.Azure.Batch/16.3.1) | | GitHub [16.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Batch_16.3.1/sdk/batch/Microsoft.Azure.Batch/) | | Batch - Apps Cryptography | NuGet [1.1.1.4](https://www.nuget.org/packages/Microsoft.Azure.Batch.Apps.Cryptography/1.1.1.4) | | | | Batch - Conventions Files | NuGet [4.0.0](https://www.nuget.org/packages/Microsoft.Azure.Batch.Conventions.Files/4.0.0) | | GitHub [4.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Microsoft.Azure.Batch.Conventions.Files_4.0.0/sdk/batch/Microsoft.Azure.Batch.Conventions.Files/) | | Batch - File Staging | NuGet [9.0.0](https://www.nuget.org/packages/Microsoft.Azure.Batch.FileStaging/9.0.0) | | GitHub [9.0.0](https://github.com/Azure/azure-sdk-for-net/tree/mgmt-legacy/sdk/batch/Microsoft.Azure.Batch.FileStaging) | diff --git a/docs/azure/includes/dotnet-new.md b/docs/azure/includes/dotnet-new.md index 42d8fdd83e298..64b69dc1859d5 100644 --- a/docs/azure/includes/dotnet-new.md +++ b/docs/azure/includes/dotnet-new.md @@ -12,7 +12,7 @@ | Calling Server | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.Communication.CallingServer/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/Communication.CallingServer-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallingServer_1.0.0-beta.3/sdk/communication/Azure.Communication.CallingServer/) | | Code Transparency | NuGet [1.0.0-beta.2](https://www.nuget.org/packages/Azure.Security.CodeTransparency/1.0.0-beta.2) | [docs](/dotnet/api/overview/azure/Security.CodeTransparency-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Security.CodeTransparency_1.0.0-beta.2/sdk/confidentialledger/Azure.Security.CodeTransparency/) | | Communication Call Automation | NuGet [1.2.0](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.2.0)
NuGet [1.3.0-beta.1](https://www.nuget.org/packages/Azure.Communication.CallAutomation/1.3.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.CallAutomation-readme) | GitHub [1.2.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.2.0/sdk/communication/Azure.Communication.CallAutomation/)
GitHub [1.3.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.CallAutomation_1.3.0-beta.1/sdk/communication/Azure.Communication.CallAutomation/) | -| Communication Chat | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Chat/1.3.0) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.3.0/sdk/communication/Azure.Communication.Chat/) | +| Communication Chat | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Communication.Chat/1.3.1) | [docs](/dotnet/api/overview/azure/Communication.Chat-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Chat_1.3.1/sdk/communication/Azure.Communication.Chat/) | | Communication Common | NuGet [1.3.0](https://www.nuget.org/packages/Azure.Communication.Common/1.3.0)
NuGet [2.0.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Common/2.0.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Common-readme) | GitHub [1.3.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_1.3.0/sdk/communication/Azure.Communication.Common/)
GitHub [2.0.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Common_2.0.0-beta.1/sdk/communication/Azure.Communication.Common/) | | Communication Email | NuGet [1.0.1](https://www.nuget.org/packages/Azure.Communication.Email/1.0.1)
NuGet [1.1.0-beta.1](https://www.nuget.org/packages/Azure.Communication.Email/1.1.0-beta.1) | [docs](/dotnet/api/overview/azure/Communication.Email-readme) | GitHub [1.0.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.0.1/sdk/communication/Azure.Communication.Email/)
GitHub [1.1.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Email_1.1.0-beta.1/sdk/communication/Azure.Communication.Email/) | | Communication Identity | NuGet [1.3.1](https://www.nuget.org/packages/Azure.Communication.Identity/1.3.1) | [docs](/dotnet/api/overview/azure/Communication.Identity-readme) | GitHub [1.3.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Communication.Identity_1.3.1/sdk/communication/Azure.Communication.Identity/) | @@ -40,7 +40,7 @@ | Digital Twins | NuGet [1.4.0](https://www.nuget.org/packages/Azure.DigitalTwins.Core/1.4.0) | [docs](/dotnet/api/overview/azure/DigitalTwins.Core-readme) | GitHub [1.4.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.DigitalTwins.Core_1.4.0/sdk/digitaltwins/Azure.DigitalTwins.Core/) | | Document Intelligence | NuGet [1.0.0-beta.3](https://www.nuget.org/packages/Azure.AI.DocumentIntelligence/1.0.0-beta.3) | [docs](/dotnet/api/overview/azure/AI.DocumentIntelligence-readme?view=azure-dotnet-preview&preserve-view=true) | GitHub [1.0.0-beta.3](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.DocumentIntelligence_1.0.0-beta.3/sdk/documentintelligence/Azure.AI.DocumentIntelligence/) | | Document Translation | NuGet [1.0.0](https://www.nuget.org/packages/Azure.AI.Translation.Document/1.0.0)
NuGet [2.0.0-beta.2](https://www.nuget.org/packages/Azure.AI.Translation.Document/2.0.0-beta.2) | [docs](/dotnet/api/overview/azure/AI.Translation.Document-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_1.0.0/sdk/translation/Azure.AI.Translation.Document/)
GitHub [2.0.0-beta.2](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.Translation.Document_2.0.0-beta.2/sdk/translation/Azure.AI.Translation.Document/) | -| Event Grid | NuGet [4.25.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.25.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.25.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.25.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | +| Event Grid | NuGet [4.26.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid/4.26.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid-readme) | GitHub [4.26.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid_4.26.0/sdk/eventgrid/Azure.Messaging.EventGrid/) | | Event Grid Namespaces | NuGet [1.0.0](https://www.nuget.org/packages/Azure.Messaging.EventGrid.Namespaces/1.0.0) | [docs](/dotnet/api/overview/azure/Messaging.EventGrid.Namespaces-readme) | GitHub [1.0.0](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventGrid.Namespaces_1.0.0/sdk/eventgrid/Azure.Messaging.EventGrid.Namespaces/) | | Event Hubs | NuGet [5.11.5](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.11.5)
NuGet [5.12.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs/5.12.0-beta.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs-readme) | GitHub [5.11.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.11.5/sdk/eventhub/Azure.Messaging.EventHubs/)
GitHub [5.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs_5.12.0-beta.1/sdk/eventhub/Azure.Messaging.EventHubs/) | | Event Hubs - Event Processor | NuGet [5.11.5](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.11.5)
NuGet [5.12.0-beta.1](https://www.nuget.org/packages/Azure.Messaging.EventHubs.Processor/5.12.0-beta.1) | [docs](/dotnet/api/overview/azure/Messaging.EventHubs.Processor-readme) | GitHub [5.11.5](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.11.5/sdk/eventhub/Azure.Messaging.EventHubs.Processor/)
GitHub [5.12.0-beta.1](https://github.com/Azure/azure-sdk-for-net/tree/Azure.Messaging.EventHubs.Processor_5.12.0-beta.1/sdk/eventhub/Azure.Messaging.EventHubs.Processor/) | diff --git a/docs/core/diagnostics/debug-stackoverflow.md b/docs/core/diagnostics/debug-stackoverflow.md index 0f613e71ea6a6..759d30a958b79 100644 --- a/docs/core/diagnostics/debug-stackoverflow.md +++ b/docs/core/diagnostics/debug-stackoverflow.md @@ -6,7 +6,7 @@ ms.date: 8/22/2024 --- # Debug StackOverflow errors -A is thrown when the execution stack overflows because it contains too many nested method calls. +A is thrown when the execution stack overflows because it contains too many nested method calls. Very often this occurs because methods are calling each other [recursively](https://wikipedia.org/wiki/Recursion_(computer_science)). For example, suppose you have an app as follows: @@ -39,12 +39,15 @@ Stack overflow. ```` -Often just seeing this callstack is enough to identify the problematic repeating method and locate the source code logic that is causing the recursive calls. However if the problem is still unclear you can debug further. +When you see the program exit with output like this, you can find the source code for the repeating method(s) and investigate the logic that causes the large number of calls. -> [!NOTE] -> This article describes how to debug a stack overflow with lldb on Linux. If you are running on Windows, we suggest debugging the app with [Visual Studio](/visualstudio/debugger/what-is-debugging) or [Visual Studio Code](https://code.visualstudio.com/Docs/editor/debugging). +## Using the debugger -## Example +Often just seeing this callstack on the console above is enough to identify the problematic code. However if the problem is still unclear you can debug further. + +### [Linux](#tab/linux) + +This example creates a core dump when the StackOverflowException occurs, then loads the dump into [lldb](https://lldb.llvm.org/) (a common Linux command-line debugger) and debugs it. 1. Run the app with it configured to collect a dump on crash @@ -64,7 +67,7 @@ Often just seeing this callstack is enough to identify the problematic repeating dotnet-sos install ```` -3. Debug the dump in lldb to see the failing stack +3. Open the dump in lldb and use the `bt` (backtrace) command to display the stack. ```` lldb --core /temp/coredump.6412 @@ -82,7 +85,7 @@ Often just seeing this callstack is enough to identify the problematic repeating ... ```` -4. The top frame `0x00007f59b40900cc` is repeated several times. Use the [SOS](sos-debugging-extension.md) `ip2md` command to figure out what method is located at the `0x00007f59b40900cc` address +4. The top frame `0x00007f59b40900cc` is repeated several times. Use the [SOS](sos-debugging-extension.md) `ip2md` command to figure out what managed method is located at the `0x00007f59b40900cc` address ```` (lldb) ip2md 0x00007f59b40900cc @@ -103,7 +106,19 @@ Often just seeing this callstack is enough to identify the problematic repeating Source file: /temp/Program.cs @ 9 ```` -5. Go look at the indicated method temp.Program.Main(System.String[]) and source "/temp/Program.cs @ 9" to see if you can figure out what you did wrong. If it still wasn't clear you could use further debugger commands to inspect the current state of the process or add logging in that area of the code. +5. Go look at the indicated method temp.Program.Main(System.String[]) and source "/temp/Program.cs @ 9" to see if you can figure out what the code is doing wrong. If additional information is needed, you can use further debugger or [SOS](sos-debugging-extension.md) commands to inspect the process. + +### [Windows](#tab/windows) + +Running the application under the debugger in [Visual Studio](/visualstudio/debugger/what-is-debugging) will show a StackOverflowException in the exception helper dialog and highlight the line of code responsible for making the final call that overflows the stack. + +[Visual Studio StackOverflowException dialog](media/visual_studio_stackoverflow_exception.png) + +The callstack debugger window also shows the stack. + +[Visual Studio StackOverflow callstack](media/visual_studio_stackoverflow_callstack.png) + +You can use all the normal Visual Studio debugger features to investigate each frame on the callstack, its source code, and the value of local variables. ## See Also diff --git a/docs/core/diagnostics/media/visual_studio_stackoverflow_callstack.png b/docs/core/diagnostics/media/visual_studio_stackoverflow_callstack.png new file mode 100644 index 0000000000000..2791f9b3e5a2c Binary files /dev/null and b/docs/core/diagnostics/media/visual_studio_stackoverflow_callstack.png differ diff --git a/docs/core/diagnostics/media/visual_studio_stackoverflow_exception.png b/docs/core/diagnostics/media/visual_studio_stackoverflow_exception.png new file mode 100644 index 0000000000000..0ef7b3f1015ca Binary files /dev/null and b/docs/core/diagnostics/media/visual_studio_stackoverflow_exception.png differ diff --git a/docs/csharp/fundamentals/coding-style/coding-conventions.md b/docs/csharp/fundamentals/coding-style/coding-conventions.md index 1cf11cd5b4da2..168dec7ba6a75 100644 --- a/docs/csharp/fundamentals/coding-style/coding-conventions.md +++ b/docs/csharp/fundamentals/coding-style/coding-conventions.md @@ -322,7 +322,7 @@ In general, use the following format for code samples: ### Comment style - Use single-line comments (`//`) for brief explanations. -- Avoid multi-line comments (`/* */`) for longer explanations. Comments aren't localized. Instead, longer explanations are in the companion article. +- Avoid multi-line comments (`/* */`) for longer explanations.
Comments in the code samples aren't localized. That means explanations embedded in the code will not be translated. Longer, explanatory text should be placed in the companion article, so that it can be localized. - For describing methods, classes, fields, and all public members use [XML comments](../../language-reference/xmldoc/index.md). - Place the comment on a separate line, not at the end of a line of code. - Begin comment text with an uppercase letter. diff --git a/docs/csharp/language-reference/keywords/event.md b/docs/csharp/language-reference/keywords/event.md index 381b2f3170e20..1546b194cb7e4 100644 --- a/docs/csharp/language-reference/keywords/event.md +++ b/docs/csharp/language-reference/keywords/event.md @@ -13,7 +13,7 @@ ms.assetid: 7858fd85-153b-4259-85d0-6aa13c35f174 --- # event (C# reference) -The `event` keyword is used to declare an event in a publisher class. +An ***event*** is a member that enables an object or class to provide notifications. Clients can attach executable code for events by supplying ***event handlers***. The `event` keyword declares an ***event***. An instance of an event is a delegate type. An object raises the event by invoking event handlers. Event handlers are delegate instances added to the event instance. Clients can add or remove their event handlers from an event. ## Example diff --git a/docs/csharp/tutorials/snippets/RangesIndexes/IndicesAndRanges.cs b/docs/csharp/tutorials/snippets/RangesIndexes/IndicesAndRanges.cs index a591c66172d36..318497ee85f74 100644 --- a/docs/csharp/tutorials/snippets/RangesIndexes/IndicesAndRanges.cs +++ b/docs/csharp/tutorials/snippets/RangesIndexes/IndicesAndRanges.cs @@ -21,7 +21,7 @@ class IndicesAndRanges internal int Syntax_LastIndex() { // - Console.WriteLine($"The last word is < {words[^1]} >."); // The last worid is < tenth >. + Console.WriteLine($"The last word is < {words[^1]} >."); // The last word is < tenth >. // return 0; } diff --git a/docs/standard/serialization/system-text-json/customize-properties.md b/docs/standard/serialization/system-text-json/customize-properties.md index 70c013ea7d327..e36b2ec9ff0f2 100644 --- a/docs/standard/serialization/system-text-json/customize-properties.md +++ b/docs/standard/serialization/system-text-json/customize-properties.md @@ -13,6 +13,8 @@ helpviewer_keywords: - "serialization" - "objects, serializing" ms.topic: how-to +ms.collection: ce-skilling-ai-copilot +ms.custom: vs-copilot-horizontal --- # How to customize property names and values with System.Text.Json @@ -28,6 +30,9 @@ By default, property names and dictionary keys are unchanged in the JSON output, > [!NOTE] > The [web default](configure-options.md#web-defaults-for-jsonserializeroptions) naming policy is camel case. +> [!TIP] +> You can use AI assistance to [customize property names and values with GitHub Copilot](#use-github-copilot-to-customize-property-names-and-order). + For other scenarios that require special handling of JSON property names and values, you can [implement custom converters](converters-how-to.md). ## Customize individual property names @@ -228,7 +233,110 @@ By default, properties are serialized in the order in which they're defined in t :::code language="csharp" source="snippets/how-to-6-0/csharp/PropertyOrder.cs"::: +## Use Github Copilot to customize property names and order + +You can use GitHub Copilot in your IDE to generate code to customize names and order of serialized properties. + +If you're using [Visual Studio 2022 version 17.8 or later](/visualstudio/releases/2022/release-notes), you can try the AI-driven [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states) to generate code that uses `System.Text.Json` to customize property names and order in the JSON output from serializtion. Submit your question as a prompt in the Copilot chat window, as in the following example. You can also submit prompts using [inline chat](/visualstudio/ide/visual-studio-github-copilot-chat#ask-questions-in-the-inline-chat-view) in the editor window itself. + +> [!NOTE] +> GitHub Copilot is powered by AI, so surprises and mistakes are possible. Make sure to verify any generated code or suggestions. For more information about the general use of GitHub Copilot, product impact, human oversight, and privacy, see [GitHub Copilot FAQs](https://github.com/features/copilot#faq). + +The following example shows you how to use Copilot to modify existing code to customize property names and order when serializing to JSON. + +1. Add the following C# example code to a code file `Example.cs` in your editor. + In Visual Studio, you can use a C# console application project to try this example. + + :::code language="csharp" source="snippets/how-to-6-0/csharp/copilot-example.cs"::: + + `Example.cs` code does the following: + + - Creates an instance of the `Person` class and initializes its properties with values. + - Serializes the `person` object to a JSON string using `JsonSerializer.Serialize`. + - Prints the following JSON string to the console: + + ```json + {"FirstName":"John","LastName":"Doe","Age":30,"Country":"USA"} + ``` + +1. In Copilot Chat, enter the following prompt to modify the code to customize names and order of the JSON serialization output. + + > `#Example.cs` modify code to use `System.Text.Json` to customize property names and order of JSON output from serialization. Set property names: FirstName to first_name, LastName to last_name. Set order to: Country, FirstName, LastName, Age. Provide customized serialization output. + + `#Example.cs` in the prompt provides a [file reference as context](/visualstudio/ide/copilot-chat-context#reference-a-file) to Copilot. You can customize the prompt to output a JSON string with property names and values that suit your requirements. To set intent and get better answers with scoped context, you can use chat features such as [slash commands, references to files, methods, or classes, and threads](/visualstudio/ide/copilot-chat-context). + + The following output shows an example Copilot Chat response: + + ```output + To customize the property names and order of the JSON output using System.Text.Json, you can use the JsonPropertyName attribute to rename properties and the JsonPropertyOrder attribute to set the order. Here's how you can modify your code: + + using System.Text.Json; + using System.Text.Json.Serialization; + + public class Person + { + [JsonPropertyName("first_name")] + [JsonPropertyOrder(2)] + public string? FirstName { get; set; } + + [JsonPropertyName("last_name")] + [JsonPropertyOrder(3)] + public string? LastName { get; set; } + + [JsonPropertyOrder(4)] + public int Age { get; set; } + + [JsonPropertyOrder(1)] + public string? Country { get; set; } + } + + public class Program + { + public static void Main() + { + var person = new Person + { + FirstName = "John", + LastName = "Doe", + Age = 30, + Country = "USA" + }; + + string jsonString = JsonSerializer.Serialize(person, new JsonSerializerOptions { WriteIndented = true }); + Console.WriteLine(jsonString); + } + } + + **Explanation:** + + 1. Renaming Properties: The JsonPropertyName attribute is used to rename FirstName to first_name and LastName to last_name. + 2. Ordering Properties: The JsonPropertyOrder attribute is used to set the order of the properties in the JSON output. The order is set as: + • Country (Order 1) + • FirstName (Order 2) + • LastName (Order 3) + • Age (Order 4) + 3. Indented JSON: The JsonSerializerOptions with WriteIndented = true is used to make the JSON output more readable. + + **Customized Serialization Output:** + { + "Country": "USA", + "first_name": "John", + "last_name": "Doe", + "Age": 30 + } + + This ensures that the JSON output has the customized property names and the specified order. + ``` + +When Copilot returns a code block, the response includes options to copy the code, insert the code into a new file, or preview the code output. + +> [!NOTE] +> Your results might be different from what's shown in the example responses. AI models are non-deterministic, which means that they can return different responses when asked the same question. This might be due to additional learning and adaption over time, language variation, changes in context, such as your chat history, and more. + ## See also - [System.Text.Json overview](overview.md) - [How to serialize and deserialize JSON](how-to.md) +- [GitHub Copilot Trust Center](https://resources.github.com/copilot-trust-center/) +- [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states) +- [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview) diff --git a/docs/standard/serialization/system-text-json/deserialization.md b/docs/standard/serialization/system-text-json/deserialization.md index 925c39829663a..083d60f59a128 100644 --- a/docs/standard/serialization/system-text-json/deserialization.md +++ b/docs/standard/serialization/system-text-json/deserialization.md @@ -11,6 +11,8 @@ helpviewer_keywords: - "deserializing objects" - "deserialization" ms.topic: concept-article +ms.collection: ce-skilling-ai-copilot +ms.custom: vs-copilot-horizontal #customer intent: As a developer, I want to learn how to use System.Text.Json to deserialize JSON data. --- @@ -20,6 +22,9 @@ This article shows how to use the method. For the generic overloads, the generic type parameter is the .NET class. For the non-generic overloads, you pass the type of the class as a method parameter. You can deserialize either synchronously or asynchronously. +> [!TIP] +> You can use AI assistance to [deserialize a JSON string with GitHub Copilot](#use-github-copilot-to-deserialize-json). + Any JSON properties that aren't represented in your class are ignored [by default](missing-members.md). Also, if any properties on the type are [required](required-properties.md) but not present in the JSON payload, deserialization will fail. ## Examples @@ -82,3 +87,66 @@ To deserialize from UTF-8, call a [!NOTE] +> GitHub Copilot is powered by AI, so surprises and mistakes are possible. Make sure to verify any generated code or suggestions. For more information about the general use of GitHub Copilot, product impact, human oversight, and privacy, see [GitHub Copilot FAQs](https://github.com/features/copilot#faq). + +The following text shows an example prompt for Copilot Chat: + +> Generate code to use `System.Text.Json` to deserialize a JSON string {"FirstName":"John","LastName":"Doe","Age":30} to an equivalent .NET object. Map property names & values. Provide example output. + +You can customize the prompt to use a JSON string with property names and values that suit your requirements. + +You can use chat features, such as [slash commands, references to files, methods, or classes, and threads](/visualstudio/ide/copilot-chat-context), to set intent and get better answers with scoped context. For an existing class in a project that's open in the IDE, you can prompt GitHub Copilot with `/generate code to dserialize JSON to equivalent .NET object in #Filename`. + +The following output shows an example Copilot Chat response: + +```output +Here's an example of how you can use `System.Text.Json` to deserialize a JSON string into a .NET object in C#: + +using System; +using System.Text.Json; +public class Person +{ + public string FirstName { get; set; } + public string LastName { get; set; } + public int Age { get; set; } +} +public class Program +{ + public static void Main() + { + string jsonString = "{\"FirstName\":\"John\",\"LastName\":\"Doe\",\"Age\":30}"; + Person person = JsonSerializer.Deserialize(jsonString); + Console.WriteLine($"FirstName: {person.FirstName}"); + Console.WriteLine($"LastName: {person.LastName}"); + Console.WriteLine($"Age: {person.Age}"); + } +} + +**Example Output** +FirstName: John +LastName: Doe +Age: 30 + +This code defines a Person class with properties that match the JSON string. It then uses `JsonSerializer.Deserialize` to convert the JSON string into a `Person` object and prints the properties to the console. +``` + +When Copilot returns a code block, the response includes options to copy the code, insert the code into a new file, or preview the code output. + +> [!NOTE] +> Your results might be different from what's shown in the example responses. AI models are non-deterministic, which means that they can return different responses when asked the same question. This might be due to additional learning and adaption over time, language variation, changes in context, such as your chat history, and more. + +:::image type="content" source="./media/deserialize-json-using-github-copilot.gif" alt-text="Animated screenshot that shows using GitHub Copilot Chat in Visual Studio to deserialize a JSON string to a .NET object." lightbox="./media/deserialize-json-using-github-copilot.gif"::: + +For more information, see: + +* [GitHub Copilot Trust Center](https://resources.github.com/copilot-trust-center/) +* [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states) +* [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview) diff --git a/docs/standard/serialization/system-text-json/media/deserialize-json-using-github-copilot.gif b/docs/standard/serialization/system-text-json/media/deserialize-json-using-github-copilot.gif new file mode 100644 index 0000000000000..8833ad302b60c Binary files /dev/null and b/docs/standard/serialization/system-text-json/media/deserialize-json-using-github-copilot.gif differ diff --git a/docs/standard/serialization/system-text-json/snippets/how-to-6-0/csharp/copilot-example.cs b/docs/standard/serialization/system-text-json/snippets/how-to-6-0/csharp/copilot-example.cs new file mode 100644 index 0000000000000..c7c38ae9e76f4 --- /dev/null +++ b/docs/standard/serialization/system-text-json/snippets/how-to-6-0/csharp/copilot-example.cs @@ -0,0 +1,26 @@ +using System.Text.Json; + +public class Person +{ + public string? FirstName { get; set; } + public string? LastName { get; set; } + public int Age { get; set; } + public string? Country { get; set; } +} + +public class Program +{ + public static void Main() + { + var person = new Person + { + FirstName = "John", + LastName = "Doe", + Age = 30, + Country = "USA" + }; + + string jsonString = JsonSerializer.Serialize(person); + Console.WriteLine(jsonString); + } +}