loading...

Writing a NuGet package release notes in an outside of a .csproj file.

j_sakamoto profile image jsakamoto ・3 min read

Editing .csproj file by any text editors is easy.

In a C# programming these days, it is becoming increasingly the case that direct editing a .csproj XML file, instead of via Visual Studio's project property GUI.

Because, the contents of modern .csproj file (a.k.a "SDK style project") is very simpler rather than old style .csproj file.

Additionally, by default, Visual Studio 2019 opens a .csproj file in that's text editor when the project node in solution explorer is double-clicked, instead of showing project property GUI, if the .csproj file is SDK style.

However, editing release notes is a nightmare...

By the way, if you are developing a library to be a NuGet package, you would like to write the package release notes.

While you are writing the package release notes in Visual Studio's project property GUI, there is no problem.

However, if you write the package release notes by Visual Studio's text editor directly, is become a nightmare.

Because the Visual Studio's text editor format the XML contents of .csproj file whenever I save it.

This auto-formatting feature breaks all of the layout of the package release notes!

The auto-formatting feature breaks all of the layout of the package release notes!

You can see many undesired spaces and line breaks in the package release notes after auto-formatting.

Yes, I can avoid this trouble by disabling auto-format feature, but editing .csproj file in other parts (ex. writing custom build tasks) without auto-formatting is also strongly painful.

What can I do?

My solution

One day, I found the method to solve this my problem finally!

The method is, writing the package release notes in a text file which is outside of .csproj file, and import it from inside of .csproj file. :)

I will show you more details.

Step 1. Write the release notes in outside of the project file.

At first, create a text file named RELEASE-NOTES.txt, and write the package release notes in this file, like this.

v.1.0.1
- Support to Blazor v.3.2 Preview 3.

v.1.0.0
- Initial release.

You can locate the RELEASE-NOTES.txt file anywhere, in this case, I located the RELEASE-NOTES.txt file at the solution folder of the my NuGet package library project.

Step 2. Import it from the project file.

Next, I implemented some MSBuild scripts in the NuGet package library project file (.csproj) to import the contents of the RELEASE-NOTES.txt file.

I implemented the MSBuild target to be executed at the before "GenerateNuspec" target is executed.

At the before executing of the "GenerateNuspec" target is a good entry point to prepare the package release notes.

This target reads the RELEASE-NOTES.txt file contents by ReadLinesFromFile MSBuild standard task, and output the contents into a MSBuild items which named ReleaseNoteLines.

Finally, build the PackageReleaseNotes MSBuild property from the ReleaseNoteLines MSBuild items that contain the contents of the RELEASE-NOTES.txt file.

By the way, MSBuild joins the items with a ";" separator by default.

In this case, I want to make PackageReleaseNotes MSBuild property with multi-lines, therefore I wrote the reference of ReleaseNoteLines MSBuild items with LF (Line-Feed) separator explicitly, like this:

@(ReleaseNoteLines, '%0a')

('%0a' means LF code in an MSBuild script file.)

The MSBuild target is like this:

<Target Name="PreparePackageReleaseNotesFromFile" BeforeTargets="GenerateNuspec">
  <ReadLinesFromFile File="../RELEASE-NOTES.txt" >
    <Output TaskParameter="Lines" ItemName="ReleaseNoteLines"/>
  </ReadLinesFromFile>
  <PropertyGroup>
    <PackageReleaseNotes>@(ReleaseNoteLines, '%0a')</PackageReleaseNotes>
  </PropertyGroup>
</Target>

Step 3. Add a comment for the other developers, co-workers.

As a final step, I wrote a comment "(Please write the package release notes in "RELEASE NOTES.txt".)" in the original place of PackageReleaseNotes MSBuild property via Visual Studio's project property GUI window.

Final Screen Shot

Conclusion

That's all.

After implemented these steps, I took back a peaceful and comfortable environment for writing the package release note.

I'm happy if this article helps you making NuGet package library life.

Happy coding :)

Posted on by:

j_sakamoto profile

jsakamoto

@j_sakamoto

Microsoft MVP for Visual Studio and Development Tech. (prefer C#, .NET Core, ASP.NET Core, Azure Web Apps, TypeScript, and Blazor WebAssembly App!)

Discussion

markdown guide