Skip to content

Commit a818298

Browse files
anandmeganandmeg
authored
Revise serialization docs per revised guidance on adding copilot highlights to docs (#43997)
1 parent cd16d3a commit a818298

File tree

7 files changed

+27
-238
lines changed

7 files changed

+27
-238
lines changed

‎docs/standard/serialization/system-text-json/customize-properties.md

Lines changed: 9 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -246,12 +246,7 @@ By default, properties are serialized in the order in which they're defined in t
246246

247247
## Use Github Copilot to customize property names and order
248248

249-
You can use GitHub Copilot in your IDE to generate code to customize names and order of serialized properties.
250-
251-
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.
252-
253-
> [!NOTE]
254-
> 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).
249+
You can use GitHub Copilot in your IDE to generate code to customize names and order of serialized properties. You can customize the prompt to output a JSON string with property names and values that suit your requirements.
255250

256251
The following example shows you how to use Copilot to modify existing code to customize property names and order when serializing to JSON.
257252

@@ -272,82 +267,18 @@ The following example shows you how to use Copilot to modify existing code to cu
272267

273268
1. In Copilot Chat, enter the following prompt to modify the code to customize names and order of the JSON serialization output.
274269

275-
> `#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.
276-
277-
`#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).
278-
279-
The following output shows an example Copilot Chat response:
280-
281-
```output
282-
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:
283-
284-
using System.Text.Json;
285-
using System.Text.Json.Serialization;
286-
287-
public class Person
288-
{
289-
[JsonPropertyName("first_name")]
290-
[JsonPropertyOrder(2)]
291-
public string? FirstName { get; set; }
292-
293-
[JsonPropertyName("last_name")]
294-
[JsonPropertyOrder(3)]
295-
public string? LastName { get; set; }
296-
297-
[JsonPropertyOrder(4)]
298-
public int Age { get; set; }
299-
300-
[JsonPropertyOrder(1)]
301-
public string? Country { get; set; }
302-
}
303-
304-
public class Program
305-
{
306-
public static void Main()
307-
{
308-
var person = new Person
309-
{
310-
FirstName = "John",
311-
LastName = "Doe",
312-
Age = 30,
313-
Country = "USA"
314-
};
315-
316-
string jsonString = JsonSerializer.Serialize(person, new JsonSerializerOptions { WriteIndented = true });
317-
Console.WriteLine(jsonString);
318-
}
319-
}
320-
321-
**Explanation:**
322-
323-
1. Renaming Properties: The JsonPropertyName attribute is used to rename FirstName to first_name and LastName to last_name.
324-
2. Ordering Properties: The JsonPropertyOrder attribute is used to set the order of the properties in the JSON output. The order is set as:
325-
• Country (Order 1)
326-
• FirstName (Order 2)
327-
• LastName (Order 3)
328-
• Age (Order 4)
329-
3. Indented JSON: The JsonSerializerOptions with WriteIndented = true is used to make the JSON output more readable.
330-
331-
**Customized Serialization Output:**
332-
{
333-
"Country": "USA",
334-
"first_name": "John",
335-
"last_name": "Doe",
336-
"Age": 30
337-
}
338-
339-
This ensures that the JSON output has the customized property names and the specified order.
340-
```
270+
```copilot-prompt
271+
#Example.cs modify code to use System.Text.Json to customize property names and order of JSON output from serialization.
272+
Set property names: FirstName to first_name, LastName to last_name.
273+
Set order to: Country, FirstName, LastName, Age.
274+
Provide customized serialization output.
275+
```
341276
342-
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.
277+
GitHub Copilot is powered by AI, so surprises and mistakes are possible. For more information, see [Copilot FAQs](https://aka.ms/copilot-general-use-faqs).
343278
344-
> [!NOTE]
345-
> 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.
279+
Learn more about [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states) and [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview).
346280
347281
## See also
348282
349283
- [System.Text.Json overview](overview.md)
350284
- [How to serialize and deserialize JSON](how-to.md)
351-
- [GitHub Copilot Trust Center](https://resources.github.com/copilot-trust-center/)
352-
- [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states)
353-
- [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview)

‎docs/standard/serialization/system-text-json/deserialization.md

Lines changed: 7 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -90,63 +90,16 @@ To deserialize from UTF-8, call a <xref:System.Text.Json.JsonSerializer.Deserial
9090

9191
## Use GitHub Copilot to deserialize JSON
9292

93-
You can use GitHub Copilot in your IDE to generate code that uses `System.Text.Json` to deserialize from JSON.
94-
95-
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 deserialize JSON. 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.
96-
97-
> [!NOTE]
98-
> 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).
93+
You can use GitHub Copilot in your IDE to generate code that uses `System.Text.Json` to deserialize from JSON. You can customize the prompt to use a JSON string with property names and values that suit your requirements.
9994

10095
The following text shows an example prompt for Copilot Chat:
10196

102-
> 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.
103-
104-
You can customize the prompt to use a JSON string with property names and values that suit your requirements.
105-
106-
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`.
107-
108-
The following output shows an example Copilot Chat response:
109-
110-
```output
111-
Here's an example of how you can use `System.Text.Json` to deserialize a JSON string into a .NET object in C#:
112-
113-
using System;
114-
using System.Text.Json;
115-
public class Person
116-
{
117-
public string FirstName { get; set; }
118-
public string LastName { get; set; }
119-
public int Age { get; set; }
120-
}
121-
public class Program
122-
{
123-
public static void Main()
124-
{
125-
string jsonString = "{\"FirstName\":\"John\",\"LastName\":\"Doe\",\"Age\":30}";
126-
Person person = JsonSerializer.Deserialize<Person>(jsonString);
127-
Console.WriteLine($"FirstName: {person.FirstName}");
128-
Console.WriteLine($"LastName: {person.LastName}");
129-
Console.WriteLine($"Age: {person.Age}");
130-
}
131-
}
132-
133-
**Example Output**
134-
FirstName: John
135-
LastName: Doe
136-
Age: 30
137-
138-
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.
97+
```copilot-prompt
98+
Generate code to use System.Text.Json to deserialize a JSON string {"FirstName":"John","LastName":"Doe","Age":30} to an equivalent .NET object.
99+
Map property names & values.
100+
Provide example output.
139101
```
140102

141-
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.
142-
143-
> [!NOTE]
144-
> 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.
145-
146-
:::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":::
147-
148-
For more information, see:
103+
GitHub Copilot is powered by AI, so surprises and mistakes are possible. For more information, see [Copilot FAQs](https://aka.ms/copilot-general-use-faqs).
149104

150-
* [GitHub Copilot Trust Center](https://resources.github.com/copilot-trust-center/)
151-
* [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states)
152-
* [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview)
105+
Learn more about [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states) and [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview).

‎docs/standard/serialization/system-text-json/how-to.md

Lines changed: 7 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -111,67 +111,16 @@ Starting in .NET 9, you can also customize the indent character and size using <
111111
112112
## Use GitHub Copilot to serialize to JSON
113113

114-
You can use GitHub Copilot in your IDE to generate code that uses `System.Text.Json` to serialize to JSON.
115-
116-
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 serialize to JSON. 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.
117-
118-
> [!NOTE]
119-
> 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).
114+
You can use GitHub Copilot in your IDE to generate code that uses `System.Text.Json` to serialize to JSON. You can customize the prompt to use object fields that suit your requirements.
120115

121116
The following text shows an example prompt for Copilot Chat:
122117

123-
> Generate code to use `System.Text.Json` to serialize an object to a JSON string. The object contains the following fields: FirstName (string), Lastname (string), Age (int). Provide example output.
124-
125-
You can customize the prompt to use object fields that suit your requirements.
126-
127-
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 serialize #Classname in #Filename to JSON`.
128-
129-
The following output shows an example Copilot Chat response:
130-
131-
```output
132-
Sure! Below is an example of how to use System.Text.Json to serialize an object with the specified fields to a JSON string in C#:
133-
134-
using System;
135-
using System.Text.Json;
136-
137-
public class Person
138-
{
139-
public string FirstName { get; set; }
140-
public string LastName { get; set; }
141-
public int Age { get; set; }
142-
}
143-
144-
public class Program
145-
{
146-
public static void Main()
147-
{
148-
var person = new Person
149-
{
150-
FirstName = "John",
151-
LastName = "Doe",
152-
Age = 30
153-
};
154-
155-
string jsonString = JsonSerializer.Serialize(person);
156-
Console.WriteLine(jsonString);
157-
}
158-
}
159-
160-
**Example Output**
161-
{"FirstName":"John","LastName":"Doe","Age":30}
162-
163-
This code defines a `Person` class, creates an instance of it, and then serializes it to a JSON string using `JsonSerializer.Serialize`. The resulting JSON string is then printed to the console.
118+
```copilot-prompt
119+
Generate code to use System.Text.Json to serialize an object to a JSON string.
120+
The object contains the following fields: FirstName (string), Lastname (string), Age (int).
121+
Provide example output.
164122
```
165123

166-
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.
167-
168-
> [!NOTE]
169-
> 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.
170-
171-
:::image type="content" source="./media/serialize-json-using-github-copilot.gif" alt-text="Animated screenshot that shows using GitHub Copilot Chat in Visual Studio to serialize an object to a JSON string." lightbox="./media/serialize-json-using-github-copilot.gif":::
172-
173-
For more information, see:
124+
GitHub Copilot is powered by AI, so surprises and mistakes are possible. For more information, see [Copilot FAQs](https://aka.ms/copilot-general-use-faqs).
174125

175-
* [GitHub Copilot Trust Center](https://resources.github.com/copilot-trust-center/)
176-
* [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states)
177-
* [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview)
126+
Learn more about [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states) and [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview).

‎docs/standard/serialization/system-text-json/media/deserialize-json-using-github-copilot.gif

-7.35 MB
Binary file not shown.

‎docs/standard/serialization/system-text-json/media/migrate-newtonsoft-json-using-github-copilot.gif

-4.08 MB
Binary file not shown.

‎docs/standard/serialization/system-text-json/media/serialize-json-using-github-copilot.gif

-2.55 MB
Binary file not shown.

‎docs/standard/serialization/system-text-json/migrate-from-newtonsoft.md

Lines changed: 4 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -633,16 +633,11 @@ Newtonsoft parses `NaN`, `Infinity`, and `-Infinity` JSON string tokens. With Sy
633633

634634
## Use GitHub Copilot to migrate
635635

636-
You can get coding help from GitHub Copilot to convert your code within your IDE.
637-
638-
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 help migrate your `Newtonsoft.Json` code to use `System.Text.Json`. Submit your question and the code to convert as a prompt in the copilot chat window, as in the following example.
639-
640-
> [!NOTE]
641-
> 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).
636+
You can get coding help from GitHub Copilot to migrate your code from `Newtonsoft.Json` to `System.Text.Json` within your IDE. You can customize the prompt per your requirements.
642637

643638
**Example prompt for Copilot Chat**
644639

645-
```
640+
```copilot-prompt
646641
convert the following code to use System.Text.Json
647642
Product product = new Product();
648643
@@ -655,50 +650,11 @@ string output = JsonConvert.SerializeObject(product);
655650
Console.WriteLine(output);
656651
```
657652

658-
**Example Copilot Chat response**
659-
660-
```output
661-
To convert the code to use System.Text.Json, you can use the JsonSerializer class. Here's the updated code:
662-
using System;
663-
using System.Text.Json;
664-
665-
public class Product
666-
{
667-
public string Name { get; set; }
668-
public DateTime ExpiryDate { get; set; }
669-
public decimal Price { get; set; }
670-
public string[] Sizes { get; set; }
671-
}
672-
673-
public class Program
674-
{
675-
public static void Main()
676-
{
677-
Product product = new Product();
678-
679-
product.Name = "Apple";
680-
product.ExpiryDate = new DateTime(2024, 08, 08);
681-
product.Price = 3.99M;
682-
product.Sizes = new string[] { "Small", "Medium", "Large" };
683-
684-
string output = JsonSerializer.Serialize(product);
685-
Console.WriteLine(output);
686-
}
687-
}
688-
This code uses System.Text.Json.JsonSerializer.Serialize to convert the Product object to a JSON string.
689-
```
690-
691-
Note that your results might be different from what is shown in these 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.
692-
693-
:::image type="content" source="./media/migrate-newtonsoft-json-using-github-copilot.gif" alt-text="Animated screenshot that shows using GitHub Copilot Chat in Visual Studio to migrate from newtonsoft" lightbox="./media/migrate-newtonsoft-json-using-github-copilot.gif":::
653+
GitHub Copilot is powered by AI, so surprises and mistakes are possible. For more information, see [Copilot FAQs](https://aka.ms/copilot-general-use-faqs).
694654

695-
You can use chat features, such as [slash commands, references, and threads](/visualstudio/ide/copilot-chat-context), to set intent and get better answers with scoped context.
696-
For example, if your code file `filename` is open in the IDE, you can [reference the file](/visualstudio/ide/copilot-chat-context#reference-a-file) in your prompt to Copilot Chat with "convert `#filename` to use `System.Text.Json`". Or you can [reference the solution](/visualstudio/ide/copilot-chat-context#reference-the-entire-solution) with "convert `@workspace` to use `System.Text.Json`" in the chat window or in inline chat.
655+
Learn more about [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states) and [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview).
697656

698657
## Additional resources
699658

700659
* [System.Text.Json overview](overview.md)
701660
* [How to serialize and deserialize JSON](how-to.md)
702-
* [GitHub Copilot Trust Center](https://resources.github.com/copilot-trust-center/)
703-
* [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states)
704-
* [GitHub Copilot in VS Code](https://code.visualstudio.com/docs/copilot/overview)

0 commit comments

Comments
 (0)