docs: Add samples on how to integrate YeSql.Net with plug-ins

.github/workflows/dotnetcore.yml

@@ -24,4 +24,8 @@ jobs:
     - name: Test 
       run: |
        dotnet test ./tests/YeSql.Net.Tests.csproj
-       dotnet test ./samples/Example.AspNetCore.Tests/Example.AspNetCore.Tests.csproj
+       dotnet test ./samples/Example.AspNetCore.Tests/Example.AspNetCore.Tests.csproj
+       dotnet build ./samples/Example.PluginApp/Plugins/EmployeePlugin/PluginApp.EmployeePlugin.csproj
+       dotnet build ./samples/Example.PluginApp/Plugins/UserPlugin/PluginApp.UserPlugin.csproj
+       dotnet build ./samples/Example.PluginApp/Plugins/HelloPlugin/PluginApp.HelloPlugin.csproj
+       dotnet test ./samples/Example.PluginApp/Test/PluginApp.Host.Tests.csproj

Directory.Packages.props

@@ -3,9 +3,14 @@
     <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
   </PropertyGroup>
   <ItemGroup>
+    <PackageVersion Include="YeSql.Net" Version="0.6.0-alpha" />
     <PackageVersion Include="CopySqlFilesToOutputDirectory" Version="0.2.0-alpha" />
     <PackageVersion Include="CopySqlFilesToPublishDirectory" Version="0.1.0-alpha" />
+    <PackageVersion Include="CPlugin.Net" Version="1.0.0" />
+    <PackageVersion Include="CPlugin.Net.Attributes" Version="1.0.0" />
+    <PackageVersion Include="DotEnv.Core" Version="3.0.0" />
     <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="7.0.10" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="7.0.0" />
     <PackageVersion Include="Swashbuckle.AspNetCore" Version="6.5.0" />
     <PackageVersion Include="IsExternalInit" Version="1.0.3" />
     <PackageVersion Include="Microsoft.AspNetCore.Mvc.Testing" Version="7.0.3" />
@@ -16,4 +21,4 @@
     <PackageVersion Include="NUnit.Analyzers" Version="3.5.0" />
     <PackageVersion Include="coverlet.msbuild" Version="6.0.0" />
   </ItemGroup>
-</Project>
+</Project>

samples/Example.PluginApp/Contracts/IPluginStartup.cs

@@ -0,0 +1,8 @@
+using Microsoft.Extensions.DependencyInjection;
+
+namespace PluginApp.Contracts;
+
+public interface IPluginStartup
+{
+    void ConfigureServices(IServiceCollection services);
+}

samples/Example.PluginApp/Contracts/PluginApp.Contracts.csproj

@@ -0,0 +1,12 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <LangVersion>latest</LangVersion>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
+  </ItemGroup>
+
+</Project>

samples/Example.PluginApp/Host/.env

@@ -0,0 +1,5 @@
+PLUGINS="
+	PluginApp.EmployeePlugin.dll
+	PluginApp.UserPlugin.dll
+	PluginApp.HelloPlugin.dll
+"

samples/Example.PluginApp/Host/PluginApp.Host.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="DotEnv.Core" />
+    <PackageReference Include="CopySqlFilesToOutputDirectory" />
+    <PackageReference Include="CPlugin.Net" />
+    <PackageReference Include="CPlugin.Net.Attributes" />
+    <PackageReference Include="Microsoft.AspNetCore.OpenApi" />
+    <PackageReference Include="Swashbuckle.AspNetCore" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\src\YeSql.Net.csproj" />
+    <ProjectReference Include="..\Contracts\PluginApp.Contracts.csproj" />
+  </ItemGroup>
+
+</Project>

samples/Example.PluginApp/Host/Program.cs

