Skip to main content

Posts tagged with '.net'

Today, I’m presenting my C# Advent entry for December 25th, a project that emerged from the C# Advent series: CMSprinkle. (By the way, C# Advent merch is still on sale, but not for much longer).

What is CMSprinkle?

CMSprinkle is a micro content management system I developed specifically for the C# Advent website. Its creation was driven by the need for a straightforward and efficient way to manage small bits of content without the overhead of a full-blown CMS or even a headless CMS.

Features and Functionality

CMSprinkle is now available on NuGet and GitHub. It’s designed for ASP.NET Core web applications, particularly MVC projects. (It may also be adaptable to other ASP.NET Core projects, though this remains untested).

Here’s a quick walkthrough of setting up a new project with CMSprinkle:

  1. Creating a New Project: Start with a new ASP.NET Core web application, targeting .NET 8. (Alternatively, you should be able to add CMSprinkle to any existing ASP.NET Core web project that you already have available).

  2. Installing CMSprinkle: Add CMSprinkle from NuGet to your project. (dotnet add package CMSprinkle)

  3. Choosing a Data Provider: Select from available data providers like Couchbase (used by the C# Advent site) or SQL Server. The system is designed to be extensible, so feel free to contribute or request additional database support.

  4. Setting Up: After adding CMSprinkle, you’ll configure it in the views and program files: set up a tag helpers, and add services in your startup.

builder.Services.AddCouchbase(options =>
{
    options.ConnectionString = "couchbase://localhost";
    options.UserName = "Administrator";
    options.Password = "password";
});

// this adds auth to CMSprinkle
// if don't do this, it will be local only
// ExampleAuthClass enables anonymous public access, so don't use it as-is!
// builder.Services.AddTransient<ICMSprinkleAuth, ExampleAuthClass>();

// this adds CMSprinkle to your project
builder.Services.AddCMSprinkle(options =>
{
    // changes URL for cmsprinkle pages
    // if not specified, default is "cmsprinkle"
    // then URLs would be /cmsprinkle/home, etc
    options.RoutePrefix = "managecontent";

    // what message you want to show up when the
    // content hasn't been created yet
    // there is a default message if you don't specify this
    options.ContentNotFoundMessage = (contentKey) => $"ERROR: Can't find {contentKey}, did you add it yet?";
});

// this adds a Couchbase connection to CMSprinkle
builder.Services.AddCMSprinkleCouchbase("Example","_default","_default", createCollectionIfNecessary: true);

// or here's the SQLServer provider
// builder.Services.AddCMSprinkleSqlServer("Server=localhost;Database=Example;User Id=sa;Password=yourStrong(!)Password;TrustServerCertificate=True;", "SprinkleContent", "dbo",  createTableIfNecessary: true);

Managing Content

CMSprinkle aims to reduce friction in adding a CMS to your site. You define content keys directly in tag helpers and configure options like custom error messages for unfound content.

<div class="text-center">
    <h1 class="display-4">Welcome</h1>
    <p>Learn about <a href="https://learn.microsoft.com/aspnet/core">building Web apps with ASP.NET Core</a>.</p>

    @* this is how you sprinkle managed content into your pages *@
    @* make sure you add CMSPrinkle in _ViewImports.cshtml first *@
    @* this will say "ERROR: Content Not Found (HelloWorld)" until you actually create the content.*@
    <CMSprinkle contentKey="HelloWorld" />
</div>

The system also includes a management console for easy content addition and editing.

A Focus on Minimalism

The guiding principle of CM Sprinkle is minimalism. It’s ideal for existing ASP.NET Core websites that require very modest content management capabilities without the complexity of a full CMS. If you have specific features in mind that would make CMSprinkle more suitable for your project, feel free to submit an issue to the GitHub repository.

Video Introduction

You can watch a video introduction to CMSprinkle here, showing a demo in action:

Join the C# Advent Celebration

I invite you to dive into the rich collection of C# Advent entries for 2023. With 50 total entries on https://csadvent.christmas, there’s something for everyone.

I wish everyone a Merry Christmas and a Happy New Year! Thank you for participating in the C# Advent, and I hope to see you again next year.

Welcome to day 16 of the 2021 C# Advent! Make sure to check out all the other great Advent items that have been opened so far!

I have been working on an experimental tool called SqlServerToCouchbase. The goal is to help people automate their relational data moving and refactoring into a Couchbase JSON database as much as possible.

It is a .NET library that you can use (in, for example, a console project). It maps a relational concept like "table" to a NoSQL concept of "collection" (among other things). Couchbase is particularly suited to this, because Couchbase also supports SQL as a querying language (with JOINs / ACID / INSERT / UPDATE / etc), and has supported SQL for many years. If that sounds interesting to you, I’d love for you to leave your feedback, criticisms, suggestions, and even pull requests on GitHub.

What I want to focus on today, however, are three great .NET libraries that I used to help build SqlServerToCouchbase. Three wise gifts: SqlServer.Types (gold), Dynamitey (frankincense), and Humanizer (myrrh).

dotMorten.Microsoft.SqlServer.Types (Gold)

The gift of gold signified that the receiver was as important as a king.

Gold

SQL Server has many data types. Mapping these data types into C# types (and ultimately to JSON) is usually straightfoward.

  • varchar, nvarchar, text? string.

  • int, float, decimal, money? number.

  • bit? boolean.

  • Even XML can become a string.

But what about the other types? Spatial types, mainly: Geography and geometry? That’s what Microsoft.SqlServer.Types is for: to provide C# types that can store propietary SQL Server data type values.

However, notice the "dotMorten" part of the library name? Unfortunately, the official Microsoft.SqlServer.Types library is not a .NET Standard library. So, Morten Nielsen created the dotMorten.Microsoft.SqlServer.Types library.

There’s a code example below, but you won’t see the library in action explicitly.

// SqlServerFrom.cs
public IEnumerable<dynamic> QueryBulk(IDbConnection conn, SqlPipelineBase pipeline)
{
    return conn.Query(pipeline.Query, buffered: false);
}

// SqlToCb.cs
foreach(var row in rows)
{
    // ... snip ...
    await collection.UpsertAsync(documentKey, row);
    // ... snip ...
}

I use Dapper to query SQL Server data, store those results in C# dynamic objects, and then give those objects to the Couchbase .NET SDK (which ultimately serialized it to JSON).

That means that a row of SQL Server data, like this:

SELECT a.AddressID, a.SpatialLocation
FROM AdventureWorks2016.Person.Address a
WHERE a.AddressID = 1

Row of SQL Server data

Gets transformed into a Couchbase JSON document like this:

SELECT a.AddressID, a.SpatialLocation
FROM AdventureWorks2016.Person.Address a
WHERE a.AddressID = 1;
[ {
    "AddressID": 1,
    "SpatialLocation": {
      "HasM": false,
      "HasZ": false,
      "IsNull": false,
      "Lat": 47.7869921906598,
      "Long": -122.164644615406,
      "M": null,
      "STSrid": 4326,
      "Z": null
    }
} ]

So, even if a SQL Server database is using one of these less common data types, SqlServerToCouchbase can still move it.

Dynamitey

The second gift is frankincense. This is an expensive incense fit for a holy king.

Frankincense

Another challenge of SqlServerToCouchbase is getting the value of the primary key. In Couchbase, a document key exists as a piece of "metadata" about the document. However, in SQL Server, a primary key consists of one (usually) or more (uncommon) fields in a table. These fields can have ANY name. Usually it’s something like "ID", "AddressID", "ADDRESS_ID", etc. But it can vary from table to table.

Once I know the names of the fields, I need to examine the dynamic object to get the values of those fields. This is where I use Dynamitey.

Dynamitey is a utility library that provides extensions to the DLR, including:

  • Easy Fast DLR based Reflection (what I’m using it for)

  • Clean syntax for using types from late bound libraries

  • Dynamic Currying

  • Manipulation of Tuples

And more.

Key names can be retrieved from SQL Server by querying INFORMATION_SCHEMA.KEY_COLUMN_USAGE. I can use those names to get the values like so:

// append key values together with :: delimeter
// for compound keys
var keys = await _config.GetPrimaryKeyNames(tableSchema, tableName, _dbFrom);
var newKey = string.Join("::", keys.Select(k => Dynamic.InvokeGet(row, k)));

If a primary key is made up of one column and the row has a value of "1", then that becomes the document key in Couchbase. If a primary key is made up of multiple columns, with values of "123" and "456", that becomes a document key in Couchbase of "123::456".

If it weren’t for Dynamitey, I’d have to create C# classes for every table. And that greatly reduces the amount of automation.

Humanizer

The third gift is myrrh. Another expensive gift. This one is fit for a holy, but also human king.

Myrrh

Humanizer is a .NET library that manipulates string, dates, numbers, etc, for display to a human. There are many things it can do, but I use it for pluralization.

When making the transition from relational to Couchbase, one of the things you must consider is when to embed data into documents. For instance, in relational, you may have two tables (Person and EmailAddress) in order to support a situation where a person has more than 1 email addresses.

SELECT p.BusinessEntityID, p.FirstName, P.LastName
FROM AdventureWorks2016.Person.Person p
WHERE p.BusinessEntityID = 1

SELECT e.EmailAddress
FROM AdventureWorks2016.Person.EmailAddress e
WHERE e.BusinessEntityID = 1

Relational modeling

(In this example, there’s only 1 email address, but the model supports more).

In a document database like Couchbase, it’s often preferable (though not required) to embed those email addresses into an array in the person document. Something like:

{
  "BusinessEntityID" : 1,
  "FirstName" : "Ken",
  "LastName" : "Sánchez",
  "????" : [
    { "EmailAddress" : "[email protected]"}
  ]
}

But what do I put into the "????" in that JSON? If I use the name of the table ("EmailAddress"), that implies that there’s only one. I would rather it be called "EmailAddresses". Hence, I use Humanizer to pluralize it:

spec.ArrayAppend(From.TableName.Pluralize(), docToEmbed.ContentAs<dynamic>(), true);

So, now it becomes:

{
  "BusinessEntityID" : 1,
  "FirstName" : "Ken",
  "LastName" : "Sánchez",
  "EmailAddresses" : [
    { "EmailAddress" : "[email protected]"}
  ]
}

Thanks for checking out these three libraries! I hope these will help you some day. Don’t forget to check out the rest of the 2021 C# Advent.

Kevin Griffin is using SignalR to update web pages live. This episode is not sponsored! Want to be a sponsor? You can contact me or check out my sponsorship gig on Fiverr

Show Notes:

Kevin Griffin is on Twitter

Want to be on the next episode? You can! All you need is the willingness to talk about something technical.

Peter Lorimer has built the ASPeKT AOP framework. This episode is sponsored by Uncall.

Show Notes:

Want to be on the next episode? You can! All you need is the willingness to talk about something technical.

Matthew D. Groves

About the Author

Matthew D. Groves lives in Central Ohio. He works remotely, loves to code, and is a Microsoft MVP.

Latest Comments

Twitter