Getting Started

Environment Setup

Before you begin, ensure that you have all the requisite tools installed

• Recent version of the .NET SDK. If you have Visual Studio, you already have this.
• A recent version of Node.js (an LTS version is recommended).
• A compatible IDE
  • Recommended:
    • Visual Studio for backend (C#) development
    • VS Code for frontend (Vue, TypeScript) development (with Vue - Official)
  • Alternatively, you could use any of these:
    • VS Code for full stack development
    • JetBrains Rider

Creating a Project

The quickest and easiest way to create a new Coalesce Vue application is to use the dotnet new template.

First, select the features that you would like included in your project, and choose the root .NET namespace of your project:

ASP.NET Core Identity

--Identity

Adds ASP.NET Core Identity, providing user storage, authentication, and authorization mechanisms. Also includes a permission-based security model. If you don't include Identity, you'll have to build your auth stack from scratch. Read More

Sign-in with Microsoft

--MicrosoftAuth

Adds Microsoft as an external authentication and account provider for Identity. Read More

Requires ASP.NET Core Identity

Sign-in with Google

--GoogleAuth

Adds Google as an external authentication and account provider for Identity. Read More

Requires ASP.NET Core Identity

Sign-in with Username/Password

--LocalAuth

Adds infrastructure for supporting individual user accounts with first-party usernames and passwords. Read More

Requires ASP.NET Core Identity

User Profile Pictures

--UserPictures

Adds infrastructure for acquiring, saving, and displaying user profile pictures.

Requires ASP.NET Core Identity

Tracking Base

--TrackingBase

Include a base entity class for tracking created/modified by and date stamps on each entity, and infrastructure for automatically setting those fields.

Audit Logging

--AuditLogs

Adds Coalesce audit logging infrastructure, logging each change made to the database through Entity Framework. Read More

Dark Mode Toggle

--DarkMode

Adds features for user-togglable dark mode. Don't use if you're developing a light-only or dark-only application.

Sample Page

--ExampleModel

Includes a 'Widget' example model with a basic Vue page, frontend tests, and backend tests.

OpenAPI/Swagger

--OpenAPI

Include configuration to expose an OpenAPI document and SwaggerUI using Swashbuckle.

Tenancy: Core

--Tenancy

Includes core infrastructure for supporting multiple tenants within one shared database, with shared user accounts.

Requires ASP.NET Core Identity

Tenancy: Creation by Self-service

--TenantCreateSelf

Allows any signed in user to create additional tenants.

Requires Tenancy: Core

Tenancy: Creation by Global Admin

--TenantCreateAdmin

Allows global admins to create new tenants.

Requires Tenancy: Core

Tenancy: Creation/Membership by OIDC

--TenantCreateExternal

Automatically creates a new tenant for external organizations (Microsoft Entra, Google GSuite), and grants automatic tenant membership to other users within those organizations.

Requires Tenancy: Core and (Sign-in with Microsoft or Sign-in with Google)

Tenancy: Membership by Invitation

--TenantMemberInvites

Allows administrators within a tenant to create invitation links to grant membership to their tenant.

Requires Tenancy: Core

Azure Application Insights

--AppInsights

Include configuration and integrations for Application Insights, both front-end and back-end. Read More

Email: Azure Communication Services

--EmailAzure

Include basic code for sending email with Azure Communication Services. See instructions in appsettings.json - the official ACS documentation is very confusing. Read More

Email: Twilio SendGrid

--EmailSendGrid

Include basic code for sending email with Twilio SendGrid. Read More

CI: Azure Pipelines

--AzurePipelines

Include an azure-pipelines.yml build template. For deployments, a release pipeline is recommended (which don't support YAML config files). Read More

CI: Github Actions

--GithubActions

Include an build-test-and-deploy.yml github action file template. Read More

---

Root Namespace:

Next, click the button or manually copy the commands below into your favorite terminal, and execute them! This will create a root folder named MyProject - execute the script in your sources/repos/etc folder.

dotnet new install IntelliTect.Coalesce.Vue.Template
dotnet new coalescevue -n MyCompany.MyProject -o MyProject --Identity --TrackingBase --DarkMode --AuditLogs --UserPictures
cd MyProject/*.Web
npm ci
npm run lint:fix
dotnet restore
dotnet coalesce

You now have a new Coalesce project! For the recommended development experience, open the .Web project in VS Code and open the root .sln file in Visual Studio.

If any of the options you chose above require external integrations, you'll need to configure those - follow the instructions for each section that have been placed into appsettings.json.

Project Structure

Data Project

The data project contains all your entity models, services, and most other custom backend code that you'll write while building your application. The code within it acts as the inputs to Coalesce's code generation, which outputs generated files into the Web project.

Web Project

The Web project is an ASP.NET Core application where the generated outputs from Coalesce are placed. It's also where you'll build your rich front-end pages that users will use to interact with your application.

The structure of the Web project follows the conventions of both ASP.NET Core and Vite. The frontend-specific folders are as follows:

• /src - Files that should be compiled into your frontend application. CSS/SCSS, TypeScript, Vue SFCs, and so on.
• /public - Static assets that should be served directly as files.
• /wwwroot - Target for Vite's compiled output. This directory is excluded from git.
• /Api/Generated - Output target for Coalesce's generated API Controllers.
• /Models/Generated - Output target for Coalesce's generated DTOs.
• /Controllers/HomeController.cs - Controller that serves the root page of your Vue SPA, both in development and production. Some customizations can be added here.

Important

The frontend build system uses Vite. You are strongly encouraged to read through at least the first few pages of the Vite Documentation before getting started on any development.

During development, no special effort is required to build your frontend code. Coalesce's UseViteDevelopmentServer in ASP.NET Core will take care of that automatically when the application starts. Just make sure NPM packages have been installed (npm ci).

Data Modeling

At this point, you can open up the newly-created solution in Visual Studio and run your application. However, your application won't do much without a data model, so you will probably want to do the following:

• Create an initial Data Model by adding EF entity classes to the data project and the corresponding DbSet<> properties to AppDbContext. You will notice that the starter project includes a single model, Widget, to start with. Feel free to change this model or remove it entirely. Read Entity Models for more information about creating a data model.

• Run dotnet ef migrations add Init (Init can be any name) in the data project to create an initial database migration.

• Run Coalesce's code generation by either:

  • Running dotnet coalesce in the web project's root directory (dotnet restore first if you get an error about "command or file was not found").
  • Running the coalesce npm script in the Task Runner Explorer, or in a terminal with npm run coalesce.

You're now at a point where you can start creating your own pages!

Building Pages & Features

Lets say we've created a model called Person as follows, and we've ran code generation with dotnet coalesce:

namespace MyApplication.Data.Models 
{
    public class Person
    {
        public int PersonId { get; set; }
        public string Name { get; set; }
        public DateTimeOffset? BirthDate { get; set; }
    }
}

We can create a details page for a Person by creating a Single File Component in MyApplication.Web/src/views/person-details.vue:

<template>
  <dl>
    <dt>Name</dt>
    <dd>
      <c-display :model="person" for="name" />
    </dd>

    <dt>Date of Birth</dt>
    <dd>
      <c-display :model="person" for="birthDate" format="M/d/yyyy" />
    </dd>
  </dl>
</template>

<script setup lang="ts"> 
import { PersonViewModel } from "@/viewmodels.g";

const props = defineProps<{ id: number }>();
const person = new PersonViewModel();

person.$load(props.id);
</script>

Note

In the code above, c-display is a component that comes from the Vuetify Components for Coalesce.

For simple property types like string and number you can always use simple template interpolation syntax, but for more complex properties like dates, c-display is handy to use because it includes features like built-in date formatting.

We then need to add route to this new view. In MyApplication.Web/src/router.ts, add a new item to the routes array:

// In the `routes` array, add the following item:
{
  path: '/person/:id',
  name: 'person-details',
  component: () => import('@/views/person-details.vue'),
  props: route => ({ id: +route.params.id }),
},

With these pieces in place, we now have a functioning page that will display details about a person. We can start up the application (or, if it was already running, refresh the page) and navigate to /person/1 (assuming a person with ID 1 exists - if not, navigate to /admin/Person and create one).

From this point, you can start adding more fields, more features, and more flair to the page. Check out all the other documentation in the sidebar to see what else Coalesce has to offer, including the Vue Overview.