@@ -0,0 +1,62 @@
+using CPlugin.Net;
+using DotEnv.Core;
+using PluginApp.Contracts;
+using System.Reflection;
+using YeSql.Net;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Load .env file.
+new EnvLoader().Load();
+
+// Load plugins from the .env file.
+var envConfiguration = new CPluginEnvConfiguration();
+PluginLoader.Load(envConfiguration);
+
+// Add services to the container.
+var startups = TypeFinder.FindSubtypesOf<IPluginStartup>();
+foreach (IPluginStartup startup in startups)
+    startup.ConfigureServices(builder.Services);
+
+// Adds the plugin assemblies as part of the application.
+// Allows to register controllers of each plugin.
+var mvcBuilder = builder.Services.AddControllers();
+foreach (Assembly assembly in PluginLoader.Assemblies)
+    mvcBuilder.AddApplicationPart(assembly);
+
+var sqlLoader = new YeSqlLoader();
+// Load SQL files from host application.
+var sqlStatements = sqlLoader.Load();
+
+// Load SQL files from plugins.
+// Not all plugins need to have SQL files.
+var directories = envConfiguration
+    .GetPluginFiles()
+    .Select(Path.GetDirectoryName)
+    .ToArray();
+sqlLoader.LoadFromDirectories(directories);
+
+builder.Services.AddSingleton(sqlStatements);
+
+// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+
+var app = builder.Build();
+
+// Configure the HTTP request pipeline.
+if (app.Environment.IsDevelopment())
+{
+    app.UseSwagger();
+    app.UseSwaggerUI();
+}
+
+app.UseHttpsRedirection();
+
+app.UseAuthorization();
+
+app.MapControllers();
+
+app.Run();
+
+public partial class Program { }

