Merge pull request #42 from andrewlock/single-package-attempt-2

Remove StronglyTypedId.Attributes package

Author: andrewlock

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [v1.0.0-beta05]
+
+Breaking Changes:
+* Removed StronglyTypedId.Attributes NuGet package.
+* The attributes are no longer embed in your project by default, instead it will use the external dll. You can re-enable the embedding by setting `STRONGLY_TYPED_ID_EMBED_ATTRIBUTES`.
+
+New Features:
+
+* Improved approach to handling [InternalsVisibleTo] issues, by embedding the StronglyTypedId.Attributes.dll in the NuGet package directly.
+
 ## [v1.0.0-beta04]
 
 New Features:

README.md

@@ -18,10 +18,7 @@ public partial struct FooId { }
 
 and the source generator magically generates the backing code when you save the file! Use _Go to Definition_ to see the generated code:
 
-<picture>
-    <source srcset="https://raw.githubusercontent.com/andrewlock/StronglyTypedId/master/docs/strongly_typed_id.mp4" type="video/mp4">
-    <img src="https://raw.githubusercontent.com/andrewlock/StronglyTypedId/master/docs/strongly_typed_id.gif" alt="Generating a strongly-typed ID using the StronglyTypedId packages"/>
-</picture>
+<img src="https://raw.githubusercontent.com/andrewlock/StronglyTypedId/master/docs/strongly_typed_id.gif" alt="Generating a strongly-typed ID using the StronglyTypedId packages"/>
 
 > StronglyTypedId requires requires [the .NET Core SDK v6.0.100 or greater](https://dotnet.microsoft.com/download/dotnet/6.0).
 
@@ -58,7 +55,15 @@ To use the the [StronglyTypedId NuGet package](https://www.nuget.org/packages/St
 * [Dapper](https://www.nuget.org/packages/Dapper/) (optional, only required if [generating a type mapper](https://andrewlock.net/using-strongly-typed-entity-ids-to-avoid-primitive-obsession-part-3/#interfacing-with-external-system-using-strongly-typed-ids))
 * [EF Core](https://www.nuget.org/packages/Microsoft.EntityFrameworkCore) (optional, only required if [generating an EF Core ValueConverter](https://andrewlock.net/strongly-typed-ids-in-ef-core-using-strongly-typed-entity-ids-to-avoid-primitive-obsession-part-4/))
 
-To install the packages, add the references to your _csproj_ file so that it looks something like the following:
+To install the packages, add the references to your _csproj_ file, for example by running
+
+```bash
+dotnet add package StronglyTypedId --version 1.0.0-beta05
+```
+
+This adds a `<PackageReference>` to your project. You can additionally mark the package as `PrivateAsets="all"` and `ExcludeAssets="runtime"`.
+
+> Setting `PrivateAssets="all"` means any projects referencing this one will not also get a reference to the _StronglyTypedId_ package. Setting `ExcludeAssets="runtime"` ensures the _StronglyTypedId.Attributes.dll_ file is not copied to your build output (it is not required at runtime).
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
@@ -68,8 +73,8 @@ To install the packages, add the references to your _csproj_ file so that it loo
     <TargetFramework>net6.0</TargetFramework>
   </PropertyGroup>
 
-  <!-- Core package -->
-  <PackageReference Include="StronglyTypedId" Version="1.0.0-beta04" />
+  <!-- Add the package -->
+  <PackageReference Include="StronglyTypedId" Version="1.0.0-beta05" PrivateAssets="all" ExcludeAssets="runtime" />
   <!-- -->
 
 </Project>
@@ -124,38 +129,100 @@ var id = new FooId("my-id-value");
 ```
 Currently supported values are `Guid` (the default), `int`, `long`, and `string`.
 
-## Error CS0436 and [InternalsVisibleTo]
+## Changing the defaults globally
 
-The StronglyTypedId generator automatically adds the `[StronglyTypedId]` attributes to your compilation as `internal` attributes. If you add the source generator package to multiple projects, and use the `[InternalsVisibleTo]` attribute, you may experience errors when you build:
+If you wish to change the converters, backing types, or implementations used by default for _all_ the `[StronglyTypedId]`-decorated IDs in your project, you can use the assembly attribute `[StronglyTypedIdDefaults]` to set all of these. For example, the following sets the default converter to a whole project to `[SystemTextJson]`, and changes the default backing-type to an `int` 
 
-```bash
-warning CS0436: The type 'StronglyTypedIdImplementations' in 'StronglyTypedIds\StronglyTypedIds.StronglyTypedIdGenerator\StronglyTypedIdImplementations.cs' conflicts with the imported type 'StronglyTypedIdImplementations' in 'MyProject, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'.
+```csharp
+// Set the defaults for the project
+[assembly:StronglyTypedIdDefaults(
+    backingType: StronglyTypedIdBackingType.Int,
+    converters: StronglyTypedIdConverter.SystemTextJson)]
+
+[StronglyTypedId]
+public partial struct OrderId { }
+
+[StronglyTypedId]
+public partial struct UserId { } 
+```
+
+This is equivalent to setting these values manually on all the IDs:
+
+```csharp
+[StronglyTypedId(
+    backingType: StronglyTypedIdBackingType.Int,
+    converters: StronglyTypedIdConverter.SystemTextJson)]
+public partial struct OrderId { }
+
+[StronglyTypedId(
+     backingType: StronglyTypedIdBackingType.Int,
+    converters: StronglyTypedIdConverter.SystemTextJson)]
+public partial struct UserId { }
 ```
 
-Removing the `[InternalsVisibleTo]` attribute will resolve the problem, but if this is not possible you can disable the auto-generation of the `[StronglyTypedId]` marker attributes, and rely on the helper [`StronglyTypedId.Attributes` package instead](https://www.nuget.org/packages/StronglyTypedId.Attributes). This package contains the same attributes, but as they are in an external package, you can avoid the CS0436 error.
 
-Add the package to your solution, ensuring you set `"PrivateAssets="All"` in the `<PackageReference>` (this will be done automatically when using the .NET CLI or an IDE). To disable the auto-generation of the marker attributes, define the constant `STRONGLY_TYPED_ID_EXCLUDE_ATTRIBUTES` in your project file. Your project file should look something like the following:
+## Embedding the attributes in your project
+
+By default, the `[StronglyTypedId]` attributes referenced in your application are contained in an external dll. It is also possible to embed the attributes directly in your project, so they appear in the dll when your project is built. If you wish to do this, you must do two things:
+
+1. Define the MSBuild constant `STRONGLY_TYPED_ID_EMBED_ATTRIBUTES`. This ensures the attributes are embedded in your project
+2. Add `compile` to the list of excluded assets in your `<PackageReference>` element. This ensures the attributes in your project are referenced, instead of the _StronglyTypedId.Attributes.dll_ library.
+
+Your project file should look something like this:
 
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
     <TargetFramework>net6.0</TargetFramework>
-    <DefineConstants>STRONGLY_TYPED_ID_EXCLUDE_ATTRIBUTES</DefineConstants>
+    <!--  Define the MSBuild constant    -->
+    <DefineConstants>STRONGLY_TYPED_ID_EMBED_ATTRIBUTES</DefineConstants>
   </PropertyGroup>
-  
-  <!-- Core package -->
-  <PackageReference Include="StronglyTypedId" Version="1.0.0-beta04" />
-  <PackageReference Include="StronglyTypedId.Attributes" Version="1.0.0-beta04">
-    <PrivateAssets>All</PrivateAssets>
-  </PackageReference>
-  <!-- -->
+
+  <!-- Add the package -->
+  <PackageReference Include="StronglyTypedId" Version="1.0.0-beta05" 
+                    PrivateAssets="all"
+                    ExcludeAssets="compile;runtime" />
+<!--                               ☝ Add compile to the list of excluded assets. -->
 
 </Project>
 ```
 
-The attribute library is only required at compile time, so it won't appear in your build output. 
+## Preserving usages of the `[StronglyTypedId]` attribute
+
+The `[StronglyTypedId]` and `[StronglyTypedIdDefaults]` attributes are decorated with the `[Conditional]` attribute, [so their usage will not appear in the build output of your project](https://andrewlock.net/conditional-compilation-for-ignoring-method-calls-with-the-conditionalattribute/#applying-the-conditional-attribute-to-classes). If you use reflection at runtime on one of your IDs, you will not find `[StronglyTypedId]` in the list of custom attributes.
+
+If you wish to preserve these attributes in the build output, you can define the `STRONGLY_TYPED_ID_USAGES` MSBuild variable. Note that this means your project will have a runtime-dependency on _StronglyTypedId.Attributes.dll_ so you need to ensure this is included in your build output.
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net6.0</TargetFramework>
+    <!--  Define the MSBuild constant to preserve usages   -->
+    <DefineConstants>STRONGLY_TYPED_ID_USAGES</DefineConstants>
+  </PropertyGroup>
+
+  <!-- Add the package -->
+  <PackageReference Include="StronglyTypedId" Version="1.0.0-beta05" PrivateAssets="all" />
+  <!--              ☝ You must not exclude the runtime assets in this case -->
+
+</Project>
+```
+
+## Error CS0436 and [InternalsVisibleTo]
+
+> In the latest version of StronglyTypedId, you should not experience error CS0436 by default. 
+
+In previous versions of the StronglyTypedId generator, the `[StronglyTypedId]` attributes were added to your compilation as `internal` attributes by default. If you added the source generator package to multiple projects, and used the `[InternalsVisibleTo]` attribute, you could experience errors when you build:
+
+```bash
+warning CS0436: The type 'StronglyTypedIdImplementations' in 'StronglyTypedIds\StronglyTypedIds.StronglyTypedIdGenerator\StronglyTypedIdImplementations.cs' conflicts with the imported type 'StronglyTypedIdImplementations' in 'MyProject, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null'.
+```
+
+In the latest version of _StronglyTypedId_, the attributes are not embedded by default, so you should not experience this problem. If you see this error, compare your installation to the examples in the installation guide.
 
 ## Why do I need this library?
 

releasenotes.props

@@ -5,6 +5,16 @@
 
 Version 0.x of this library used the helper library CodeGeneration.Roslyn for build-time source generation. In version 1.x this approach has been completely replaced in favour of source generators, as these are explicitly supported in .NET 5+. As part of this change, there were a number of additional features added and breaking changes made.
 
+## Changes in 1.0.0-beta05:
+
+Breaking Changes:
+* Removed StronglyTypedId.Attributes NuGet package.
+* The attributes are no longer embed in your project by default, instead it will use the external dll. You can re-enable the embedding by setting `STRONGLY_TYPED_ID_EMBED_ATTRIBUTES`.
+
+New Features:
+
+* Improved approach to handling [InternalsVisibleTo] issues, by embedding the StronglyTypedId.Attributes.dll in the NuGet package directly.
+
 ## Changes in 1.0.0-beta04:
 
 New Features:

src/StronglyTypedIds.Attributes/StronglyTypedIds.Attributes.csproj

@@ -1,12 +1,10 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFrameworks>net461;netstandard2.0;netcoreapp2.1</TargetFrameworks>
+    <TargetFramework>netstandard2.0</TargetFramework>
     <Nullable>enable</Nullable>
     <RootNamespace>StronglyTypedIds</RootNamespace>
-    <PackageId>StronglyTypedId.Attributes</PackageId>
-    <Description>Helper library for StronglyTypedId generator containg attributes only. See README for when to use this package </Description>
-    <IsPackable>true</IsPackable>
+    <IsPackable>false</IsPackable>
   </PropertyGroup>
 
 </Project>

src/StronglyTypedIds/EmbeddedSources.cs

@@ -8,11 +8,11 @@ namespace StronglyTypedIds
     internal static class EmbeddedSources
     {
         private static readonly Assembly ThisAssembly = typeof(EmbeddedSources).Assembly;
-        internal static readonly string StronglyTypedIdAttributeSource = LoadEmbeddedResource("StronglyTypedIds.Templates.Sources.StronglyTypedIdAttribute.cs");
-        internal static readonly string StronglyTypedIdDefaultsAttributeSource = LoadEmbeddedResource("StronglyTypedIds.Templates.Sources.StronglyTypedIdDefaultsAttribute.cs");
-        internal static readonly string StronglyTypedIdBackingTypeSource = LoadEmbeddedResource("StronglyTypedIds.Templates.Sources.StronglyTypedIdBackingType.cs");
-        internal static readonly string StronglyTypedIdConverterSource = LoadEmbeddedResource("StronglyTypedIds.Templates.Sources.StronglyTypedIdConverter.cs");
-        internal static readonly string StronglyTypedIdImplementationsSource = LoadEmbeddedResource("StronglyTypedIds.Templates.Sources.StronglyTypedIdImplementations.cs");
+        internal static readonly string StronglyTypedIdAttributeSource = LoadTemplateForEmitting("StronglyTypedIdAttribute");
+        internal static readonly string StronglyTypedIdDefaultsAttributeSource = LoadTemplateForEmitting("StronglyTypedIdDefaultsAttribute");
+        internal static readonly string StronglyTypedIdBackingTypeSource = LoadTemplateForEmitting("StronglyTypedIdBackingType");
+        internal static readonly string StronglyTypedIdConverterSource = LoadTemplateForEmitting("StronglyTypedIdConverter");
+        internal static readonly string StronglyTypedIdImplementationsSource = LoadTemplateForEmitting("StronglyTypedIdImplementations");
 
         private static readonly string AutoGeneratedHeader = LoadEmbeddedResource("StronglyTypedIds.Templates.AutoGeneratedHeader.cs");
 
@@ -128,5 +128,17 @@ public ResourceCollection(
                 Header = header;
             }
         }
+
+        internal static string LoadTemplateForEmitting(string resourceName)
+        {
+            var resource = LoadEmbeddedResource($"StronglyTypedIds.Templates.Sources.{resourceName}.cs");
+            return AutoGeneratedHeader + @"#if STRONGLY_TYPED_ID_EMBED_ATTRIBUTES
+
+" + resource
+                       .Replace("public sealed", "internal sealed")
+                       .Replace("public enum", "internal enum")
+                   + @"
+#endif";
+        }
     }
 }

src/StronglyTypedIds/Parser.cs

@@ -6,7 +6,6 @@
 using Microsoft.CodeAnalysis.CSharp;
 using Microsoft.CodeAnalysis.CSharp.Syntax;
 using StronglyTypedIds.Diagnostics;
-using StronglyTypedIds.Sources;
 
 namespace StronglyTypedIds;
 

src/StronglyTypedIds/SourceGenerationHelper.cs

@@ -1,7 +1,6 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
-using StronglyTypedIds.Sources;
 
 namespace StronglyTypedIds
 {