Added Sagara.Core.Data.

README.md

@@ -34,6 +34,13 @@ proof-of-concept or bug demonstration applications. It reduces the amount of boi
 [Sagara.Core.Caching docs](src/Sagara.Core.Caching/docs/index.md)
 
 
+## Sagara.Core.Data
+
+[![NuGet Sagara.Core.Data](https://buildstats.info/nuget/Sagara.Core.Data)](https://www.nuget.org/packages/Sagara.Core.Data)
+
+[Sagara.Core.Data docs](src/Sagara.Core.Data/docs/index.md)
+
+
 ## Sagara.Core.Logging.Serilog
 
 [![NuGet Sagara.Core.Logging.Serilog](https://buildstats.info/nuget/Sagara.Core.Logging.Serilog)](https://www.nuget.org/packages/Sagara.Core.Logging.Serilog)

Sagara.Core.sln

@@ -21,6 +21,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Sagara.Core.Logging.Serilog
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sagara.Core.AspNetCore", "src\Sagara.Core.AspNetCore\Sagara.Core.AspNetCore.csproj", "{B14FE614-00CE-497B-BD0E-5A20C3C68343}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Sagara.Core.Data", "src\Sagara.Core.Data\Sagara.Core.Data.csproj", "{6CAA147B-A247-4491-99D7-742D4CF1BCBD}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -43,6 +45,10 @@ Global
 		{B14FE614-00CE-497B-BD0E-5A20C3C68343}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{B14FE614-00CE-497B-BD0E-5A20C3C68343}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{B14FE614-00CE-497B-BD0E-5A20C3C68343}.Release|Any CPU.Build.0 = Release|Any CPU
+		{6CAA147B-A247-4491-99D7-742D4CF1BCBD}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{6CAA147B-A247-4491-99D7-742D4CF1BCBD}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{6CAA147B-A247-4491-99D7-742D4CF1BCBD}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{6CAA147B-A247-4491-99D7-742D4CF1BCBD}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

make_docs.bat

@@ -19,6 +19,11 @@ echo [Sagara.Core.Caching] Generating docs...
 dotnet defaultDocumentation -a "src\Sagara.Core.Caching\bin\Debug\net8.0\Sagara.Core.Caching.dll" -o "src\Sagara.Core.Caching\docs" --ConfigurationFilePath ".\DefaultDocumentation.json"
 echo [Sagara.Core.Caching] Done.
 
+REM Sagara.Core.Data
+echo [Sagara.Core.Data] Generating docs...
+dotnet defaultDocumentation -a "src\Sagara.Core.Data\bin\Debug\net8.0\Sagara.Core.Data.dll" -o "src\Sagara.Core.Data\docs" --ConfigurationFilePath ".\DefaultDocumentation.json"
+echo [Sagara.Core.Data] Done.
+
 REM Sagara.Core.Logging.Serilog
 echo [Sagara.Core.Logging.Serilog] Generating docs...
 dotnet defaultDocumentation -a "src\Sagara.Core.Logging.Serilog\bin\Debug\net8.0\Sagara.Core.Logging.Serilog.dll" -o "src\Sagara.Core.Logging.Serilog\docs" --ConfigurationFilePath ".\DefaultDocumentation.json"

src/Sagara.Core.Data/Models/Entity.cs

@@ -0,0 +1,42 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Sagara.Core.Data.Models;
+
+/// <summary>
+/// <para>Abstract base class for all EF Core entities. It contains common audit properties and the 
+/// timestamp property.</para>
+/// <para>Derive from this class and add an Id property with the desired Id type.</para>
+/// </summary>
+// How else am I supposed to initialize Id? How else am I supposed to allow EF Core to create instances?
+#pragma warning disable CA1012 // Abstract types should not have public constructors
+public abstract class Entity : IEntity
+#pragma warning restore CA1012 // Abstract types should not have public constructors
+{
+    /// <inheritdoc />
+    public DateTime CreateUtc { get; set; }
+
+    /// <inheritdoc />
+    public Guid CreateUserId { get; set; }
+
+    /// <inheritdoc />
+    public DateTime UpdateUtc { get; set; }
+
+    /// <inheritdoc />
+    public Guid UpdateUserId { get; set; }
+
+    /// <inheritdoc />
+    [Timestamp]
+    // Required by EF Core for SQL Server Timestamp functionality.
+#pragma warning disable CA1819 // Properties should not return arrays
+    public byte[] Timestamp { get; set; } = null!;
+#pragma warning restore CA1819 // Properties should not return arrays
+
+    /// <summary>
+    /// Default .ctor. Initializes the Id and sets <see cref="CreateUtc"/> and <see cref="UpdateUtc"/>
+    /// to the current UTC date/time.
+    /// </summary>
+    public Entity()
+    {
+        EntityHelper.InitializeDates(this);
+    }
+}

src/Sagara.Core.Data/Models/EntityHelper.cs

@@ -0,0 +1,20 @@
+namespace Sagara.Core.Data.Models;
+
+/// <summary>
+/// Methods to help with <see cref="Entity"/> objects.
+/// </summary>
+internal static class EntityHelper
+{
+    /// <summary>
+    /// Common method to initialize the CreateUtc and UpdateUtc properties on classes that
+    /// implement <see cref="IEntity"/>.
+    /// </summary>
+    /// <param name="entity">The instance to update.</param>
+    public static void InitializeDates(IEntity entity)
+    {
+        var utcNow = DateTime.UtcNow;
+
+        entity.CreateUtc = utcNow;
+        entity.UpdateUtc = utcNow;
+    }
+}

src/Sagara.Core.Data/Models/GuidIdEntity.cs

@@ -0,0 +1,29 @@
+using System.ComponentModel.DataAnnotations.Schema;
+
+namespace Sagara.Core.Data.Models;
+
+/// <summary>
+/// Abstract base class for all EF Core entities. It contains common audit properties and the 
+/// timestamp property.
+/// </summary>
+// How else am I supposed to initialize Id? How else am I supposed to allow EF Core to create instances?
+#pragma warning disable CA1012 // Abstract types should not have public constructors
+public abstract class GuidIdEntity : Entity
+#pragma warning restore CA1012 // Abstract types should not have public constructors
+{
+    /// <summary>
+    /// The Entity's unique id (primary key). Must be assigned by the client.
+    /// </summary>
+    [DatabaseGenerated(DatabaseGeneratedOption.None)]
+    public Guid Id { get; set; }
+
+    /// <summary>
+    /// Default .ctor. Initializes the Id and sets <see cref="Entity.CreateUtc"/> and <see cref="Entity.UpdateUtc"/>
+    /// to the current UTC date/time.
+    /// </summary>
+    public GuidIdEntity()
+        : base()
+    {
+        Id = SequentialGuid.GenerateComb();
+    }
+}

src/Sagara.Core.Data/Models/IEntity.cs

@@ -0,0 +1,40 @@
+namespace Sagara.Core.Data.Models;
+
+/// <summary>
+/// Implemented by <see cref="Entity"/>, from which all non-Identity entities derive, and also by
+/// any IdentityUser&lt;T&gt;-derived classes.
+/// </summary>
+public interface IEntity
+{
+    // NOTE: there is no Id property here because, e.g., ASP.NET Core Identity models have their
+    //   own Id property.
+
+    /// <summary>
+    /// UTC date/time when the entity was created.
+    /// </summary>
+    DateTime CreateUtc { get; set; }
+
+    /// <summary>
+    /// UserId of the person who created the entity.
+    /// </summary>
+    Guid CreateUserId { get; set; }
+
+    /// <summary>
+    /// UTC date/time when the entity was last updated.
+    /// </summary>
+    DateTime UpdateUtc { get; set; }
+
+    /// <summary>
+    /// UserId of the person who last updated the entity.
+    /// </summary>
+    Guid UpdateUserId { get; set; }
+
+    /// <summary>
+    /// SQL Server timestamp field, used for concurrency checking.
+    /// </summary>
+    // Justification: Required by EF Core for the SQL Server timestamp to function.
+#pragma warning disable CA1819 // Properties should not return arrays
+    byte[] Timestamp { get; set; }
+#pragma warning restore CA1819 // Properties should not return arrays
+}
+

src/Sagara.Core.Data/README.md

@@ -0,0 +1,5 @@
+# Sagara.Core.Data
+
+Common data access code that I use across many projects.
+
+See the [GitHub repo](https://github.com/jonsagara/Sagara.Core) for documentation.

src/Sagara.Core.Data/Sagara.Core.Data.csproj

@@ -0,0 +1,59 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+	<PropertyGroup>
+		<TargetFramework>net8.0</TargetFramework>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<Nullable>enable</Nullable>
+
+		<!-- NuGet -->
+		<PackageId>Sagara.Core.Data</PackageId>
+		<Description>Common data access functionality using Entity Framework Core.</Description>
+		<PackageLicenseFile>LICENSE.md</PackageLicenseFile>
+		<PackageReadmeFile>README.md</PackageReadmeFile>
+		<!--<PackageIcon>NuGet Package Icon.png</PackageIcon>-->
+		<PackageTags>EntityFrameworkCore SQLServer</PackageTags>
+		<PackageReleaseNotes></PackageReleaseNotes>
+
+		<!-- SourceLink -->
+		<IncludeSymbols>true</IncludeSymbols>
+		<SymbolPackageFormat>snupkg</SymbolPackageFormat>
+		<EmbedUntrackedSources>true</EmbedUntrackedSources>
+		<GenerateDocumentationFile>True</GenerateDocumentationFile>
+
+	</PropertyGroup>
+
+	<ItemGroup>
+		<!--<None Include="..\..\NuGet Package Icon.png" Pack="true" PackagePath="\" />-->
+		<None Include="..\..\LICENSE.md" Pack="true" PackagePath="" />
+		<None Include=".\README.md" Pack="true" PackagePath="\" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.0-rc.1.23419.4" />
+		<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="8.0.0-rc.1.23419.4" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<ProjectReference Include="..\Sagara.Core\Sagara.Core.csproj" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.1.1">
+			<PrivateAssets>all</PrivateAssets>
+			<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+		</PackageReference>
+	</ItemGroup>
+
+	<ItemGroup>
+	  <None Update="README.md">
+	    <PackagePath>\</PackagePath>
+	    <Pack>true</Pack>
+	  </None>
+	</ItemGroup>
+
+	<!-- When running in GitHub Actions, enable deterministic builds for the NuGet package. -->
+	<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
+		<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+	</PropertyGroup>
+
+</Project>

src/Sagara.Core.Data/docs/Sagara.Core.Data.Models.Entity.md

@@ -0,0 +1,110 @@
+#### [Sagara.Core.Data](index.md 'index')
+### [Sagara.Core.Data.Models](index.md#Sagara.Core.Data.Models 'Sagara.Core.Data.Models')
+
+## Entity Class
+
+
+Abstract base class for all EF Core entities. It contains common audit properties and the   
+            timestamp property.  
+
+Derive from this class and add an Id property with the desired Id type.
+
+```csharp
+public abstract class Entity :
+Sagara.Core.Data.Models.IEntity
+```
+
+Inheritance [System.Object](https://docs.microsoft.com/en-us/dotnet/api/System.Object 'System.Object') 🡒 Entity
+
+Derived  
+↳ [GuidIdEntity](Sagara.Core.Data.Models.GuidIdEntity.md 'Sagara.Core.Data.Models.GuidIdEntity')
+
+Implements [IEntity](Sagara.Core.Data.Models.IEntity.md 'Sagara.Core.Data.Models.IEntity')
+### Constructors
+
+<a name='Sagara.Core.Data.Models.Entity.Entity()'></a>
+
+## Entity() Constructor
+
+Default .ctor. Initializes the Id and sets [CreateUtc](Sagara.Core.Data.Models.Entity.md#Sagara.Core.Data.Models.Entity.CreateUtc 'Sagara.Core.Data.Models.Entity.CreateUtc') and [UpdateUtc](Sagara.Core.Data.Models.Entity.md#Sagara.Core.Data.Models.Entity.UpdateUtc 'Sagara.Core.Data.Models.Entity.UpdateUtc')  
+to the current UTC date/time.
+
+```csharp
+public Entity();
+```
+### Properties
+
+<a name='Sagara.Core.Data.Models.Entity.CreateUserId'></a>
+
+## Entity.CreateUserId Property
+
+UserId of the person who created the entity.
+
+```csharp
+public System.Guid CreateUserId { get; set; }
+```
+
+Implements [CreateUserId](Sagara.Core.Data.Models.IEntity.md#Sagara.Core.Data.Models.IEntity.CreateUserId 'Sagara.Core.Data.Models.IEntity.CreateUserId')
+
+#### Property Value
+[System.Guid](https://docs.microsoft.com/en-us/dotnet/api/System.Guid 'System.Guid')
+
+<a name='Sagara.Core.Data.Models.Entity.CreateUtc'></a>
+
+## Entity.CreateUtc Property
+
+UTC date/time when the entity was created.
+
+```csharp
+public System.DateTime CreateUtc { get; set; }
+```
+
+Implements [CreateUtc](Sagara.Core.Data.Models.IEntity.md#Sagara.Core.Data.Models.IEntity.CreateUtc 'Sagara.Core.Data.Models.IEntity.CreateUtc')
+
+#### Property Value
+[System.DateTime](https://docs.microsoft.com/en-us/dotnet/api/System.DateTime 'System.DateTime')
+
+<a name='Sagara.Core.Data.Models.Entity.Timestamp'></a>
+
+## Entity.Timestamp Property
+
+SQL Server timestamp field, used for concurrency checking.
+
+```csharp
+public byte[] Timestamp { get; set; }
+```
+
+Implements [Timestamp](Sagara.Core.Data.Models.IEntity.md#Sagara.Core.Data.Models.IEntity.Timestamp 'Sagara.Core.Data.Models.IEntity.Timestamp')
+
+#### Property Value
+[System.Byte](https://docs.microsoft.com/en-us/dotnet/api/System.Byte 'System.Byte')[[]](https://docs.microsoft.com/en-us/dotnet/api/System.Array 'System.Array')
+
+<a name='Sagara.Core.Data.Models.Entity.UpdateUserId'></a>
+
+## Entity.UpdateUserId Property
+
+UserId of the person who last updated the entity.
+
+```csharp
+public System.Guid UpdateUserId { get; set; }
+```
+
+Implements [UpdateUserId](Sagara.Core.Data.Models.IEntity.md#Sagara.Core.Data.Models.IEntity.UpdateUserId 'Sagara.Core.Data.Models.IEntity.UpdateUserId')
+
+#### Property Value
+[System.Guid](https://docs.microsoft.com/en-us/dotnet/api/System.Guid 'System.Guid')
+
+<a name='Sagara.Core.Data.Models.Entity.UpdateUtc'></a>
+
+## Entity.UpdateUtc Property
+
+UTC date/time when the entity was last updated.
+
+```csharp
+public System.DateTime UpdateUtc { get; set; }
+```
+
+Implements [UpdateUtc](Sagara.Core.Data.Models.IEntity.md#Sagara.Core.Data.Models.IEntity.UpdateUtc 'Sagara.Core.Data.Models.IEntity.UpdateUtc')
+
+#### Property Value
+[System.DateTime](https://docs.microsoft.com/en-us/dotnet/api/System.DateTime 'System.DateTime')

src/Sagara.Core.Data/docs/Sagara.Core.Data.Models.EntityHelper.md

@@ -0,0 +1,31 @@
+#### [Sagara.Core.Data](index.md 'index')
+### [Sagara.Core.Data.Models](index.md#Sagara.Core.Data.Models 'Sagara.Core.Data.Models')
+
+## EntityHelper Class
+
+Methods to help with [Entity](Sagara.Core.Data.Models.Entity.md 'Sagara.Core.Data.Models.Entity') objects.
+
+```csharp
+internal static class EntityHelper
+```
+
+Inheritance [System.Object](https://docs.microsoft.com/en-us/dotnet/api/System.Object 'System.Object') 🡒 EntityHelper
+### Methods
+
+<a name='Sagara.Core.Data.Models.EntityHelper.InitializeDates(Sagara.Core.Data.Models.IEntity)'></a>
+
+## EntityHelper.InitializeDates(IEntity) Method
+
+Common method to initialize the CreateUtc and UpdateUtc properties on classes that  
+implement [IEntity](Sagara.Core.Data.Models.IEntity.md 'Sagara.Core.Data.Models.IEntity').
+
+```csharp
+public static void InitializeDates(Sagara.Core.Data.Models.IEntity entity);
+```
+#### Parameters
+
+<a name='Sagara.Core.Data.Models.EntityHelper.InitializeDates(Sagara.Core.Data.Models.IEntity).entity'></a>
+
+`entity` [IEntity](Sagara.Core.Data.Models.IEntity.md 'Sagara.Core.Data.Models.IEntity')
+
+The instance to update.