From 72c2020f37600fffdbfb4c06611b62fadbc5e8dd Mon Sep 17 00:00:00 2001 From: Ilkay Ilknur Date: Tue, 4 May 2021 17:32:42 +0300 Subject: [PATCH 1/4] json document has been added. --- docs/en/JSON.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/en/JSON.md diff --git a/docs/en/JSON.md b/docs/en/JSON.md new file mode 100644 index 0000000000..fa847ebbb6 --- /dev/null +++ b/docs/en/JSON.md @@ -0,0 +1,51 @@ +# JSON +The ABP Framework provides an abstraction to work with JSON. Having such an abstraction has some benefits; + +* You can write library independent code. Therefore, you can change the underlying library with the minimum effort and code change. +* You can easily change the underlying JSON library (System.Text.Json, Newtonsoft.Json, etc.) by configuring the options. +* You can use the predefined converters defined in the ABP without worrying about the underlying library's internal details. + +> The JSON serialization system is implemented with the [Volo.Abp.Json](https://www.nuget.org/packages/Volo.Abp.Json) NuGet package. Most of the time, you don't need to manually [install it](https://abp.io/package-detail/Volo.Abp.Json) since it comes pre-installed with the [application startup template](Startup-Templates/Application.md). + +## IJsonSerializer + +You can inject `IJsonSerializer` and use it for JSON operations. Here is the available operations in the `IJsonSerializer` interface. + +```csharp +public interface IJsonSerializer +{ + string Serialize(object obj, bool camelCase = true, bool indented = false); + T Deserialize(string jsonString, bool camelCase = true); + object Deserialize(Type type, string jsonString, bool camelCase = true); +} +``` +Usage Example: + +```csharp +public class ProductManager +{ + public IJsonSerializer JsonSerializer { get; } + + public ProductManager(IJsonSerializer jsonSerializer) + { + JsonSerializer = jsonSerializer; + } + + public void SendRequest(Product product) + { + var json= JsonSerializer.Serialize(product); + // Left blank intentionally for demo purposes... + } +} +``` + +## Configuration + +`AbpJsonOptions` type provides options for the JSON operations in the ABP Framework. + +Properties: +* **DefaultDateTimeFormat(`string`)**: Default `DateTime` format. +* **UseHybridSerializer(`bool`)**: True by default. Boolean field indicating whether the ABP Framework uses the hybrid approach or not. If the field is true, it will try to use `System.Json.Text` to handle JSON if it can otherwise use the `Newtonsoft.Json.` +* **Providers(`ITypeList`)**: List of JSON serializer providers implementing the `IJsonSerializerProvider` interface. You can create and add custom serializers to the list, and the ABP Framework uses them automatically. When the `Serialize` or `Deserialize` method is called on the `IJsonSerializer` interface, the ABP Framework calls the `CanHandle` methods of the given providers in reverse order and uses the first provider that returns `true` to do the JSON operation. + + From 0132d95a2ab297f20ef29a856f7ae4a0931f3924 Mon Sep 17 00:00:00 2001 From: Ilkay Ilknur Date: Tue, 4 May 2021 17:32:57 +0300 Subject: [PATCH 2/4] JSON document added to the navigation --- docs/en/docs-nav.json | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/en/docs-nav.json b/docs/en/docs-nav.json index 03c8ff2c4c..6c1755b033 100644 --- a/docs/en/docs-nav.json +++ b/docs/en/docs-nav.json @@ -320,6 +320,10 @@ } ] }, + { + "text": "JSON", + "path": "JSON.md" + }, { "text": "Features", "path": "Features.md" From 939e891ae816551f26abdf47756085b082908e10 Mon Sep 17 00:00:00 2001 From: Ilkay Ilknur Date: Fri, 7 May 2021 12:32:17 +0300 Subject: [PATCH 3/4] duplicate statement removed. --- docs/en/JSON.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/en/JSON.md b/docs/en/JSON.md index fa847ebbb6..33ef889711 100644 --- a/docs/en/JSON.md +++ b/docs/en/JSON.md @@ -2,7 +2,6 @@ The ABP Framework provides an abstraction to work with JSON. Having such an abstraction has some benefits; * You can write library independent code. Therefore, you can change the underlying library with the minimum effort and code change. -* You can easily change the underlying JSON library (System.Text.Json, Newtonsoft.Json, etc.) by configuring the options. * You can use the predefined converters defined in the ABP without worrying about the underlying library's internal details. > The JSON serialization system is implemented with the [Volo.Abp.Json](https://www.nuget.org/packages/Volo.Abp.Json) NuGet package. Most of the time, you don't need to manually [install it](https://abp.io/package-detail/Volo.Abp.Json) since it comes pre-installed with the [application startup template](Startup-Templates/Application.md). @@ -48,4 +47,3 @@ Properties: * **UseHybridSerializer(`bool`)**: True by default. Boolean field indicating whether the ABP Framework uses the hybrid approach or not. If the field is true, it will try to use `System.Json.Text` to handle JSON if it can otherwise use the `Newtonsoft.Json.` * **Providers(`ITypeList`)**: List of JSON serializer providers implementing the `IJsonSerializerProvider` interface. You can create and add custom serializers to the list, and the ABP Framework uses them automatically. When the `Serialize` or `Deserialize` method is called on the `IJsonSerializer` interface, the ABP Framework calls the `CanHandle` methods of the given providers in reverse order and uses the first provider that returns `true` to do the JSON operation. - From 8553bd39b6dd3787f2a1772984b6eb3bd57461c0 Mon Sep 17 00:00:00 2001 From: Ilkay Ilknur Date: Fri, 7 May 2021 13:14:29 +0300 Subject: [PATCH 4/4] AbpSystemTextJsonSerializerOptions description added. --- docs/en/JSON.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/en/JSON.md b/docs/en/JSON.md index 33ef889711..29e93007af 100644 --- a/docs/en/JSON.md +++ b/docs/en/JSON.md @@ -40,6 +40,8 @@ public class ProductManager ## Configuration +### AbpJsonOptions + `AbpJsonOptions` type provides options for the JSON operations in the ABP Framework. Properties: @@ -47,3 +49,12 @@ Properties: * **UseHybridSerializer(`bool`)**: True by default. Boolean field indicating whether the ABP Framework uses the hybrid approach or not. If the field is true, it will try to use `System.Json.Text` to handle JSON if it can otherwise use the `Newtonsoft.Json.` * **Providers(`ITypeList`)**: List of JSON serializer providers implementing the `IJsonSerializerProvider` interface. You can create and add custom serializers to the list, and the ABP Framework uses them automatically. When the `Serialize` or `Deserialize` method is called on the `IJsonSerializer` interface, the ABP Framework calls the `CanHandle` methods of the given providers in reverse order and uses the first provider that returns `true` to do the JSON operation. +### AbpSystemTextJsonSerializerOptions + +`AbpSystemTextJsonSerializerOptions` provides options for `System.Text.Json` usage. + +Properties: + +- **JsonSerializerOptions(`System.Text.Json.JsonSerializerOptions`)**: Global options for System.Text.Json library operations. See [here](https://docs.microsoft.com/en-us/dotnet/api/system.text.json.jsonserializeroptions) for reference. +- **UnsupportedTypes(`ITypeList`)**: List of the unsupported types. You can add types of the unsupported types to the list and, the hybrid JSON serializer automatically uses the `Newtonsoft.Json` library instead of `System.Text.Json`. +