Add README

Author: nogic1008

README.md

@@ -0,0 +1,215 @@
+# T4Sample (How to Use T4 in .NET Core + VSCode)
+
+This is a sample to create a table Entity class using T4.
+
+In Japanese, see also [.NET Core+VS CodeでもT4 テンプレートエンジンでコード生成したい！](https://qiita.com/nogic1008/items/2c4049d43a11e83df15b)
+
+## Environments
+
+- .NET Core 3.0 SDK (Preview 7)
+  - For use ["default implementation of interfaces"](https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/default-interface-members-versions).
+
+- Visual Studio Code
+  - Required: [C# Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp)
+  - Recommended: [T4 Support](https://marketplace.visualstudio.com/items?itemName=zbecknell.t4-support) to highlight T4 Documents.
+
+## What is "T4"?
+
+T4 means "Text Template Transformation Toolkit".
+It is bundled to Visual Studio since 2008.
+
+It is often used for automatic code generation such as table definition classes.
+
+This sample uses [Mono.TextTemplating](https://github.com/mono/t4) which is a T4 implemented by Mono Project.
+
+## Processes
+
+### 1. Create Project
+
+```console
+> dotnet new console
+```
+
+### 2. Add `LangVersion` to .csproj
+
+- Set `LangVersion` to *8.0*.
+
+```diff
+   <PropertyGroup>
++    <LangVersion>8.0</LangVersion>
+     <OutputType>Exe</OutputType>
+     <TargetFramework>netcoreapp3.0</TargetFramework>
+   </PropertyGroup>
+```
+
+### 3. Create Table and Column Entities
+
+- [ColumnInfo.cs](./ColumnInfo.cs)
+- [TableInfo.cs](./TableInfo.cs)
+
+### 4. Install Mono.TextTemplating from NuGet
+
+The program code generated by T4 file depends on this package.
+
+```console
+> dotnet add package Mono.TextTemplating --version 2.0.5
+```
+
+### 5. Install T4 Cli Tool
+
+Add `DotNetCliToolReference` in csproj to use [dotnet-t4-project-tool](https://www.nuget.org/packages/dotnet-t4-project-tool/).
+
+```diff
+  <ItemGroup>
++    <DotNetCliToolReference Include="dotnet-t4-project-tool" Version="2.0.5" />
+     <PackageReference Include="Mono.TextTemplating" Version="2.0.5" />
+   </ItemGroup>
+```
+
+### 6. Add Task to Prebuild and Cleanup
+
+#### Define Target Files
+
+Define `TextTemplate` and `Genarated` using Glob.
+
+```diff
+  <ItemGroup>
+     <DotNetCliToolReference Include="dotnet-t4-project-tool" Version="2.0.5" />
+     <PackageReference Include="Mono.TextTemplating" Version="2.0.5" />
++    <TextTemplate Include="**\*.tt" />
++    <Generated Include="**\*.Generated.cs" />
+   </ItemGroup>
+```
+
+#### Define Prebuild Task
+
+Define Task to run `dotnet t4`.
+
+- `%(TextTemplate.Identity)`
+  - T4 File Paths such as *foo/Template.tt*.
+- `$(RootNameSpace)`
+  - Default Namespace.
+  If you changed the T4 class's namespace, set it exactly.
+- `%(TextTemplate.Filename)`
+  - T4 File Name.
+
+```diff
+   </ItemGroup>
++  <Target Name="TextTemplateTransform" BeforeTargets="BeforeBuild">
++    <Exec WorkingDirectory="$(ProjectDir)" Command="dotnet t4 %(TextTemplate.Identity) -c $(RootNameSpace).%(TextTemplate.Filename) -o %(TextTemplate.Filename).Generated.cs" />
++  </Target>
+```
+
+#### Define Cleanup Task
+
+Define Task to delete `*.Generated.cs`.
+
+```diff
+   </Target>
++  <Target Name="TextTemplateClean" AfterTargets="Clean">
++    <Delete Files="@(Generated)" />
++  </Target>
+```
+
+### 7. Create T4 Interface and define implements
+
+`TransFormText()`, Called by Program to use T4 Classes are defined in *\*.Generated.cs*.
+But \*.Generated.cs is generated just before the build.
+So calling `TransFormText()` will cause a compile error because there is no definition at before build time.
+
+This sample avoids this by using the "default implementation of interfaces".
+
+```csharp
+using System;
+
+namespace T4Sample
+{
+    public interface ITextTemplate
+    {
+        string TransformText() => throw new NotImplementedException();
+    }
+}
+```
+
+### 8. Create T4 Template File & Class
+
+Note that T4 class should be defined with `partial` class.
+
+- [TableEntityTemplate.tt](./TableEntityTemplate.tt)
+- [TableEntityTemplate.cs](./TableEntityTemplate.cs)
+
+### 9. Call T4 Class in Program.cs
+
+Note that variable type should be an interface. **Don't** use `var` or `TableEntityTemplate`.
+
+- [Program.cs](./Program.cs)
+
+## Build & Run
+
+### Build
+
+```console
+> dotnet build
+```
+
+`TableEntityTemplate.Generated.cs` is generated and the program is built including it.
+
+### Run
+
+`dotnet run` does not cause Beforebuild-Event, you should execute `dotnet build` first.
+
+```console
+> dotnet run
+```
+
+### Result
+
+```csharp
+using System;
+using System.Collections.Generic;
+
+namespace MyNameSpace
+{
+    /// <summery>
+    /// Stores employee information.
+    /// </summery>
+    public class StaffMaster
+    {
+        public int StaffId { get; }
+
+        public string StaffName { get; set; }
+
+        /// <summery>
+        /// Home Address.
+        /// </summery>
+        public string Address { get; set; }
+
+        public DateTime CreatedDate { get; set; }
+
+        public StaffMaster(
+            int staffId
+        )
+        {
+            StaffId = staffId;
+        }
+
+        public StaffMaster(
+            int staffId,
+            string staffName,
+            string address,
+            DateTime createdDate
+        )
+        {
+            StaffId = staffId;
+            StaffName = staffName;
+            Address = address;
+            CreatedDate = createdDate;
+        }
+    }
+}
+```
+
+## References
+
+- [T4 Templates at Build Time with Dotnet Core](https://notquitepure.info/2018/12/12/T4-Templates-at-Build-Time-With-Dotnet-Core/)
+- [Mono/T4](https://github.com/mono/t4)