.Net: Move documentation examples from documentation repo into SK repo (#4704)

### Motivation and Context
In order to keep documentation examples up to date, moving them to a
repo where they will actually be built and run.

### Description
Move documentation examples from doc repo to this one.

### Contribution Checklist
- [ ] The code builds clean without any errors or warnings
- [ ] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [ ] All unit tests pass, and I have added new tests where possible
- [ ] I didn't break anyone 😄

Author: glahaye

dotnet/Directory.Packages.props

@@ -13,9 +13,14 @@
     <PackageVersion Include="Markdig" Version="0.34.0" />
     <PackageVersion Include="Handlebars.Net" Version="2.1.4" />
     <PackageVersion Include="JsonSchema.Net.Generation" Version="3.5.1" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker" Version="1.20.1" />
+    <PackageVersion Include="Microsoft.Azure.Functions.Worker.Extensions.Http" Version="3.1.0" />
     <PackageVersion Include="Microsoft.Azure.Kusto.Data" Version="11.3.5" />
+    <PackageVersion Include="Microsoft.Azure.WebJobs.Extensions.OpenApi" Version="1.5.1" />
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="[1.1.0, )" />
     <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="8.0.0" />
+    <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="System.Diagnostics.DiagnosticSource" Version="8.0.0" />
     <PackageVersion Include="System.Linq.Async" Version="6.0.1" />

dotnet/SK-dotnet.sln

@@ -116,15 +116,9 @@ EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "System", "System", "{3CDE10B2-AE8F-4FC4-8D55-92D4AD32E144}"
 	ProjectSection(SolutionItems) = preProject
 		src\InternalUtilities\src\System\EnvExtensions.cs = src\InternalUtilities\src\System\EnvExtensions.cs
-		src\InternalUtilities\src\System\InternalTypeConverter.cs = src\InternalUtilities\src\System\InternalTypeConverter.cs
-		src\InternalUtilities\src\System\TypeConverterFactory.cs = src\InternalUtilities\src\System\TypeConverterFactory.cs
-		src\InternalUtilities\src\System\NonNullCollection.cs = src\InternalUtilities\src\System\NonNullCollection.cs
 	EndProjectSection
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Type", "Type", "{E85EA4D0-BB7E-4DFD-882F-A76EB8C0B8FF}"
-	ProjectSection(SolutionItems) = preProject
-		src\InternalUtilities\src\Type\TypeExtensions.cs = src\InternalUtilities\src\Type\TypeExtensions.cs
-	EndProjectSection
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Plugins.Core", "src\Plugins\Plugins.Core\Plugins.Core.csproj", "{0D0C4DAD-E6BC-4504-AE3A-EEA4E35920C1}"
 EndProject
@@ -197,6 +191,10 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Experimental.Orchestration.
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Experimental.Orchestration.Flow.UnitTests", "src\Experimental\Orchestration.Flow.UnitTests\Experimental.Orchestration.Flow.UnitTests.csproj", "{731CC542-8BE9-42D4-967D-99206EC2B310}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "DocumentationExamples", "samples\DocumentationExamples\DocumentationExamples.csproj", "{A8E0D3B2-49D7-4DF6-BF91-B234C1C5E25D}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CreateChatGptPlugin", "samples\CreateChatGptPlugin\Solution\CreateChatGptPlugin.csproj", "{87AB5AF5-5783-4372-9789-664895E0A2FF}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -460,6 +458,18 @@ Global
 		{731CC542-8BE9-42D4-967D-99206EC2B310}.Publish|Any CPU.Build.0 = Debug|Any CPU
 		{731CC542-8BE9-42D4-967D-99206EC2B310}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{731CC542-8BE9-42D4-967D-99206EC2B310}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A8E0D3B2-49D7-4DF6-BF91-B234C1C5E25D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A8E0D3B2-49D7-4DF6-BF91-B234C1C5E25D}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A8E0D3B2-49D7-4DF6-BF91-B234C1C5E25D}.Publish|Any CPU.ActiveCfg = Debug|Any CPU
