Packaging your work: Uploading Open-source code to NuGet

NuGet is an essential tool for developers in the .NET ecosystem, enabling easy distribution and consumption of libraries. Whether building reusable code for personal projects, or sharing tools with the global developer community, publishing open-source code as a NuGet package makes it accessible to anyone. In this post, the process of uploading an open-source API, the PlanScorecard API, to a NuGet package is explored, along with building an understanding of the assembly sharing platform, preparing, uploading, and publishing your work.

Background

What is NuGet?

NuGet is the official package manager for the .NET ecosystem, designed to simplify the sharing, consumption, and management of reusable code libraries. With over 3 million packages available, it's a cornerstone of the .NET development workflow, allowing developers to quickly incorporate pre-build libraries into their projects.

Key Features of NuGet

1. Package Distribution: NuGet hosts and distributes compiled libraries (packages) that can be easily integrated into projects.

2. Dependency Management: It automatically handles dependencies, ensuring that all required packages are installed in the correct versions.

3. Version Control: NuGet packages are versioned, allowing developers to update or rollback versions with minimal effort.

4. Seamless Integration with .NET Tools: NuGet is deeply integrated into tools like Visual Studio, .NET CLI, and even CI/CD pipelines, enabling a smooth development workflow.

While both NuGet and GitHub serve the development community, they address different needs.

Feature	NuGet	GitHub
Purpose	Distributing compiled libraries for reuse	Hosting source code and version control
Content	Precompiled packages (e.g., .nupkg)	Source code repositories
Audience	Developers looking for read-to-go libraries	Developers contributing to and reviewing source code.
Usage	Installed via CLI or IDE (e.g. Visual Studio)	Cloned or downloaded for modifications

Some common examples of using NuGet packaged libraries are referenced in a number of blogs. NLog is a logging library available on NuGet and discussed in Gateway Script's first blog post, First Experiences Logging with NLog. OxyPlot is used for the visualization of the Gamma Analysis map in the blog post titled Getting Started with Portal Dosimetry Scripting Part II: Visualizing the Gamma Analysis as well as TrajectoryLog.Net Part II: Visualizing Fluences with OxyPlot. The Plan Scorecard API is also currently using a popular JSON deserialization library, Newtonsoft.JSON. By publishing an API on NuGet, the features are incorporated more easily into projects with just a few commands, creating opportunities for broader adoption and community contributions.

The Plan Scorecard API

The PlanScorecard API is a comprehensive tool for scoring radiation therapy treatment plans and patients using customizable metrics. It is built on a robust data model designed to support scoring multiple plans and patients while providing utilities for customization, automation, and reporting.

The PlanScorecard API bridges the gap between automated plan evaluation and clinical reporting, empowering developers to enhance workflow efficiency and plan quality.

Central to the scoring process, this model contains properties and methods to define, calculate and customize plan scores:

Selected Properties:

StructureId, TemplateStructureId, and MetricId	Identifying the structures being scored and their corresponding templates along with the metrics within the template.
MetricText, ScoreMax, and MetricComment	Define the scoring metrics and associated metadata.
ScoreValues	A collection of score objects (represented by the ScoreValueModel) detailing individual score metrics. The ScoreValueModel contains properties such as PatientId, CourseId, and PlanId, along with the Value of the metric being measured, the Score provided from the template based on the value.
ScoreTemplateModel	JSON-based templates for creating scorecards.

Selected Methods:

BuildPlanScoreFromTemplate	Generates the plan scores using a predefined template and plan data available via ESAPI
GetStructuresFromTemplate	Matches or generates structures based on templates or IDs
NormPlan	Calculates the optimal normalization value to maximize scoring outcomes.

The properties and methods within the PlanScorecard API are also used in the PlanScoreCard tool on the Medical Affairs Applied Solutions GitHub page. This software allows for clinicians to both create and edit dosimetric scorecards and score plans on multiple patients. The PlanScorecard API allows for developers to use these same methods within custom software applications. The PlanScorecard API bridges the gap between automated plan evaluation and clinical reporting, empowering developers to enhance workflow efficiency and plan quality.

Introduction

In the following example, the steps to prepare and publish the PlanScorecard API as a NuGet package will be detailed, making the API available to developers worldwide. While there are various ways to upload a NuGet package, we'll follow the guidelines outlined in Microsoft's Learn platform under Quickstart: Create and publish a package using Visual Studio (.NET Framework, Windows). It is critical to select the .NET Framework specific instructions because the setup and configurations for a .NET Framework application differ than those for .NET Core or .NET 5+. The NuGet CLI derives much of the information about the project from the project file (*.csproj).

Before getting started a NuGet account will be required to sign up. Please access NuGet.org to register and obtain an API key for publishing your package. If following along directly, Visual Studio should also be installed as this is the tool we will use to modify the C# project file.

Preparing the Application for Upload

