.Net Samples Restructuring - Phase 2 (microsoft#6005)

## Phase 2 - Sample Restructuring - Removal of Examples numbering - Decomposing `KernelSyntaxExamples` into meaningful Feature base folders within `Concepts`. - Update current sample projects to use `sample` centric `InternalUtilities` reducing code repetition - Update SDK projects type to be correctly idenfified as xUnit Test projects - Update projects to be implicit using friendly, reducing considerably the extra lines of code for every sample. - Decomposing `Concepts\AgentSyntax` into `Concepts\Agents` - Decomposing `Concepts\AgentSyntax\GettingStarted` into a new root dedicated `GettingStartedWithAgents`
glahaye · Apr 29, 2024 · c545c7d · c545c7d
1 parent 1c77ad2
commit c545c7d
Show file tree

Hide file tree

Showing 214 changed files with 921 additions and 2,885 deletions.
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,16 +5,16 @@
       // Use IntelliSense to find out which attributes exist for C# debugging
       // Use hover for the description of the existing attributes
       // For further information visit https://github.com/OmniSharp/omnisharp-vscode/blob/master/debugger-launchjson.md
-      "name": ".NET Core Launch (dotnet-kernel-syntax-examples)",
+      "name": "C#: Concept Samples",
       "type": "coreclr",
       "request": "launch",
-      "preLaunchTask": "build (KernelSyntaxExamples)",
+      "preLaunchTask": "build (Concepts)",
       // If you have changed target frameworks, make sure to update the program path.
-      "program": "${workspaceFolder}/dotnet/samples/KernelSyntaxExamples/bin/Debug/net6.0/KernelSyntaxExamples.dll",
+      "program": "${workspaceFolder}/dotnet/samples/Concepts/bin/Debug/net6.0/Concepts.dll",
       "args": [
         /*"example0"*/
       ],
-      "cwd": "${workspaceFolder}/dotnet/samples/KernelSyntaxExamples",
+      "cwd": "${workspaceFolder}/dotnet/samples/Concepts",
       // For more information about the 'console' field, see https://aka.ms/VSCode-CS-LaunchJson-Console
       "console": "internalConsole",
       "stopAtEntry": false
@@ -30,16 +30,21 @@
       "type": "python",
       "request": "launch",
       "module": "pytest",
-      "args": [
-        "${file}"
-      ]
+      "args": ["${file}"]
+    },
+    {
+      "name": "C#: HuggingFaceImageToText Demo",
+      "type": "dotnet",
+      "request": "launch",
+      "projectPath": "${workspaceFolder}\\dotnet\\samples\\Demos\\HuggingFaceImageToText.csproj",
+      "launchConfigurationId": "TargetFramework=;HuggingFaceImageToText"
     },
     {
-      "name": "C#: HuggingFaceImageTextExample",
+      "name": "C#: GettingStarted Samples",
       "type": "dotnet",
       "request": "launch",
-      "projectPath": "${workspaceFolder}\\dotnet\\samples\\HuggingFaceImageTextExample\\HuggingFaceImageTextExample.csproj",
-      "launchConfigurationId": "TargetFramework=;HuggingFaceImageTextExample"
+      "projectPath": "${workspaceFolder}\\dotnet\\samples\\GettingStarted\\GettingStarted.csproj",
+      "launchConfigurationId": "TargetFramework=;GettingStarted"
     }
   ]