+		{A8E0D3B2-49D7-4DF6-BF91-B234C1C5E25D}.Publish|Any CPU.Build.0 = Debug|Any CPU
+		{A8E0D3B2-49D7-4DF6-BF91-B234C1C5E25D}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A8E0D3B2-49D7-4DF6-BF91-B234C1C5E25D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{87AB5AF5-5783-4372-9789-664895E0A2FF}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{87AB5AF5-5783-4372-9789-664895E0A2FF}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{87AB5AF5-5783-4372-9789-664895E0A2FF}.Publish|Any CPU.ActiveCfg = Debug|Any CPU
+		{87AB5AF5-5783-4372-9789-664895E0A2FF}.Publish|Any CPU.Build.0 = Debug|Any CPU
+		{87AB5AF5-5783-4372-9789-664895E0A2FF}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{87AB5AF5-5783-4372-9789-664895E0A2FF}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -528,6 +538,8 @@ Global
 		{B0CE8C69-EC56-4825-94AB-01CA7E8BA55B} = {A2357CF8-3BB9-45A1-93F1-B366C9B63658}
 		{3A4B8F90-3E74-43E0-800C-84F8AA9B5BF3} = {A2357CF8-3BB9-45A1-93F1-B366C9B63658}
 		{731CC542-8BE9-42D4-967D-99206EC2B310} = {A2357CF8-3BB9-45A1-93F1-B366C9B63658}
+		{A8E0D3B2-49D7-4DF6-BF91-B234C1C5E25D} = {FA3720F1-C99A-49B2-9577-A940257098BF}
+		{87AB5AF5-5783-4372-9789-664895E0A2FF} = {FA3720F1-C99A-49B2-9577-A940257098BF}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {FBDC56A3-86AD-4323-AA0F-201E59123B83}

dotnet/samples/CreateChatGptPlugin/.editorconfig

@@ -0,0 +1,2 @@
+[*.cs]
+dotnet_diagnostic.CA1016.severity = none

dotnet/samples/CreateChatGptPlugin/MathPlugin/.gitignore

@@ -0,0 +1,4 @@
+**/bin
+**/obj
+local.settings.json
+azure-function/appsettings.json

dotnet/samples/CreateChatGptPlugin/MathPlugin/README.md