For the upcoming step, please download the NuGet CLI from the following link: https://dist.nuget.org/win-x86-commandline/latest/nuget.exe. The instructions request that this package be stored in a specified folder, and that this folder is then added to your PATH environment variable. For the example, this executable will be stored directly in the folder where the project file is located. Copy and paste the downloaded NuGet CLI into that location. Right mouse click the exe file and go to the properties. The file needs to be unblocked by checking the "Unblock" option at the bottom of the properties window. In the next step, the .nuspec manifest file is created which describes the software application to NuGet.

Setting the Project Properties for the Application

The Assembly information for the project will be uploaded with the package to NuGet. This is how developers consuming the package will be notified of the authors and owners, the versions, and other various information about your software. To access the Assembly information, open your project in Visual Studio. From the Visual Studio IDE, go to the Project menu and select Properties. On the initial Application tab, click the Assembly Information... button. Once these properties are set, save the project and rebuild the solution.

After setting the properties correctly the application manifest can be generated. In Visual Studio, select the Tools menu from the top of the IDE. Select the option Command Line --> Developer Command Prompt. The prompt will open at the location of the solution file. Navigate to where the nuget.exe file was saved. Then find the C# project file for which you would like to write the .nuspec description. Then type in the following prompt, where <ProjectName.csproj> is the name of the project file.

nuget spec <ProjectName.csproj>

The nuspec file can be opened with notepad. In reviewing the nuspec file, variables are in place for the metadata of many of the parameters in the file. These are going to be read from the Assembly Information of the project. There are a couple of additional values that can be changed for this project.

• Change the tag requireLicenseAcceptance from false to true.

• By default, the license is set to an MIT license. If you have a different license, you may specify here. If using a custom license, copy the LICENSE file into the same project folder temporarily.

  • Change the type from expression to file.

  • Add the name of the license file in the same folder.

  • Add the following lines after the closing tag for metadata but before the closing tag for package.

<files>
	<file src="license.txt" target=""/>
  </files>

• Add the GitHub repository to the projectUrl. If a custom project website exists, please use this.

• Add releaseNotes describing updates to the package where applicable.

• Modify the tags to make the package easy to find in the NuGet package explorer.

Remove your .nuspec file, nupkg file, and the license file as well as the nuget.exe CLI tool from your repository so they are not accidentally pushed to GitHub.

Uploading the package to NuGet

In the same developer command prompt (from Tools--> Developer Command Prompt) run the command following command on the same project file location.

nuget pack

Login to nuget.org. In the prior shared Quickstart instructions from microsoft, the CLI can be used to upload the nuget page nupkg file. Since the writing of this document, NuGet allows for the upload of the nupkg file directly into the website. Click on your NuGet username at the upper right hand corner, and click on the option Manage Packages. Drag the nupkg file into the Upload box. On upload the NuGet website will verify the package including the inclusion of the package ID, the version, the license, any dependencies (Newtonsoft.Json in this instance). Prior to submission, the website will also allow for the addition of custom documentation. Click Submit at the bottom of the site.

At this time, the package still must be published. NuGet performs validation on the packages prior to making them available for developers. While waiting for your NuGet package to be published, feel free to remove your .nuspec file, nupkg file, and the license file as well as the nuget.exe CLI tool from your repository so they are not accidentally pushed to GitHub.

Using the NuGet package

The new project that requires this PlanScorecard API is a tool named the Scorecard Visualizer, which is a new feature in the PlanScorecard application. This new feature is based on some source code developed by Shane McCarthy at the University of Kentucky for visualizing scorecards after they have been created. On opening the Scorecard Visualizer project, right click the project and select the option Manage NuGet Packages... In the Browse tab of the NuGet package manager, search Planscorecard and find the PlanScoreCard.API package along with the description, licenses, URLs and other information included in the package upload.

Please note that the license must be accepted per the modification made in the nuspec file.

Once the package has been attached, test the application. For this specific instance, after loading in a scorecard and clicking on the Edit Scorecard button.

In the PlanScorecard editor, a new icon will allow for the visualization of scorecard parameters in a concise and creative way.

Conclusion

Publishing an open-source API to NuGet is more than just a technical process; it's a way to contribute to the developer community, foster collaboration, and promote innovations. By making the PlanScorecard API publicly available, the first steps have been taken to allow others in radiation oncology software development to more easily use the API to improve their own applications. While the process of uploading a package is straightforward, a few challenges must also be considered.

• Maintaining Compatibility: With the .NET ecosystem rapidly evolving, keeping your package compatible with newer frameworks while supporting legacy systems can be challenging.

• Documentation: Comprehensive documentation, including examples and clear descriptions, is essential for widespread adoption.

• Community Feedback: Be prepared to address user questions, suggestions, and potential issues as others begin to sue your API.

Publishing an API is just the start of a journey. By leveraging NuGet, you can empower a wider audience to enhance their own projects, driving collaboration and innovation in the field. What's next for the libraries you will push to NuGet? That's up to the developers who now join in the vision.