Skip to content

Simplify project file formatting for including files in NuGet packages (icon, license, README) #10839

Open
@chrisraygill

Description

We should simplify the process of including files in the nupkg to ideally a single-line experience like most other package metadata.

One of the advantages of creating SDK-style projects is the ease of interpreting and editing project files. The majority of package metadata can be specified in a single line while embedded files like icons, license files, and README files will need a line in the <PropertyGroup> and <ItemGroup>.

Converting these metadata elements into one-liners will have the following impacts:

  • Make the project file look "cleaner" and more interpretable.
  • Make it easier for beginners to copy and paste elements from tutorials or examples.
  • Make it faster and easier to include these critical metadata elements overall.

Activity

chrisraygill

chrisraygill commented on May 6, 2021

@chrisraygill
ContributorAuthor

Closing as dupe of dotnet/sdk#2142

loic-sharma

loic-sharma commented on May 6, 2021

@loic-sharma
Contributor

This feature would reduce 16 lines down to 11 lines, a 30% reduction in boilerplate in your project file. Before: 🙊

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>

    <PackageIcon>icon.png</PackageIcon>
    <PackageReadmeFile>README.md</PackageReadmeFile>
    <PackageLicenseFile>LICENSE.txt</PackageLicenseFile>
  </PropertyGroup>

  <ItemGroup>
    <None Include="README.md" Pack="true" PackagePath="\"/>
    <None Include="icon.png" Pack="true" PackagePath="\"/>
    <None Include="LICENSE.txt" Pack="true" PackagePath="\"/>
  </ItemGroup>
</Project>

After: 😎

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>

    <NewPackageIcon>icon.png</NewPackageIcon>
    <NewPackageReadmeFile>README.md</NewPackageReadmeFile>
    <NewPackageLicenseFile>LICENSE.txt</NewPackageLicenseFile>
  </PropertyGroup>

</Project>
loic-sharma

loic-sharma commented on May 6, 2021

@loic-sharma
Contributor

Reopening after offline chat with Chris. This feature request synergizes well - but is separate - from dotnet/sdk#2142. This issue is separate as licenses, icons, and readmes must be labeled in the package's generated .nuspec manifest.

MarkPflug

MarkPflug commented on May 10, 2021

@MarkPflug

I like this idea, but what about taking it to the extreme and defaulting all the values based on naming conventions?

<!-- if the user doesn't explicitly specify the icon, default it to the projectname.png or icon.png if they exist -->
<NewPackageIcon Condition="$(NewPackageIcon) == '' And Exists($(MSBuildProjectName).png)">$(MSBuildProjectName).png</NewPackageIcon>
<NewPackageIcon Condition="$(NewPackageIcon) == '' And Exists(icon.png)">icon.png</NewPackageIcon>

How often would a user be surprised by this as a default behavior? Is it likely that there would be an icon.png, README.txt or LICENSE.txt in the project root that the user doesn't want to be used as the package asset? I suppose this would be a breaking change to existing package creation, so maybe a opt-in to this behavior would be necessary.

After 🤩:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <UseNugetDefaults>true</UseNugetDefaults>
  </PropertyGroup>

</Project>

Or maybe <UseNugetDefaults>1</UseNugetDefaults> , so that the defaults can be versioned in the future and allow users to opt-in by bumping the number, akin to LangVersion for C#.

JonDouglas

JonDouglas commented on May 18, 2021

@JonDouglas
Contributor

I believe simplifying the single line defaults should be accomplished easily today & if users want to continue to do the multi-line approach with custom paths, they can do that.

Instead of another MSBuild property, I would encourage an empowering error message if the asset is not found in either experience (default or custom paths).

In other words, if you opt into the metadata, you should be guided towards being successful using it without needing to opt-in to another feature or reading documentation. You should be able to be guided by error messages if you do something wrong.

michael-hawker

michael-hawker commented on Sep 7, 2023

@michael-hawker

Would greatly appreciate this. Trying to add a readme file, and pack isn't finding it giving NU5039 and I have no idea why... Have both PackageReadmeFile and the pack item.

1 remaining item

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      Simplify project file formatting for including files in NuGet packages (icon, license, README) · Issue #10839 · NuGet/Home