@@ -0,0 +1,54 @@
+# Semantic Kernel OpenAI plugin starter
+
+This project provides starter code to create a OpenAI plugin. It includes the following components:
+
+- An endpoint that serves up an ai-plugin.json file for ChatGPT to discover the plugin
+- A generator that automatically converts prompts into prompt endpoints
+- The ability to add additional native functions as endpoints to the plugin
+
+## Prerequisites
+
+- [.NET 6](https://dotnet.microsoft.com/download/dotnet/8.0) is required to run this starter.
+- [Azure Functions Core Tools](https://www.npmjs.com/package/azure-functions-core-tools) is required to run this starter.
+- Install the recommended extensions
+- [C#](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp)
+- [Semantic Kernel Tools](https://marketplace.visualstudio.com/items?itemName=ms-semantic-kernel.semantic-kernel) (optional)
+
+## Configuring the starter
+
+To configure the starter, you need to provide the following information:
+
+- Define the properties of the plugin in the appsettings.json file.
+- Enter the API key for your AI endpoint in the [local.settings.json](./azure-function/local.settings.json.example) file.
+
+### Using appsettings.json
+
+Configure an OpenAI endpoint
+
+1. Copy [settings.json.openai-example](./azure-function/config-samples/appsettings.json.openai-example) to `./appsettings.json`
+1. Edit the `kernel` object to add your OpenAI endpoint configuration
+1. Edit the `aiPlugin` object to define the properties that get exposed in the ai-plugin.json file
+
+Configure an Azure OpenAI endpoint
+
+1. Copy [settings.json.azure-example](./azure-function/config-samples/appsettings.json.azure-example) to `./appsettings.json`
+1. Edit the `kernel` object to add your Azure OpenAI endpoint configuration
+1. Edit the `aiPlugin` object to define the properties that get exposed in the ai-plugin.json file
+
+### Using local.settings.json
+
+1. Copy [local.settings.json.example](./azure-function/local.settings.json.example) to `./azure-function/local.settings.json`
+1. Edit the `Values` object to add your OpenAI endpoint configuration in the `apiKey` property
+
+## Running the starter
+
+To run the Azure Functions application just hit `F5`.
+
+To build and run the Azure Functions application from a terminal use the following commands:
+
+```powershell
+cd azure-function
+dotnet build
+cd bin/Debug/net8.0
+func host start
+```

dotnet/samples/CreateChatGptPlugin/MathPlugin/azure-function/AIPluginJson.cs

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Net;
+using Microsoft.Azure.Functions.Worker;
+using Microsoft.Azure.Functions.Worker.Http;
+using Models;
+
+public class AIPluginJson
+{
+    [Function("GetAIPluginJson")]
+    public HttpResponseData Run([HttpTrigger(AuthorizationLevel.Anonymous, "get", Route = ".well-known/ai-plugin.json")] HttpRequestData req)
+    {
+        var currentDomain = $"{req.Url.Scheme}://{req.Url.Host}:{req.Url.Port}";
+
+        HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
+        response.Headers.Add("Content-Type", "application/json");
+
+        var appSettings = AppSettings.LoadSettings();
+
+        // serialize app settings to json using System.Text.Json
+        var json = System.Text.Json.JsonSerializer.Serialize(appSettings.AIPlugin);
+
+        // replace {url} with the current domain
+        json = json.Replace("{url}", currentDomain, StringComparison.OrdinalIgnoreCase);
+
+        response.WriteString(json);
+
+        return response;
+    }
+}

dotnet/samples/CreateChatGptPlugin/MathPlugin/azure-function/Directory.Build.props

@@ -0,0 +1,33 @@
+<Project>
+  <PropertyGroup>
+    <!-- Default properties inherited by all projects. Projects can override. -->
+    <RunAnalyzersDuringBuild>true</RunAnalyzersDuringBuild>
+    <EnableNETAnalyzers>true</EnableNETAnalyzers>
+    <AnalysisMode>AllEnabledByDefault</AnalysisMode>
+    <AnalysisLevel>latest</AnalysisLevel>
+    <GenerateDocumentationFile>true</GenerateDocumentationFile>
+    <LangVersion>11</LangVersion>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>disable</ImplicitUsings>
+    <NoWarn>CS1591,CA1852,CA1050</NoWarn> 
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <!-- Disable NuGet packaging by default. Projects can override. -->
+    <IsPackable>disable</IsPackable>
+  </PropertyGroup>
+
+  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
+    <DebugSymbols>true</DebugSymbols>
+    <DebugType>full</DebugType>
+  </PropertyGroup>
+
+  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
+    <DebugType>portable</DebugType>
+  </PropertyGroup>
+
+  <PropertyGroup>
+    <RepoRoot>$([System.IO.Path]::GetDirectoryName($([MSBuild]::GetPathOfFileAbove('.gitignore', '$(MSBuildThisFileDirectory)'))))</RepoRoot>
+  </PropertyGroup>
+
+</Project>

dotnet/samples/CreateChatGptPlugin/MathPlugin/azure-function/Directory.Build.targets

@@ -0,0 +1,25 @@
+<Project>
+  <!-- Direct all packages under 'dotnet' to get versions from Directory.Packages.props -->
+  <!-- using Central Package Management feature -->
+  <!-- https://learn.microsoft.com/en-us/nuget/consume-packages/Central-Package-Management -->
+  <Sdk Name="Microsoft.Build.CentralPackageVersions" Version="2.1.3" />
+
+  <!-- Only run 'dotnet format' on dev machines, Release builds. Skip on GitHub Actions -->
+  <!-- as this runs in its own Actions job. -->
+  <Target Name="DotnetFormatOnBuild" BeforeTargets="Build"
+          Condition=" '$(Configuration)' == 'Release' AND '$(GITHUB_ACTIONS)' == '' ">
+    <Message Text="Running dotnet format" Importance="high" />
+    <Exec Command="dotnet format --no-restore -v diag $(ProjectFileName)" />
+  </Target>
+
+  <Target Name="AddInternalsVisibleTo" BeforeTargets="BeforeCompile">
+    <!-- Handle Add InternalsVisibleTo to any targets that don't support it. -->
+    <ItemGroup Condition="'@(InternalsVisibleTo->Count())' &gt; 0 AND $([MSBuild]::VersionLessThan($(NETCoreSdkVersion), '5.0.0'))">
+      <AssemblyAttribute Include="System.Runtime.CompilerServices.InternalsVisibleTo">
+        <_Parameter1 Condition="'%(InternalsVisibleTo.PublicKey)' != ''">%(InternalsVisibleTo.Identity), PublicKey="%(InternalsVisibleTo.PublicKey)</_Parameter1>
+        <_Parameter1 Condition="'%(InternalsVisibleTo.PublicKey)' == ''">%(InternalsVisibleTo.Identity)</_Parameter1>
+        <_Parameter1_TypeName>System.String</_Parameter1_TypeName>
+      </AssemblyAttribute>
+    </ItemGroup>
+  </Target>
+</Project>

dotnet/samples/CreateChatGptPlugin/MathPlugin/azure-function/Extensions/AIPluginRunner.cs

@@ -0,0 +1,56 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Net;
+using System.Reflection;
+using System.Text.Json;
+using Microsoft.Azure.Functions.Worker.Http;
+using Microsoft.Extensions.Logging;
+using Microsoft.SemanticKernel;
+
+namespace Plugins.AzureFunctions.Extensions;
+
+public class AIPluginRunner
+{
+    private readonly ILogger<AIPluginRunner> _logger;
+    private readonly Kernel _kernel;
+
+    public AIPluginRunner(Kernel kernel, ILoggerFactory loggerFactory)
+    {
+        this._kernel = kernel;
+        this._logger = loggerFactory.CreateLogger<AIPluginRunner>();
+    }
+
+    /// <summary>
+    /// Runs a prompt using the operationID and returns back an HTTP response.
+    /// </summary>
+    /// <param name="req"></param>
+    /// <param name="pluginName"></param>
+    /// <param name="functionName"></param>
+    public async Task<HttpResponseData> RunAIPluginOperationAsync<T>(HttpRequestData req, string pluginName, string functionName)
+    {
+        KernelArguments arguments = ConvertToKernelArguments((await JsonSerializer.DeserializeAsync<T>(req.Body).ConfigureAwait(true))!);
+
+        var response = req.CreateResponse(HttpStatusCode.OK);
+        response.Headers.Add("Content-Type", "text/plain;charset=utf-8");
+        await response.WriteStringAsync(
+            (await this._kernel.InvokeAsync(pluginName, functionName, arguments).ConfigureAwait(false)).ToString()
+        ).ConfigureAwait(false);
+        return response;
+    }
+
+    // Method to convert model to dictionary
+    private static KernelArguments ConvertToKernelArguments<T>(T model)
+    {
+        {
+            var arguments = new KernelArguments();
+            foreach (PropertyInfo property in typeof(T).GetProperties())
+            {
+                if (property.GetValue(model) != null)
+                {
+                    arguments.Add(property.Name, property.GetValue(model));
+                }
+            }
+            return arguments;
+        }
+    }
+}

dotnet/samples/CreateChatGptPlugin/MathPlugin/azure-function/Extensions/KernelBuilderExtensions.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.SemanticKernel;
+using Models;
+
+internal static class KernelBuilderExtensions
+{
+    /// <summary>
+    /// Adds a chat completion service to the list. It can be either an OpenAI or Azure OpenAI backend service.
+    /// </summary>
+    /// <param name="kernelBuilder"></param>
+    /// <param name="kernelSettings"></param>
+    /// <exception cref="ArgumentException"></exception>
+    internal static IServiceCollection WithChatCompletionService(this IServiceCollection kernelBuilder, KernelSettings kernelSettings)
+    {
+        switch (kernelSettings.ServiceType.ToUpperInvariant())
+        {
+            case ServiceTypes.AzureOpenAI:
+                kernelBuilder.AddAzureOpenAIChatCompletion(deploymentName: kernelSettings.DeploymentOrModelId, modelId: kernelSettings.DeploymentOrModelId, endpoint: kernelSettings.Endpoint, apiKey: kernelSettings.ApiKey, serviceId: kernelSettings.ServiceId);
+                break;
+
+            case ServiceTypes.OpenAI:
+                kernelBuilder.AddOpenAIChatCompletion(modelId: kernelSettings.DeploymentOrModelId, apiKey: kernelSettings.ApiKey, orgId: kernelSettings.OrgId, serviceId: kernelSettings.ServiceId);
+                break;
+
+            default:
+                throw new ArgumentException($"Invalid service type value: {kernelSettings.ServiceType}");
+        }
+
+        return kernelBuilder;
+    }
+}