samples/Example.PluginApp/Host/Properties/launchSettings.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "iisSettings": {
+    "windowsAuthentication": false,
+    "anonymousAuthentication": true,
+    "iisExpress": {
+      "applicationUrl": "http://localhost:40859",
+      "sslPort": 44325
+    }
+  },
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "http://localhost:5240",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "https://localhost:7264;http://localhost:5240",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "IIS Express": {
+      "commandName": "IISExpress",
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

samples/Example.PluginApp/Host/SqlController.cs

@@ -0,0 +1,13 @@
+using Microsoft.AspNetCore.Mvc;
+using YeSql.Net;
+
+namespace PluginApp.Host;
+
+[Route("api/[controller]")]
+[ApiController]
+public class SqlController : ControllerBase
+{
+    [HttpGet("OrderSql")]
+    public string GetOrderSql(IYeSqlCollection sqlCollection)
+        => sqlCollection["GetOrders"];
+}

samples/Example.PluginApp/Host/sample.sql

@@ -0,0 +1,2 @@
+-- name: GetOrders
+SELECT * FROM [order];

samples/Example.PluginApp/Plugins/Directory.Build.props

@@ -0,0 +1,21 @@
+<Project>
+  <!-- Import global properties from root directory. -->
+  <Import Project="..\..\..\Directory.Build.props" />
+  <PropertyGroup>
+    <Configuration Condition="$(Configuration) == ''">Debug</Configuration>
+    <ProjectRootDir>$([MSBuild]::GetDirectoryNameOfFileAbove($(MSBuildThisFileDirectory), 'YeSql.Net.Examples.sln'))</ProjectRootDir>
+    <OutDir>$(ProjectRootDir)/Example.PluginApp/Host/bin/$(Configuration)/$(TargetFramework)/plugins/$(MSBuildProjectName)</OutDir>
+    <EnableDynamicLoading>true</EnableDynamicLoading>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="$(ProjectRootDir)/Example.PluginApp/Contracts/PluginApp.Contracts.csproj">
+      <Private>false</Private>
+      <ExcludeAssets>runtime</ExcludeAssets>
+    </ProjectReference>
+    <PackageReference Include="CPlugin.Net.Attributes" ExcludeAssets="runtime" />
+    <PackageReference Include="YeSql.Net" ExcludeAssets="runtime" />
+    <PackageReference Include="CopySqlFilesToOutputDirectory" />
+  </ItemGroup>
+
+</Project>

samples/Example.PluginApp/Plugins/EmployeePlugin/EmployeeSqlController.cs

@@ -0,0 +1,12 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace PluginApp.EmployeePlugin;
+
+[Route("api/[controller]")]
+[ApiController]
+public class EmployeeSqlController : ControllerBase
+{
+    [HttpGet]
+    public string GetSqlCode(EmployeeSqlService service)
+        => service.GetSqlCode();
+}

samples/Example.PluginApp/Plugins/EmployeePlugin/EmployeeSqlService.cs

@@ -0,0 +1,9 @@
+using YeSql.Net;
+
+namespace PluginApp.EmployeePlugin;
+
+public class EmployeeSqlService(IYeSqlCollection sqlCollection)
+{
+    public string GetSqlCode()
+        => sqlCollection["GetEmployees"];
+}

samples/Example.PluginApp/Plugins/EmployeePlugin/PluginApp.EmployeePlugin.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+    <LangVersion>latest</LangVersion>
+    <NoDefaultLaunchSettingsFile>true</NoDefaultLaunchSettingsFile>
+  </PropertyGroup>
+
+</Project>

samples/Example.PluginApp/Plugins/EmployeePlugin/PluginStartup.cs

@@ -0,0 +1,15 @@
+using CPlugin.Net;
+using PluginApp.Contracts;
+using PluginApp.EmployeePlugin;
+
+[assembly: Plugin(typeof(PluginStartup))]
+
+namespace PluginApp.EmployeePlugin;
+
+public class PluginStartup : IPluginStartup
+{
+    public void ConfigureServices(IServiceCollection services)
+    {
+        services.AddTransient<EmployeeSqlService>();
+    }
+}

samples/Example.PluginApp/Plugins/EmployeePlugin/employee.sql

@@ -0,0 +1,2 @@
+-- name: GetEmployees
+SELECT * FROM [employee];

samples/Example.PluginApp/Plugins/HelloPlugin/HelloController.cs

@@ -0,0 +1,12 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace PluginApp.HelloPlugin;
+
+[Route("api/[controller]")]
+[ApiController]
+public class HelloController : ControllerBase
+{
+    [HttpGet]
+    public string Greet(HelloService service)
+        => service.Greet();
+}

samples/Example.PluginApp/Plugins/HelloPlugin/HelloService.cs

@@ -0,0 +1,7 @@
+namespace PluginApp.HelloPlugin;
+
+public class HelloService
+{
+    public string Greet()
+        => "Hello World!";
+}

samples/Example.PluginApp/Plugins/HelloPlugin/PluginApp.HelloPlugin.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+    <LangVersion>latest</LangVersion>
+    <NoDefaultLaunchSettingsFile>true</NoDefaultLaunchSettingsFile>
+  </PropertyGroup>
+
+</Project>

samples/Example.PluginApp/Plugins/HelloPlugin/PluginStartup.cs

@@ -0,0 +1,15 @@
+using CPlugin.Net;
+using PluginApp.Contracts;
+using PluginApp.HelloPlugin;
+
+[assembly: Plugin(typeof(PluginStartup))]
+
+namespace PluginApp.HelloPlugin;
+
+public class PluginStartup : IPluginStartup
+{
+    public void ConfigureServices(IServiceCollection services)
+    {
+        services.AddTransient<HelloService>();
+    }
+}

samples/Example.PluginApp/Plugins/UserPlugin/PluginApp.UserPlugin.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <OutputType>Library</OutputType>
+    <LangVersion>latest</LangVersion>
+    <NoDefaultLaunchSettingsFile>true</NoDefaultLaunchSettingsFile>
+  </PropertyGroup>
+
+</Project>

samples/Example.PluginApp/Plugins/UserPlugin/PluginStartup.cs

@@ -0,0 +1,15 @@
+using CPlugin.Net;
+using PluginApp.Contracts;
+using PluginApp.UserPlugin;
+
+[assembly: Plugin(typeof(PluginStartup))]
+
+namespace PluginApp.UserPlugin;
+
+public class PluginStartup : IPluginStartup
+{
+    public void ConfigureServices(IServiceCollection services)
+    {
+        services.AddTransient<UserSqlService>();
+    }
+}

samples/Example.PluginApp/Plugins/UserPlugin/UserSqlController.cs

@@ -0,0 +1,12 @@
+using Microsoft.AspNetCore.Mvc;
+
+namespace PluginApp.UserPlugin;
+
+[Route("api/[controller]")]
+[ApiController]
+public class UserSqlController : ControllerBase
+{
+    [HttpGet]
+    public string GetSqlCode(UserSqlService service)
+        => service.GetSqlCode();
+}

samples/Example.PluginApp/Plugins/UserPlugin/UserSqlService.cs

@@ -0,0 +1,9 @@
+using YeSql.Net;
+
+namespace PluginApp.UserPlugin;
+
+public class UserSqlService(IYeSqlCollection sqlCollection)
+{
+    public string GetSqlCode()
+        => sqlCollection["GetUsers"];
+}

samples/Example.PluginApp/Plugins/UserPlugin/user.sql

@@ -0,0 +1,2 @@
+-- name: GetUsers
+SELECT * FROM [user];

samples/Example.PluginApp/Test/GlobalUsings.cs

@@ -0,0 +1,4 @@
+global using NUnit.Framework;
+global using FluentAssertions;
+global using Microsoft.AspNetCore.Mvc.Testing;
+global using System.Net;