Introduction

By Joe Audette

cloudscribe ™ is a loosely coupled collection of libraries for building web sites and applications on ASP.NET Core. The libraries are packaged as NuGet packages and available on NuGet.org and the source code is available on GitHub.com

There are 2 groups of libraries that correspond to the "big" features, cloudscribe Core and cloudscribe SimpleContent, and then there are a number of other libraries that provide various smaller functionality, that you may find useful in your projects even if you are not using the "big" cloudscribe features. See the Complete List of cloudscribe Libraries to get an idea of the breadth and scope of what cloudscribe provides for you.

cloudscribe is not a framework per se, it is a set of ready built functionality for common things needed by most web sites or applications. It is very extensible and customizable.  Most things that I think you might want to customize or change are implemented as interfaces so that you can easily inject your own custom implementations for various things, and some things are configurable by application settings. If you find something that you want to change but don't know how or can't find the information you need on how to change it, you can always ask questions in our gitter chat web page. I am open also to introducing more interfaces where needed if there is demand to customize things that are not currently easy to change, so it never hurts to ask.

Why Use cloudscribe?

When you start a new ASP.NET Core web project in Visual Studio using the built in project templates, at most you get a starter site that provides functionality to register and login, but it doesn't provide anything for managing users and role memberships and provides no way to make a user with administrative permissions. You would have to build that for yourself. When you start a new project with cloudscribe all of that and much more is built already and provided for you, so you don't have to build it yourself and you can immediately get working on the main features of your project instead of having to build a lot of common foundational functionality that most web projects need.

Getting Started

Prerequesites

You can use cloudscribe to develop web applications on Windows, Linux, or MacOS using the latest .NET Core SDK. You can use the .NET Core command line interface (CLI) to build, run, and publish your own projects. You can write code using your favorite text editor such as Visual Studio Code which is available free on all 3 operating systems. You can also use the full blown Visual Studio IDE on Windows or MacOS. On Windows you need Visual Studio 2017 version 15.3.3 or higher. I have not tried Visual Studio for Mac myself so let me know how it goes if you try it.

Starting New Projects in Visual Studio

We've made it very easy to get started building new projects with cloudscribe by providing an extension for Visual Studio 2017 (not yet tested on Visual Studio for Mac). You can download the cloudscribe Project Template extension free from the Visual Studio Marketplace. Close all instances of Visual Studio and double click the download to install. Then when you open Visual Studio you will see a new cloudscribe project template under the C# Web section.

When you create a new project a dialog window will appear to allow you to choose which data storage platform you wish to use and which cloudscribe features to include. Currently we have support for Microsoft SqlServer, MySql, PostgreSql, and NoDb "no database" file system storage. Every project will use cloudscribe Core, and you can optionally also include cloudscribe SimpleContent (a user friendly blog and content engine), cloudscribe Logging which logs to data storage and provides a UI for viewing the log, cloudscribe Simple Contact Form, Custom Registration with key/value pair storage, and integration with IdentityServer4 (forked for multi-tenancy).

Starting New Projects with the .NET CLI

We also have a project template that works with the dotnet new command using the .NET Core CLI, making it very easy to start new projects from the command line. To install the template (NuGet package) open a command window or powershell window and enter the following command:

dotnet new -i "cloudscribe.templates::*"

If you later want to uninstall the project template, you can use the command:

dotnet new -u cloudscribe

Once you have the cloudscribe project template installed you should enter the following command to see the available parameters that you can pass to the template in order to choose which data storage platform to use and which features to install:

PS C:\_c\scratch> dotnet new cloudscribe --help
Usage: new [options]

Options:
  -h, --help          Displays help for this command.
  -l, --list          Lists templates containing the specified name. If no name is specified, lists all templates.
  -n, --name          The name for the output being created. If no name is specified, the name of the current directory is used.
  -o, --output        Location to place the generated output.
  -i, --install       Installs a source or a template pack.
  -u, --uninstall     Uninstalls a source or a template pack.
  --type              Filters templates based on available types. Predefined values are "project", "item" or "other".
  --force             Forces content to be generated even if it would change existing files.
  -lang, --language   Specifies the language of the template to create.


cloudscribe web project template (C#)
Author: Joe Audette
Options:
  -T|--Title                  The name of the project which determines the assembly product name.
                              string - Optional
                              Default: Project Title

  -S|--SimpleContent          Include cloudscribe SimpleContent blog and content engine.
                              bool - Optional
                              Default: true

  -C|--ContactForm            Include cloudscribe SimpleContactForm.
                              bool - Optional
                              Default: false

  -K|--KvpCustomRegistration  Include cloudscribe key/value pair custom registration.
                              bool - Optional
                              Default: false

  -I|--IdentityServer         Include IdentityServer4 (fork) integration.
                              bool - Optional
                              Default: false

  -L|--Logging                Include cloudscribe logging and log viewer UI.
                              bool - Optional
                              Default: true

  -D|--DataStorage            The data storage platform you wish to use.
                                  NoDb     - A no-database file system storage
                                  MSSQL    - Microsoft SqlServer storage using Entity Framework Core
                                  pgsql    - PostgreSql storage using Entity Framework Core
                                  MySql    - MySql storage using Entity Framework Core
                              Default: MSSQL

  -H|--HttpsPort              Port number to use to configure SSL in launchSettings.json.
                              integer - Optional

  -Ke|--KestrelPort           Port number to use to configure Kestrel in launchSettings.json.
                              integer - Optional

  -II|--IISExpressPort        Port number to use to configure IIS Express in launchSettings.json.
                              integer - Optional


PS C:\_c\scratch>

So, for example to use all the available features with PostgreSql you would enter the commands:

mkdir yourprojectname
cd yourprojectname

dotnet new cloudscribe -D pgsql -S true -C true -K true -I true -L true

The first 2 commands are just creating a folder for your project and then moving into the folder. The folder name will be used as the project name. Note that while my example is explicitly passing in all the parameter values, you can leave out parameters if you are using the default values. You can also optionally pass in some parameters that are used for the kestrel and IIS web ports but I recommend leave those out so they will be randomly set to valid values.

UPDATE 2017-09-13

I have already updated the project template once to add a readme.html file that provides information about the features installed and next steps, login credentials etc. Note that the Visual Studio template automatically updates, but if you are using the command line, you need to uninstall and re-install to get the latest version of the template.

The StarterKits

The first way we created for people to get started with cloudscribe Core and/or cloudscribe SimpleContent was the StarterKits, which are a collection of ready to use .NET/Visual Studio solutions with cloudscribe components wired up in various common configurations. Now our new project templates are the best way to get started for new projects but we will keep the Starter Kits maintained going forward because they still can be used as a reference for how to wire things up if you are trying to integrate cloudscribe components into an existing application instead of starting a new project. You can publish those as they are, or customize them with your own code and then publish them. Visual Studio provides a way to publish to the file system which you would use for producing a set of files that could be uploaded to more traditional IIS web hosting, or linux hosting, or you can publish to Microsoft Azure, or even to Docker containers. We could package the published versions of the StarterKits as ready to deploy packages for you, but then you would not be able to add your own custom code. It is better that we provide you the StarterKit applications so that you can own the application itself and customize it for your needs.

Learn More Starting at These Main Topics

Comments