Migrations

This page contains instructions for migrating to new version of the library.

v0.7

For a good look at how this tooling setup looks like, read through Readme.

For a migration of a published generator plugin, see https://github.com/amis92/RecordGenerator/pull/127

P2P generator (in the same solution)

Scenario: you have your own generator in a project, in the same solution that you use it in.

For migrating the generator project, see NuGet generator publisher and ignore packing changes.

For migrating the consuming project, you need to add an attribute OutputItemType="CodeGenerationRoslynPlugin" to the ProjectReference of the generator.

<!-- Sample.Consumer/Sample.Consumer.csproj -->
     <ProjectReference Include="..\Sample.Generator\Sample.Generator.csproj"
+                      OutputItemType="CodeGenerationRoslynPlugin"
                       PrivateAssets="all" />

You might need additional attributes there - see Readme's Customize generator reference.

An example migration was done on the Sample project: https://github.com/AArnott/CodeGeneration.Roslyn/commit/f69346b57e027e8fdd7a33cbfed6080e376c14cd?diff=unified

NuGet generator consumer

Scenario: your project has a PackageReference (NuGet) to a generator.

If a generator targets version of CG.R < 0.7, you can still use it. Since you can't manually fix the NuGet package's content, we've provided a migration path; for informative purposes a CGR1002 warning will be raised to make you aware of the change. Until the generator package you use is updated, you need to add that warning code to the list of ignored warnings. See an example below:

<!-- YourConsumerProject.csproj -->
<Project>
  <!--...-->
  <PropertyGroup>
    <!-- Ignore CGR1002 because it's expected to be raised by legacy generators -->
    <MSBuildWarningsAsMessages>$(MSBuildWarningsAsMessages);CGR1002</MSBuildWarningsAsMessages>
    <!--...-->
  </PropertyGroup>
</Project>

Example usage is in Tests: https://github.com/AArnott/CodeGeneration.Roslyn/blob/dadd6396e0a3d5968ba3de12fc2dcbb12a1fc995/src/CodeGeneration.Roslyn.Tests/CodeGeneration.Roslyn.Tests.csproj#L9

NuGet generator publisher

Scenario: you have a generator plugin published on NuGet.

To migrate your generator plugin to the new version, use the new Plugin.Sdk package.

ℹ For documentation on Sdk element see MSBuild Sdk Element.

Since CG.R v0.7, generators have to target netcoreapp2.1, because that's the framework the CG.R Tool runs on (and loads the plugins).

If your generator has a single TargetFramework:

<Project Sdk="Microsoft.NET.Sdk">
  <Sdk Name="CodeGeneration.Roslyn.Plugin.Sdk" Version="{version used}" />
  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
  </PropertyGroup>

  <ItemGroup>
    <!-- Example dependency (supported since CG.R 0.7) -->
    <PackageReference Include="Newtonsoft.Json" Version="12.0.3" />
  </ItemGroup>
</Project>

If your generator is multitargeting with TargetFrameworks (e.g. to use C#8's NRT feature), you need to still target netcoreapp2.1. For details, see https://github.com/AArnott/CodeGeneration.Roslyn/blob/master/README.md#multitargeting-generator

⚠ The Sdk will implicitly reference the CodeGeneration.Roslyn package for you, so you can remove the reference to it in your project file.

ℹ Additionally, the Sdk hooks into the build pipeline so that your generator works both locally, as well as is packaged correctly into a NuGet as expected by the CG.R Tool. You should remove all packaging customizations in generator project file.

If you've followed instructions for Packaging up your code generator for others' use in old Readmes, remove:

• build/{MyPackage}.props/targets that defined GeneratorAssemblySearchPaths
• dependency on CodeGeneration.Roslyn.BuildTime package (no longer published)
• <IsTool> property - correct package path is set in Sdk

Those are deprecated and the correct package setup is done by the Plugin.Sdk.

You should also instruct your consumers that they need to change their references:

• Remove <DotNetCliToolReference Include="dotnet-codegen" Version="*" />
• Remove <PackageReference Include="CodeGeneration.Roslyn.BuildTime" Version="*" /> if they have
• Add CodeGeneration.Roslyn.Tool (if you don't provide metapackage; details below):

  dotnet add package CodeGeneration.Roslyn.Tool

And of course any packages you provide (e.g. Pkg.Generators and Pkg.Attributes).

💡 You can provide a much better UX by creating a meta-package for your plugin, which would essentially be just a dependency container. For details see https://github.com/AArnott/CodeGeneration.Roslyn#create-the-metapackage