-}
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -327,12 +327,12 @@
     // ****************
     // Kernel Syntax Examples
     {
-      "label": "build (KernelSyntaxExamples)",
+      "label": "build (Concepts)",
       "command": "dotnet",
       "type": "process",
       "args": [
         "build",
-        "${workspaceFolder}/dotnet/samples/KernelSyntaxExamples/KernelSyntaxExamples.csproj",
+        "${workspaceFolder}/dotnet/samples/Concepts/Concepts.csproj",
         "/property:GenerateFullPaths=true",
         "/consoleloggerparameters:NoSummary",
         "/property:DebugType=portable"
@@ -341,26 +341,26 @@
       "group": "build"
     },
     {
-      "label": "watch (KernelSyntaxExamples)",
+      "label": "watch (Concepts)",
       "command": "dotnet",
       "type": "process",
       "args": [
         "watch",
         "run",
         "--project",
-        "${workspaceFolder}/dotnet/samples/KernelSyntaxExamples/KernelSyntaxExamples.csproj"
+        "${workspaceFolder}/dotnet/samples/Concepts/Concepts.csproj"
       ],
       "problemMatcher": "$msCompile",
       "group": "build"
     },
     {
-      "label": "run (KernelSyntaxExamples)",
+      "label": "run (Concepts)",
       "command": "dotnet",
       "type": "process",
       "args": [
         "run",
         "--project",
-        "${workspaceFolder}/dotnet/samples/KernelSyntaxExamples/KernelSyntaxExamples.csproj",
+        "${workspaceFolder}/dotnet/samples/Concepts/Concepts.csproj",
         "${input:filter}"
       ],
       "problemMatcher": "$msCompile",
@@ -370,7 +370,7 @@
         "panel": "shared",
         "group": "PR-Validate"
       }
-    },
+    }
   ],
   "inputs": [
     {

diff --git a/docs/decisions/0021-json-serializable-custom-types.md b/docs/decisions/0021-json-serializable-custom-types.md
@@ -15,7 +15,7 @@ This ADR aims to simplify the usage of custom types by allowing developers to us
 
 Standardizing on a JSON-serializable type is necessary to allow functions to be described using a JSON Schema within a planner's function manual. Using a JSON Schema to describe a function's input and output types will allow the planner to validate that the function is being used correctly.
 
-Today, use of custom types within Semantic Kernel requires developers to implement a custom `TypeConverter` to convert to/from the string representation of the type. This is demonstrated in [Example60_AdvancedNativeFunctions](https://github.com/microsoft/semantic-kernel/blob/main/dotnet/samples/KernelSyntaxExamples/Example60_AdvancedNativeFunctions.cs#L202C44-L202C44) as seen below:
+Today, use of custom types within Semantic Kernel requires developers to implement a custom `TypeConverter` to convert to/from the string representation of the type. This is demonstrated in [Functions/MethodFunctions_Advanced] as seen below:
 
 ```csharp
     [TypeConverter(typeof(MyCustomTypeConverter))]

diff --git a/docs/decisions/0042-samples-restructure.md b/docs/decisions/0042-samples-restructure.md
@@ -37,7 +37,7 @@ informed:
 
 | Current Folder                       | Proposal                                                            |
 | ------------------------------------ | ------------------------------------------------------------------- |
-| KernelSyntaxExamples/Getting_Started | Move into `Getting Started`                                         |
+| KernelSyntaxExamples/Getting_Started | Move into `GettingStarted`                                          |
 | KernelSyntaxExamples/`Examples??_*`  | Decompose into `Concepts` on multiple conceptual subfolders         |
 | AgentSyntaxExamples                  | Decompose into `Concepts` on `Agents` specific subfolders.          |
 | DocumentationExamples                | Move into `LearnResources` subfolder and rename to `MicrosoftLearn` |

diff --git a/dotnet/Directory.Packages.props b/dotnet/Directory.Packages.props
@@ -23,6 +23,7 @@
     <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.3.0" />
     <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.3.0" />
     <PackageVersion Include="Microsoft.Bcl.TimeProvider" Version="8.0.1" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Debug" Version="8.0.0" />
     <PackageVersion Include="Microsoft.ML.OnnxRuntime" Version="1.17.1" />
     <PackageVersion Include="FastBertTokenizer" Version="0.4.67" />
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="8.0.0" />
@@ -59,6 +60,7 @@
     <PackageVersion Include="System.Threading.Tasks.Dataflow" Version="8.0.0" />
     <PackageVersion Include="Verify.Xunit" Version="23.5.2" />
     <PackageVersion Include="xunit" Version="2.7.0" />
+    <PackageVersion Include="xunit.abstractions" Version="2.0.3" />
     <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.7" />
     <PackageVersion Include="xretry" Version="1.9.0" />
     <PackageVersion Include="coverlet.collector" Version="6.0.2" />

diff --git a/dotnet/SK-dotnet.sln b/dotnet/SK-dotnet.sln
@@ -12,8 +12,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{FA37
 		samples\README.md = samples\README.md
 	EndProjectSection
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "KernelSyntax", "samples\KernelSyntaxExamples\KernelSyntax.csproj", "{47C6F821-5103-431F-B3B8-A2868A68BB78}"
-EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "IntegrationTests", "src\IntegrationTests\IntegrationTests.csproj", "{E4B777A1-28E1-41BE-96AE-7F3EC61FD5D4}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Plugins.Document", "src\Plugins\Plugins.Document\Plugins.Document.csproj", "{F94D1938-9DB7-4B24-9FF3-166DDFD96330}"
@@ -252,17 +250,11 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Functions", "Functions", "{
 	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Agents.OpenAI", "src\Agents\OpenAI\Agents.OpenAI.csproj", "{644A2F10-324D-429E-A1A3-887EAE64207F}"
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Concepts", "Concepts", "{A2E102D2-7015-44CD-B8EF-C56758CD37DE}"
-	ProjectSection(SolutionItems) = preProject
-		samples\Concepts\README.md = samples\Concepts\README.md
-	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Demos", "Demos", "{5D4C0700-BBB5-418F-A7B2-F392B9A18263}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "LearnResources", "samples\LearnResources\LearnResources.csproj", "{B04C26BC-A933-4A53-BE17-7875EB12E012}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "AgentSyntax", "samples\Concepts\AgentSyntax\AgentSyntax.csproj", "{37847DE5-C3B0-41ED-8749-98B9F429B9E5}"
-EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CreateChatGptPlugin", "samples\Demos\CreateChatGptPlugin\Solution\CreateChatGptPlugin.csproj", "{E6204E79-EFBF-499E-9743-85199310A455}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "HomeAutomation", "samples\Demos\HomeAutomation\HomeAutomation.csproj", "{CBEEF941-AEC6-42A4-A567-B5641CEFBB87}"
@@ -273,11 +265,24 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "TelemetryWithAppInsights",
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "GettingStarted", "samples\GettingStarted\GettingStarted.csproj", "{1D98CF16-5156-40F0-91F0-76294B153DB3}"
 EndProject
-Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Tutorials", "Tutorials", "{DA5C4B1B-7194-402D-9B13-0A8A9D8FEE81}"
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "GettingStartedWithAgents", "samples\GettingStartedWithAgents\GettingStartedWithAgents.csproj", "{87DA81FE-112E-4AF5-BEFB-0B91B993F749}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "samples", "samples", "{77E141BA-AF5E-4C01-A970-6C07AC3CD55A}"
 	ProjectSection(SolutionItems) = preProject
-		samples\Tutorials\README.md = samples\Tutorials\README.md
+		src\InternalUtilities\samples\ConfigurationNotFoundException.cs = src\InternalUtilities\samples\ConfigurationNotFoundException.cs
+		src\InternalUtilities\samples\EnumerableExtensions.cs = src\InternalUtilities\samples\EnumerableExtensions.cs
+		src\InternalUtilities\samples\Env.cs = src\InternalUtilities\samples\Env.cs
+		src\InternalUtilities\samples\ObjectExtensions.cs = src\InternalUtilities\samples\ObjectExtensions.cs
+		src\InternalUtilities\samples\PlanExtensions.cs = src\InternalUtilities\samples\PlanExtensions.cs
+		src\InternalUtilities\samples\RepoFiles.cs = src\InternalUtilities\samples\RepoFiles.cs
+		src\InternalUtilities\samples\SamplesInternalUtilities.props = src\InternalUtilities\samples\SamplesInternalUtilities.props
+		src\InternalUtilities\samples\TextOutputHelperExtensions.cs = src\InternalUtilities\samples\TextOutputHelperExtensions.cs
+		src\InternalUtilities\samples\XunitLogger.cs = src\InternalUtilities\samples\XunitLogger.cs
+		src\InternalUtilities\samples\YourAppException.cs = src\InternalUtilities\samples\YourAppException.cs
 	EndProjectSection
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Concepts", "samples\Concepts\Concepts.csproj", "{925B1185-8B58-4E2D-95C9-4CA0BA9364E5}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -291,11 +296,6 @@ Global
 		{A284C7EB-2248-4A75-B112-F5DCDE65410D}.Publish|Any CPU.Build.0 = Publish|Any CPU
 		{A284C7EB-2248-4A75-B112-F5DCDE65410D}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{A284C7EB-2248-4A75-B112-F5DCDE65410D}.Release|Any CPU.Build.0 = Release|Any CPU
-		{47C6F821-5103-431F-B3B8-A2868A68BB78}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{47C6F821-5103-431F-B3B8-A2868A68BB78}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{47C6F821-5103-431F-B3B8-A2868A68BB78}.Publish|Any CPU.ActiveCfg = Release|Any CPU
-		{47C6F821-5103-431F-B3B8-A2868A68BB78}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{47C6F821-5103-431F-B3B8-A2868A68BB78}.Release|Any CPU.Build.0 = Release|Any CPU
 		{E4B777A1-28E1-41BE-96AE-7F3EC61FD5D4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{E4B777A1-28E1-41BE-96AE-7F3EC61FD5D4}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{E4B777A1-28E1-41BE-96AE-7F3EC61FD5D4}.Publish|Any CPU.ActiveCfg = Release|Any CPU
@@ -614,12 +614,6 @@ Global
 		{B04C26BC-A933-4A53-BE17-7875EB12E012}.Publish|Any CPU.Build.0 = Debug|Any CPU
 		{B04C26BC-A933-4A53-BE17-7875EB12E012}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{B04C26BC-A933-4A53-BE17-7875EB12E012}.Release|Any CPU.Build.0 = Release|Any CPU
-		{37847DE5-C3B0-41ED-8749-98B9F429B9E5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
-		{37847DE5-C3B0-41ED-8749-98B9F429B9E5}.Debug|Any CPU.Build.0 = Debug|Any CPU
-		{37847DE5-C3B0-41ED-8749-98B9F429B9E5}.Publish|Any CPU.ActiveCfg = Debug|Any CPU
-		{37847DE5-C3B0-41ED-8749-98B9F429B9E5}.Publish|Any CPU.Build.0 = Debug|Any CPU
-		{37847DE5-C3B0-41ED-8749-98B9F429B9E5}.Release|Any CPU.ActiveCfg = Release|Any CPU
-		{37847DE5-C3B0-41ED-8749-98B9F429B9E5}.Release|Any CPU.Build.0 = Release|Any CPU
 		{E6204E79-EFBF-499E-9743-85199310A455}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{E6204E79-EFBF-499E-9743-85199310A455}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{E6204E79-EFBF-499E-9743-85199310A455}.Publish|Any CPU.ActiveCfg = Debug|Any CPU
@@ -650,13 +644,24 @@ Global
 		{1D98CF16-5156-40F0-91F0-76294B153DB3}.Publish|Any CPU.Build.0 = Debug|Any CPU
 		{1D98CF16-5156-40F0-91F0-76294B153DB3}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{1D98CF16-5156-40F0-91F0-76294B153DB3}.Release|Any CPU.Build.0 = Release|Any CPU
+		{87DA81FE-112E-4AF5-BEFB-0B91B993F749}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{87DA81FE-112E-4AF5-BEFB-0B91B993F749}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{87DA81FE-112E-4AF5-BEFB-0B91B993F749}.Publish|Any CPU.ActiveCfg = Debug|Any CPU
+		{87DA81FE-112E-4AF5-BEFB-0B91B993F749}.Publish|Any CPU.Build.0 = Debug|Any CPU
+		{87DA81FE-112E-4AF5-BEFB-0B91B993F749}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{87DA81FE-112E-4AF5-BEFB-0B91B993F749}.Release|Any CPU.Build.0 = Release|Any CPU
+		{925B1185-8B58-4E2D-95C9-4CA0BA9364E5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{925B1185-8B58-4E2D-95C9-4CA0BA9364E5}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{925B1185-8B58-4E2D-95C9-4CA0BA9364E5}.Publish|Any CPU.ActiveCfg = Debug|Any CPU
+		{925B1185-8B58-4E2D-95C9-4CA0BA9364E5}.Publish|Any CPU.Build.0 = Debug|Any CPU
+		{925B1185-8B58-4E2D-95C9-4CA0BA9364E5}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{925B1185-8B58-4E2D-95C9-4CA0BA9364E5}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
 	EndGlobalSection
 	GlobalSection(NestedProjects) = preSolution
 		{A284C7EB-2248-4A75-B112-F5DCDE65410D} = {831DDCA2-7D2C-4C31-80DB-6BDB3E1F7AE0}
-		{47C6F821-5103-431F-B3B8-A2868A68BB78} = {A2E102D2-7015-44CD-B8EF-C56758CD37DE}
 		{E4B777A1-28E1-41BE-96AE-7F3EC61FD5D4} = {831DDCA2-7D2C-4C31-80DB-6BDB3E1F7AE0}
 		{F94D1938-9DB7-4B24-9FF3-166DDFD96330} = {D6D598DF-C17C-46F4-B2B9-CDE82E2DE132}
 		{689A5041-BAE7-448F-9BDC-4672E96249AA} = {D6D598DF-C17C-46F4-B2B9-CDE82E2DE132}
@@ -733,16 +738,16 @@ Global
 		{91B8BEAF-4ADC-4014-AC6B-C563F41A8DD1} = {6823CD5E-2ABE-41EB-B865-F86EC13F0CF9}
 		{4DFB3897-0319-4DF2-BCFE-E6E0648297D2} = {958AD708-F048-4FAF-94ED-D2F2B92748B9}
 		{644A2F10-324D-429E-A1A3-887EAE64207F} = {6823CD5E-2ABE-41EB-B865-F86EC13F0CF9}
-		{A2E102D2-7015-44CD-B8EF-C56758CD37DE} = {FA3720F1-C99A-49B2-9577-A940257098BF}
 		{5D4C0700-BBB5-418F-A7B2-F392B9A18263} = {FA3720F1-C99A-49B2-9577-A940257098BF}
 		{B04C26BC-A933-4A53-BE17-7875EB12E012} = {FA3720F1-C99A-49B2-9577-A940257098BF}
-		{37847DE5-C3B0-41ED-8749-98B9F429B9E5} = {A2E102D2-7015-44CD-B8EF-C56758CD37DE}
 		{E6204E79-EFBF-499E-9743-85199310A455} = {5D4C0700-BBB5-418F-A7B2-F392B9A18263}
 		{CBEEF941-AEC6-42A4-A567-B5641CEFBB87} = {5D4C0700-BBB5-418F-A7B2-F392B9A18263}
 		{E12E15F2-6819-46EA-8892-73E3D60BE76F} = {5D4C0700-BBB5-418F-A7B2-F392B9A18263}
 		{5C813F83-9FD8-462A-9B38-865CA01C384C} = {5D4C0700-BBB5-418F-A7B2-F392B9A18263}
 		{1D98CF16-5156-40F0-91F0-76294B153DB3} = {FA3720F1-C99A-49B2-9577-A940257098BF}
-		{DA5C4B1B-7194-402D-9B13-0A8A9D8FEE81} = {FA3720F1-C99A-49B2-9577-A940257098BF}
+		{87DA81FE-112E-4AF5-BEFB-0B91B993F749} = {FA3720F1-C99A-49B2-9577-A940257098BF}
+		{77E141BA-AF5E-4C01-A970-6C07AC3CD55A} = {4D3DAE63-41C6-4E1C-A35A-E77BDFC40675}
+		{925B1185-8B58-4E2D-95C9-4CA0BA9364E5} = {FA3720F1-C99A-49B2-9577-A940257098BF}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {FBDC56A3-86AD-4323-AA0F-201E59123B83}

diff --git a/dotnet/samples/Concepts/AgentSyntax/Configuration/ConfigurationException.cs b/dotnet/samples/Concepts/AgentSyntax/Configuration/ConfigurationException.cs
diff --git a/dotnet/samples/Concepts/AgentSyntax/Configuration/TestConfiguration.cs b/dotnet/samples/Concepts/AgentSyntax/Configuration/TestConfiguration.cs