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 (which provides multi-tenant or single tenant web application foundation with management for user, roles, claims and more) and cloudscribe SimpleContent (a very user friendly content and blog engine), 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.  There is also an option to include a webpack setup for client side development and using sass with bootstrap for custom theme design, but be aware that option requires additional tooling to be installed.

There is also a youtube demo of project creation with our Visual Studio project template.

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:\_demo> 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:                                                                                                                
  -M|--MultiTenantMode        Multi-tenancy configuration.                                                              
                                  FolderName    - There is a root tenant, and other tenants can be added starting at a folder segment.
                                  HostName      - You will be able to create additional sites by specifying a host name. Additional tenants require DNS and web server settings.
                                  None          - A single tenant installation. This can be changed later by configuration.
                              Default: FolderName                                                                       

  -S|--SimpleContentConfig    SimpleContent configuration.                                                              
                                  a    - Pages and Bog with Pages as default route                                      
                                  b    - Pages and Blog with Home Controller as default route                           
                                  c    - Blog ONLY with Blog as default route                                           
                                  d    - Blog ONLY with Home Controller as default route                                
                                  z    - Not installed, SimpleContent will not be included                              
                              Default: a                                                                                

  -N|--NonRootPagesSegment    If you are using SimpleContent pages with SimpleContentConfig option b, this will be used as the url segment for the pages to start at.
                              string - Optional                                                                         
                              Default: p                                                                                

  -No|--NonRootPagesTitle     If you are using SimpleContent pages with SimpleContentConfig option b, this will be used as the title for the pages top level menu item.
                              string - Optional                                                                         
                              Default: Articles                                                                         

  -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 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                                                                            

  -W|--Webpack                Include client side development setup with webpack, typescript, and theme ready to customize using bootstrap-sass. This is an advanced option and requires that you have node and npm installed.
                              bool - Optional                                                                           
                              Default: false                                                                            

  -R|--ReactSample            Include a react sample client app, requires Webpack to be true                            
                              bool - Optional                                                                           
                              Default: true                                                                             

  -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:\_demo>

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 a -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.

Note that the template creates a readme.html file that is customized with information depending on which features and configurations you use when you create your project. This readme.html file is opened automatically if you use the Visual Studio project template but it doesn't open automatically if you use the command line so you should open it manually in that case. It has information about the default login credentials and any additional configuration that may be needed for the features you have included in your project.

Publishing

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

You can also publish from the command line using the .NET Core CLI.

Samples

We have a few samples here and will add more over time as needed: https://github.com/joeaudette/cloudscribe.Samples

For some of the more advanced scenarios it can be useful to see working demos that are already populated with data. For example we have a sample with IdentityServer4 integration and several working client applications that authenticate with IdentityServer4 using JWT authentication to protect the web apis. You may find that helpful to compare how it is setup if you have any trouble getting your own client applications working.

Learn More Starting at These Main Topics

Comments