feat: Add templates package for dotnet new (#217)

* feat: Add Templates package

* feat: script for testing template pack

* ci: Build and test templates

* docs: Add templates usage to readme

Author: amis92

.config/dotnet-tools.json

@@ -3,7 +3,7 @@
   "isRoot": true,
   "tools": {
     "nbgv": {
-      "version": "3.1.71",
+      "version": "3.0.28",
       "commands": [
         "nbgv"
       ]

.github/workflows/ci.yml

@@ -21,7 +21,9 @@ jobs:
         os: [ windows-latest, ubuntu-latest, macos-latest ]
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v1
+    - uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
 
     - name: Setup .NET Core
       uses: actions/setup-dotnet@v1
@@ -58,3 +60,9 @@ jobs:
     - name: Build samples
       shell: pwsh
       run: samples/build.ps1
+
+    - name: Build and test templates
+      shell: pwsh
+      run: |
+        templates/build.ps1
+        templates/test-new.ps1

.gitignore

@@ -209,3 +209,6 @@ FakesAssemblies/
 GeneratedArtifacts/
 _Pvt_Extensions/
 ModelManifest.xml
+
+# MSBuild binlogs
+*.binlog

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 ## Prerequisites
 
 * .NET Core SDK - version as specified in [src/global.json](src/global.json).
-* netcoreapp2.1 runtime (Microsoft.NETCore.App 2.1.x)
+* PowerShell 7+ (`pwsh` in PATH)
 
 ## Building
 

README.md

@@ -19,9 +19,10 @@ Instructions on development and using this project's source code are in [CONTRIB
   - [Table of Contents](#table-of-contents)
   - [How to write your own code generator](#how-to-write-your-own-code-generator)
     - [Prerequisites](#prerequisites)
+    - [Use template pack](#use-template-pack)
     - [Define code generator](#define-code-generator)
-    - [Create consuming console app](#create-consuming-console-app)
     - [Define attribute](#define-attribute)
+    - [Create consuming console app](#create-consuming-console-app)
     - [Apply code generation](#apply-code-generation)
   - [Advanced scenarios](#advanced-scenarios)
     - [Customize generator reference](#customize-generator-reference)
@@ -44,6 +45,63 @@ In this walkthrough, we will define a code generator that replicates any class (
 
 [dotnet-sdk-2.1]: https://dotnet.microsoft.com/download/dotnet-core/2.1
 
+### Use template pack
+
+To install the template pack, run:
+> `dotnet new -i CodeGeneration.Roslyn.Templates`
+
+You'll then have our template pack installed and ready for use with `dotnet new`.
+For details see [templates Readme](./templates/README.md).
+
+Prepare a directory where you want to create your Plugin projects, e.g. `mkdir DemoGeneration`.
+Then, in that directory, create the set of Plugin projects (we add the --sln to create solution as well):
+> `dotnet new cgrplugin -n Duplicator --sln`
+
+This will create 3 ready-to-build projects. You can now skip through the next steps
+of creating and setting up projects, just apply the following changes to have the same content:
+- rename `Duplicator.Generators/Generator1.cs` to `DuplicateWithSuffixGenerator.cs`
+  - also replace the `DuplicateWithSuffixGenerator` class with the following:
+    ```csharp
+    public class DuplicateWithSuffixGenerator : ICodeGenerator
+    {
+        private readonly string suffix;
+
+        public DuplicateWithSuffixGenerator(AttributeData attributeData)
+        {
+            suffix = (string)attributeData.ConstructorArguments[0].Value;
+        }
+
+        public Task<SyntaxList<MemberDeclarationSyntax>> GenerateAsync(TransformationContext context, IProgress<Diagnostic> progress, CancellationToken cancellationToken)
+        {
+            // Our generator is applied to any class that our attribute is applied to.
+            var applyToClass = (ClassDeclarationSyntax)context.ProcessingNode;
+
+            // Apply a suffix to the name of a copy of the class.
+            var copy = applyToClass.WithIdentifier(SyntaxFactory.Identifier(applyToClass.Identifier.ValueText + suffix));
+
+            // Return our modified copy. It will be added to the user's project for compilation.
+            var results = SyntaxFactory.SingletonList<MemberDeclarationSyntax>(copy);
+            return Task.FromResult(results);
+        }
+    }
+    ```
+- rename `Duplicator.Attributes/Generator1Attribute.cs` file to `DuplicateWithSuffixAttribute.cs`
+  - also replace `DuplicateWithSuffixAttribute` class with the following:
+    ```csharp
+    [AttributeUsage(AttributeTargets.Class)]
+    [CodeGenerationAttribute("Duplicator.Generators.DuplicateWithSuffixGenerator, Duplicator.Generators")]
+    [Conditional("CodeGeneration")]
+    public class DuplicateWithSuffixAttribute : Attribute
+    {
+        public DuplicateWithSuffixAttribute(string suffix)
+        {
+            Suffix = suffix;
+        }
+
+        public string Suffix { get; }
+    }
+    ```
+
 ### Define code generator
 
 Your generator cannot be defined in the same project that will have code generated
@@ -57,7 +115,7 @@ Now we'll use an [MSBuild project SDK] [`CodeGeneration.Roslyn.Plugin.Sdk`][Plug
 <!-- Duplicator.Generators/Duplicator.Generators.csproj -->
 <Project Sdk="Microsoft.NET.Sdk">
   <!-- Add the following element above any others: -->
-  <Sdk Name="CodeGeneration.Roslyn.Plugin.Sdk" Version="{replace with actual version used}"/>
+  <Sdk Name="CodeGeneration.Roslyn.Plugin.Sdk" Version="{replace with actual version used}" />
 
   <PropertyGroup>
     <TargetFramework>netcoreapp2.1</TargetFramework>
@@ -107,56 +165,26 @@ namespace Duplicator.Generators
 }
 ```
 
-### Create consuming console app
-
-We'll consume our generator in a Reflector app:
-> `dotnet new console -f netcoreapp2.1 -o Reflector`
-> 
-> `dotnet add Reflector reference Duplicator.Generators`
-
-Let's write a simple program that prints all types in its assembly:
-```csharp
-// Reflector/Program.cs
-using System;
-
-namespace Reflector
-{
-    class Program
-    {
-        static void Main(string[] args)
-        {
-            foreach (var type in typeof(Program).Assembly.GetTypes())
-                Console.WriteLine(type.FullName);
-        }
-    }
-}
-```
-
-Now, when we `dotnet run -p Reflector` we should get:
-> `Reflector.Program`
-
 ### Define attribute
 
 To activate your code generator, you need to define an attribute with which
-we'll annotate the class to be copied. Install [Attributes package][AttrNuPkg]:
+we'll annotate the class to be copied. Let's do that in a new project:
+> `dotnet new classlib -f netstandard2.0 -o Duplicator.Attributes`
 
-> `dotnet add Reflector package CodeGeneration.Roslyn.Attributes`
+Install [Attributes package][AttrNuPkg]:
+
+> `dotnet add Duplicator.Attributes package CodeGeneration.Roslyn.Attributes`
 
 Then, define your attribute class:
 
 ```csharp
-// Reflector/Program.cs
+// Duplicator.Attributes/DuplicateWithSuffixAttribute.cs
 using System;
 using System.Diagnostics;
 using CodeGeneration.Roslyn;
 
-namespace Reflector
+namespace Duplicator
 {
-    class Program
-    {
-        // ...
-    }
-
     [AttributeUsage(AttributeTargets.Class)]
     [CodeGenerationAttribute("Duplicator.Generators.DuplicateWithSuffixGenerator, Duplicator.Generators")]
     [Conditional("CodeGeneration")]
@@ -185,6 +213,36 @@ with a dependency on your code generation assembly.
 > ℹ Of course, the attribute will persist if you define compilation symbol
 > "CodeGeneration"; we assume it won't be defined.
 
+### Create consuming console app
+
+We'll consume our generator in a Reflector app:
+> `dotnet new console -o Reflector`
+> 
+> `dotnet add Reflector reference Duplicator.Attributes`
+> 
+> `dotnet add Reflector reference Duplicator.Generators`
+
+Let's write a simple program that prints all types in its assembly:
+```csharp
+// Reflector/Program.cs
+using System;
+
+namespace Reflector
+{
+    class Program
+    {
+        static void Main(string[] args)
+        {
+            foreach (var type in typeof(Program).Assembly.GetTypes())
+                Console.WriteLine(type.FullName);
+        }
+    }
+}
+```
+
+Now, when we `dotnet run -p Reflector` we should get:
+> `Reflector.Program`
+
 ### Apply code generation
 
 Applying code generation is incredibly simple. Just add the attribute on any type
@@ -195,6 +253,7 @@ or member supported by the attribute and generator you wrote. We'll test our Dup
 using System;
 using System.Diagnostics;
 using CodeGeneration.Roslyn;
+using Duplicator;
 
 namespace Reflector
 {
@@ -205,19 +264,12 @@ namespace Reflector
     {
         // ...
     }
-
-    class DuplicateWithSuffixAttribute : Attribute
-    {
-        // ...
-    }
 }
 ```
 
 Let's check our app again:
 > `> dotnet run -p Reflector`
 > 
-> `Reflector.DuplicateWithSuffixAttribute`
-> 
 > `Reflector.Program`
 > 
 > `Reflector.Test`
@@ -261,8 +313,6 @@ This is how your project file can look like:
 And if all steps were done correctly:
 > `> dotnet run -p Reflector`
 > 
-> `Reflector.DuplicateWithSuffixAttribute`
-> 
 > `Reflector.Program`
 > 
 > `Reflector.Test`
@@ -354,12 +404,16 @@ we have to use `SetTargetFramework` metadata. Setting it implies
 
 ### Package your code generator
 
+> ℹ If you've used `cgrplugin` template, you've already got metapackage project ready.
+
 You can also package up your code generator as a NuGet package for others to install
 and use. A project using `CodeGeneration.Roslyn.Plugin.Sdk` is automatically
 configured to produce a correct Plugin nuget package.
 
 #### Separate out the attribute
 
+> ⚠ This section is deprecated since it's now the default.
+
 The triggering attribute has to be available in consuming code. Your consumers
 can write it themselves, but it's not a good idea to require them do so.
 So we'll separate the attribute into another project that has TFM allowing
@@ -398,7 +452,7 @@ An example consuming project file would contain:
 </ItemGroup>
 ```
 
-> ➡ There's a much better approach: **metapackage**.
+> ✔ There's a much better approach: **metapackage**.
 
 For this, we'll use [`CodeGeneration.Roslyn.PluginMetapackage.Sdk`][PluginMetapkgSdkNuPkg] [MSBuild project SDK]
 in a new project called simply `Duplicator`, which will reference our attributes:

src/CodeGeneration.Roslyn.Templates/CodeGeneration.Roslyn.Templates.csproj

@@ -0,0 +1,33 @@
+<Project Sdk="Microsoft.Build.NoTargets">
+
+  <PropertyGroup>
+    <PackageType>Template</PackageType>
+    <Description>Templates to use when creating CodeGeneration.Roslyn Plugins (source code generators).</Description>
+    <PackageTags>$(PackageTags);templates;cgrgen;cgratt;cgrplugin;cgrplugingens;cgrpluginatts</PackageTags>
+    <TargetFramework>netstandard2.0</TargetFramework>
+    <IncludeBuildOutput>false</IncludeBuildOutput>
+    <IncludeContentInPack>true</IncludeContentInPack>
+    <SuppressDependenciesWhenPacking>true</SuppressDependenciesWhenPacking>
+    <IncludeSymbols>false</IncludeSymbols>
+    <BeforePack>$(BeforePack);SetPackageVersionInTemplateConfigs</BeforePack>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <Content Include="../../templates/content/**" Pack="true" PackagePath="content" />
+  </ItemGroup>
+
+  <Target Name="SetPackageVersionInTemplateConfigs" DependsOnTargets="GetBuildVersion">
+    <ItemGroup>
+      <!-- Take template.json files, set patched Target paths and PackagePath -->
+      <_TemplateJson Include="@(Content)"
+                     Condition=" '%(Filename)%(Extension)' == 'template.json' " 
+                     TargetPath="$(IntermediateOutputPath)patched/%(RecursiveDir)%(Filename)%(Extension)"
+                     PackagePath="%(PackagePath)/%(RecursiveDir)"/>
+      <Content Remove="@(_TemplateJson)" />
+      <Content Include="@(_TemplateJson->'%(TargetPath)')" />
+    </ItemGroup>
+    <!-- Actually patch the files: pwsh -c "&{ ./patch.ps1 'src1','src2' 'trg1','trg2' 'version' }" -->
+    <Exec Command="pwsh -c &quot; &amp;{ ./patch.ps1 @(_TemplateJson->'%27%(Identity)%27', ',') @(_TemplateJson->'%27%(TargetPath)%27', ',') '$(PackageVersion)' } &quot;" />
+  </Target>
+
+</Project>

src/CodeGeneration.Roslyn.Templates/patch.ps1

@@ -0,0 +1,20 @@
+param (
+    [Parameter()]
+    [string[]] $InputFile,
+    [Parameter()]
+    [string[]] $OutputFile,
+    [Parameter()]
+    [string] $Version
+)
+
+while ($InputFile) {
+    $input, $InputFile = $InputFile
+    $output, $OutputFile = $OutputFile
+
+    $json = Get-Content $input | ConvertFrom-Json
+    $versionSymbol = $json.symbols.'cgr-version'
+    if ($versionSymbol) {
+        $versionSymbol.defaultValue = $Version
+    }
+    New-Item $output -Value (ConvertTo-Json $json) -Force
+}

src/CodeGeneration.Roslyn.sln

@@ -42,6 +42,8 @@ Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "CodeGeneration.Roslyn.Plugi
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CodeGeneration.Roslyn.PluginMetapackage.Sdk", "CodeGeneration.Roslyn.PluginMetapackage.Sdk\CodeGeneration.Roslyn.PluginMetapackage.Sdk.csproj", "{C1964B5A-1E9C-477B-B1A1-B464FFB8BCB7}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "CodeGeneration.Roslyn.Templates", "CodeGeneration.Roslyn.Templates\CodeGeneration.Roslyn.Templates.csproj", "{ABEDDF07-58BA-47EB-BA0F-F615D1E6D397}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -88,6 +90,10 @@ Global
 		{C1964B5A-1E9C-477B-B1A1-B464FFB8BCB7}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{C1964B5A-1E9C-477B-B1A1-B464FFB8BCB7}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{C1964B5A-1E9C-477B-B1A1-B464FFB8BCB7}.Release|Any CPU.Build.0 = Release|Any CPU
+		{ABEDDF07-58BA-47EB-BA0F-F615D1E6D397}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{ABEDDF07-58BA-47EB-BA0F-F615D1E6D397}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{ABEDDF07-58BA-47EB-BA0F-F615D1E6D397}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{ABEDDF07-58BA-47EB-BA0F-F615D1E6D397}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE

src/Directory.Build.props

@@ -9,6 +9,7 @@
     <RepositoryUrl>https://github.com/aarnott/CodeGeneration.Roslyn</RepositoryUrl>
     <RepositoryType>git</RepositoryType>
     <PackageReleaseNotes>https://github.com/AArnott/CodeGeneration.Roslyn/blob/master/CHANGELOG.md</PackageReleaseNotes>
+    <PackageTags>codegen;codegeneration;roslyn;sourcegen;sourcegeneration;source;generation</PackageTags>
 
     <PublishRepositoryUrl>true</PublishRepositoryUrl>
     <EmbedUntrackedSources>true</EmbedUntrackedSources>

templates/.gitignore

@@ -0,0 +1 @@
+.nuget