Update documentation

masesgroup · Oct 14, 2023 · 67facf3 · 67facf3
1 parent d58ee07
commit 67facf3
Show file tree

Hide file tree

Showing 7 changed files with 102 additions and 25 deletions.
diff --git a/src/documentation/articles/serialization.md b/src/documentation/articles/serialization.md
@@ -164,3 +164,94 @@ public class CustomSerDes<T> : KNetSerDes<T>
 
 > **IMPORTANT NOTE**: the type applied in the previous properties of `KafkaDbContext` shall be a generic type definition, [Entity Framework Core](https://learn.microsoft.com/it-it/ef/core/) provider for [Apache Kafka](https://kafka.apache.org/) will apply the right generic type when needed.
 
+## **Avro** serialization
+
+With package [MASES.EntityFrameworkCore.KNet.Serialization.Avro](https://www.nuget.org/packages/MASES.EntityFrameworkCore.KNet.Serialization.Avro/) an user can choose two different Avro serializers:
+The engine comes with two different encoders:
+- Binary: `KEFCoreSerDesAvroBinary`
+- Json: `KEFCoreSerDesAvroJson`
+
+### Avro schema
+
+The following schema is the default used from the engine and can be registered in Apache Schema registry so other applications can use it to extract the data stored in the topics:
+
+```json
+{
+	"namespace": "MASES.EntityFrameworkCore.KNet.Serialization.Avro.Storage",
+	"type": "record",
+	"name": "AvroValueContainer",
+	"doc": "Represents the storage container type to be used from KEFCore",
+	"fields": [
+		{
+			"name": "EntityName",
+			"type": "string"
+		},
+		{
+			"name": "ClrType",
+			"type": "string"
+		},
+		{
+			"name": "Data",
+			"type": {
+				"type": "array",
+				"items": {
+					"namespace": "MASES.EntityFrameworkCore.KNet.Serialization.Avro.Storage",
+					"type": "record",
+					"name": "PropertyDataRecord",
+					"doc": "Represents the single container for Entity properties stored in AvroValueContainer and used from KEFCore",
+					"fields": [
+						{
+							"name": "PropertyIndex",
+							"type": "int"
+						},
+						{
+							"name": "PropertyName",
+							"type": "string"
+						},
+						{
+							"name": "ClrType",
+							"type": "string"
+						},
+						{
+							"name": "Value",
+							"type": [
+								"null",
+								"boolean",
+								"int",
+								"long",
+								"float",
+								"double",
+								"string"
+							]
+						}
+					]
+				}
+			}
+		}
+	]
+}
+```
+The extension converted this schema into code to speedup the exection of serialization/deserialization operations.
+
+### How to use Avro 
+
+`KafkaDbContext` contains three properties can be used to override the default types:
+- **KeySerializationType**: Leave this value untouched, till now the engine uses the default serializer
+- **ValueSerializationType**: set this value to `KEFCoreSerDesAvroBinary<>` or `KEFCoreSerDesAvroJson<>`
+- **ValueContainerType**: set this value to `AvroValueContainer<>`
+
+An example is:
+
+```C#
+using (context = new BloggingContext()
+{
+    BootstrapServers = "KAFKA-SERVER:9092",
+    ApplicationId = "MyAppid",
+    DbName = "MyDBName",
+    ValueContainerType = typeof(AvroValueContainer<>),
+    ValueSerializationType = UseAvroBinary ? typeof(KEFCoreSerDesAvroBinary<>) : typeof(KEFCoreSerDesAvroJson<>),
+})
+{
+	// execute stuff here
+}
+```
diff --git a/...re.SerDes.Avro/AvroSerializationHelper.cs → ....Avro.Compiler/AvroSerializationHelper.cs b/...re.SerDes.Avro/AvroSerializationHelper.cs → ....Avro.Compiler/AvroSerializationHelper.cs
diff --git a/....Avro/KEFCore.SerDes.Avro.Compiler.csproj → ...piler/KEFCore.SerDes.Avro.Compiler.csproj b/....Avro/KEFCore.SerDes.Avro.Compiler.csproj → ...piler/KEFCore.SerDes.Avro.Compiler.csproj
@@ -13,16 +13,6 @@
 		<Nullable>enable</Nullable>
 		<GeneratePackageOnBuild>false</GeneratePackageOnBuild>
 	</PropertyGroup>
-	<ItemGroup>
-	  <Compile Remove="Generated\**" />
-	  <EmbeddedResource Remove="Generated\**" />
-	  <None Remove="Generated\**" />
-	</ItemGroup>
-	<ItemGroup>
-	  <Compile Remove="AvroValueContainer.cs" />
-	  <Compile Remove="KEFCoreSerDes.AvroBinary.cs" />
-	  <Compile Remove="KEFCoreSerDes.AvroJson.cs" />
-	</ItemGroup>
 
 	<ItemGroup>
 		<PackageReference Include="Apache.Avro" Version="1.11.3" />

diff --git a/src/net/KEFCore.SerDes.Avro/Program.cs → ...t/KEFCore.SerDes.Avro.Compiler/Program.cs b/src/net/KEFCore.SerDes.Avro/Program.cs → ...t/KEFCore.SerDes.Avro.Compiler/Program.cs
diff --git a/src/net/KEFCore.SerDes.Avro/KEFCore.SerDes.Avro.csproj b/src/net/KEFCore.SerDes.Avro/KEFCore.SerDes.Avro.csproj
@@ -16,10 +16,6 @@
 		<RunAnalyzersDuringLiveAnalysis>True</RunAnalyzersDuringLiveAnalysis>
 		<RunAnalyzersDuringBuild>False</RunAnalyzersDuringBuild>
 	</PropertyGroup>
-	<ItemGroup>
-	  <Compile Remove="AvroSerializationHelper.cs" />
-	  <Compile Remove="Program.cs" />
-	</ItemGroup>
 
 	<ItemGroup>
 		<Using Include="System.Diagnostics" />

diff --git a/src/net/KEFCore.sln b/src/net/KEFCore.sln
@@ -9,7 +9,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KEFCore.SerDes", "KEFCore.S
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KEFCore.SerDes.Avro", "KEFCore.SerDes.Avro\KEFCore.SerDes.Avro.csproj", "{87EB9CF6-D275-460F-B3F5-A5DED0E40196}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KEFCore.SerDes.Avro.Compiler", "KEFCore.SerDes.Avro\KEFCore.SerDes.Avro.Compiler.csproj", "{19F6B000-2C24-4431-8F39-DBF79BFD98F5}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KEFCore.SerDes.Avro.Compiler", "KEFCore.SerDes.Avro.Compiler\KEFCore.SerDes.Avro.Compiler.csproj", "{1E2A2989-7F4C-4651-907F-BCED5E8FA717}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -29,10 +29,10 @@ Global
 		{87EB9CF6-D275-460F-B3F5-A5DED0E40196}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{87EB9CF6-D275-460F-B3F5-A5DED0E40196}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{87EB9CF6-D275-460F-B3F5-A5DED0E40196}.Release|Any CPU.Build.0 = Release|Any CPU
-		{19F6B000-2C24-4431-8F39-DBF79BFD98F5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{19F6B000-2C24-4431-8F39-DBF79BFD98F5}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{19F6B000-2C24-4431-8F39-DBF79BFD98F5}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{19F6B000-2C24-4431-8F39-DBF79BFD98F5}.Release|Any CPU.Build.0 = Release|Any CPU
+		{1E2A2989-7F4C-4651-907F-BCED5E8FA717}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{1E2A2989-7F4C-4651-907F-BCED5E8FA717}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{1E2A2989-7F4C-4651-907F-BCED5E8FA717}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{1E2A2989-7F4C-4651-907F-BCED5E8FA717}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

diff --git a/test/KEFCore.Test.sln b/test/KEFCore.Test.sln
@@ -21,7 +21,7 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KEFCore.SerDes.Avro", "..\s
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KEFCore.Benchmark.Avro.Test", "KEFCore.Benchmark.Avro.Test\KEFCore.Benchmark.Avro.Test.csproj", "{40D1001C-EC50-4994-BE40-F410DB20AF4F}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KEFCore.SerDes.Avro.Compiler", "..\src\net\KEFCore.SerDes.Avro\KEFCore.SerDes.Avro.Compiler.csproj", "{687F7AED-70E0-433C-AF89-89F2878EE106}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KEFCore.SerDes.Avro.Compiler", "..\src\net\KEFCore.SerDes.Avro.Compiler\KEFCore.SerDes.Avro.Compiler.csproj", "{BED3DF6D-B60E-486D-96E9-AD069D0600D2}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -57,10 +57,10 @@ Global
 		{40D1001C-EC50-4994-BE40-F410DB20AF4F}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{40D1001C-EC50-4994-BE40-F410DB20AF4F}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{40D1001C-EC50-4994-BE40-F410DB20AF4F}.Release|Any CPU.Build.0 = Release|Any CPU
-		{687F7AED-70E0-433C-AF89-89F2878EE106}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{687F7AED-70E0-433C-AF89-89F2878EE106}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{687F7AED-70E0-433C-AF89-89F2878EE106}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{687F7AED-70E0-433C-AF89-89F2878EE106}.Release|Any CPU.Build.0 = Release|Any CPU
+		{BED3DF6D-B60E-486D-96E9-AD069D0600D2}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{BED3DF6D-B60E-486D-96E9-AD069D0600D2}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{BED3DF6D-B60E-486D-96E9-AD069D0600D2}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{BED3DF6D-B60E-486D-96E9-AD069D0600D2}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -73,7 +73,7 @@ Global
 		{C8FAF4B6-796E-40C5-990E-A1308306C1F2} = {B35B16BB-890F-4385-AB20-7AA4DD6E9C01}
 		{3F5C48E6-02E8-4921-AA1D-24F8F644F67E} = {B35B16BB-890F-4385-AB20-7AA4DD6E9C01}
 		{40D1001C-EC50-4994-BE40-F410DB20AF4F} = {4A0AD520-9BC4-4F92-893B-6F92BBC35BFA}
-		{687F7AED-70E0-433C-AF89-89F2878EE106} = {B35B16BB-890F-4385-AB20-7AA4DD6E9C01}
+		{BED3DF6D-B60E-486D-96E9-AD069D0600D2} = {B35B16BB-890F-4385-AB20-7AA4DD6E9C01}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {36C294ED-9ECE-42AA-8273-31E008749AF3}