Introducing Source Code Link for NuGet packages

August 27, 2018 by Maxime Rouiller

NuGet.org now supports surfacing source code repository link for NuGet packages. This will enable package authors to surface both the project’s website and the source repository using the projectUrl and the repository properties respectively instead of having to choose between the two using just the projectUrl property.

The nuspec has supported the repository property for a while and today more than 16,000 packages contain this property. We have now come a full circle by surfacing this information on the package details page (on NuGet.org). This is how it looks for the Newtonsoft.Json package:

Source Code

In this post, I would like to elaborate on the different ways to light up this feature for your packages.

Using nuspec

If you are using a nuspec file for packaging, you will need to add a repository tag within your nuspec. For example, take a look at NUnit’s nuspec:

<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
    <metadata minClientVersion="2.12">
       <!-- .. snipped ... -->
       
       <!-- Add this line and making the URL targets your project -->
       <repository type="git" url="https://github.com/nunit/nunit" />
       
       <!-- .. snipped ... -->
    </metadata>
</package>

Using project file

If you create your NuGet package directly with a project file, you will need to add a RepositoryUrl and a RepositoryType to the project file to enable this new feature on your package. Here’s an example on how RestSharp implements it directly within their csproj.

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- .. snipped ... -->
    
    <RepositoryUrl>https://github.com/restsharp/RestSharp.git</RepositoryUrl>
    <RepositoryType>git</RepositoryType>
    
    <!-- .. snipped ... -->
  </PropertyGroup>
  <!-- .. snipped ... -->
</Project>

SourceLink enables source debugging directly within your .NET Core packages. At the same time, it also inserts the repostory attribute in your project to have the link show up on the NuGet package’s details page. To use it, you need to add the following to your csproj file.

<PropertyGroup>
    <!-- Optional: Publish the repository URL in the built .nupkg (in the NuSpec <Repository> element) -->
    <PublishRepositoryUrl>true</PublishRepositoryUrl>
</PropertyGroup>

<ItemGroup>
  <!-- For GitHub -->
  <PackageReference Include="Microsoft.SourceLink.GitHub" Version="1.0.0-beta-63127-02" PrivateAssets="All"/>

  <!-- For Visual Studio Team Services -->
  <PackageReference Include="Microsoft.SourceLink.Vsts.Git" Version="1.0.0-beta-63127-02" PrivateAssets="All"/>

  <!-- For Team Foundation Server -->
  <PackageReference Include="Microsoft.SourceLink.Tfs.Git" Version="1.0.0-beta-63127-02" PrivateAssets="All"/>
  <SourceLinkTfsGitHost Include="tfs-server-name" VirtualDirectory="tfs"/>

  <!-- For GitLab -->
  <PackageReference Include="Microsoft.SourceLink.GitLab" Version="1.0.0-beta-63127-02" PrivateAssets="All"/>

  <!-- For BitBucket -->
  <PackageReference Include="Microsoft.SourceLink.Bitbucket.Git" Version="1.0.0-beta-63127-02" PrivateAssets="All"/>

</ItemGroup>

For example, you can refer to the Newtonsoft.Json’s implementation.

Using Cake Build

Many open source projects use Cake Build to package their projects. Here’s how you need to change your NuGetPackSettings to allow the source code repository link to be surfaced on NuGet.org:

var nuGetPackSettings = new NuGetPackSettings
    {
        // snipped
        Repository = new NuGetRepository {
                Type = "git",
                Url = "https://github.com/org/repository"
            }
        // snipped
    };

Conclusion

With these small changes to your packaging process, you will quickly get a source code link next to your project. You won’t have to choose between your project page or your project repository anymore. For more information on how nuspec and csproj properties are mapped, look at our documentation. If you want to reach out to us, you can either create a new GitHub issue or tag @nuget in your tweets.