Skip to main content

CSharp.Mongo.Migrations

Building and Releasing an Open-source Library using .NET & GitHub

Open-source libraries are a major part of developing software, whether consuming them as libraries through a package manager, interacting with other developers, or contributing back to the community, there aren’t many projects or organisations that don’t rely on open-source software.

This article will cover the basics of getting started with library development in .NET and GitHub using the CSharp.Mongo.Migration library as an example.

Setting Up a Repository (with GitHub)

In software development, version control is a must. If you are already familiar with, and use another source control host, consider skipping this section of the article. Sharing, collaboration, and discussion are all large parts of open-source software development. GitHub is a great (and free, for public repositories) tool to manage:

  • Code with git
  • Documentation through wikis
  • Issue tracking and discussion
  • Simple kanban style project management 
  • CI/CD

Creating the Repository

In order to get started with a new GitHub repository youwe'll mustneed firstto sign up for an account (or use an existing one), after which you will be able to create your repository..

Decisions

There are a number of decisions that should be made before getting started on youran open-source library:

  1. Name: this is the user visible name of yourthe repository, and therefore library or project, in .NET this might be yourthe solution name, or root project namespace.
  2. Open-source licence: This licence will help to protect yourthe project from unfair use, see https://choosealicense.com/ for the basics on selecting a licence.
Givens

There are some assumed settings for a new open-source, .NET repository:

  1. Visibility: This should be public, otherwise youwe aren’t really building an open library!
  2. Readme: All public libraries should have a helpful README.md file, here's an example.
  3. gitignore: ‘Visual Studio’ is the default ignore file for .NET projects.
  4. Licence: MentionedAs mentioned above, youit's shouldbest to include a LICENSE file in yourthe repository root, here's an example.

Configuring the Repository

YouConsider may wish to enableenabling the following extra features for yourthe repository:

  1. Wikis: Consider adding a wiki to document your libraries API.
    1. You may want to restrict editing of the wiki to collaborators only.
    library.
  2. Issues: Allows viewers or collaborators to log bugs, or raise ideas for the library implementation.
  3. Projects: Collaborators can view issues in a kanban board and track progress of milestones.

Cloning the Repository

Now that youwe have a repository on GitHub with a few of the default files you'we'll need to initialise a local clone of the repository on your local machine.source.

You'll need to makeMake sure to install and configure git and add an SSH key to your GitHub account before youattempting canto clone the repository.

The easiest way to clone a repository is to visit the repository page on GitHub, click the 'Code' button, copy the repository URL, and run the git clone command in a terminal:

image.png

mkdir ~/dev
cd ~/dev
git clone git@github.com:JordanDChappell/CSharp.Mongo.Migration.git
cd CSharp.Mongo.Migration

Make sure to replace the URL above with your own repository.

Getting Started With .NET

.NET is a free and open-source cross-platform framework supported by Microsoft where most applications are written in the C# programming language. The platform can be used to build web and desktop applications, as well as command line utilities, services, and class libraries.

Prerequisites

Before diving in youwe will need the following:

Creating YourA Project

The .NET SDK includes a large variety of different project templates that can be viewed here or by running dotnet new list from a terminal.

Most .NET projects (especially those that are developed using the Visual Studio IDE) include a solution (sln) file and one or more project files (csproj) to organise all of the code and configuration.

We'll be using the sln and classlib templatetemplates to create a library calledwith My.Cool.Library:the same name as our repository on GitHub:

mkdir ~/dev/My.Cool.Library
cd ~/dev/My.Cool.LibraryCSharp.Mongo.Migration
dotnet new sln
dotnet new classlib
dotnet sln ./CSharp.Mongo.Migration.sln add ./CSharp.Mongo.Migration.csproj

The solution and project will be named based on the directory that you run the command from, or can be set explicitly using the --name argument.

Initially, the project will have the following folder structure:

~/
├─ dev/
│  ├─ CSharp.Mongo.Migration/
│  │  ├─ obj/
│  │  ├─ Class1.cs
│  │  ├─ CSharp.Mongo.Migration.csproj
│  │  ├─ CSharp.Mongo.Migration.sln

This structure would be perfectly fine for a very small library with a tiny number of code (cs) files, but may become unorganised as the library grows.

 

Back to top