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 and TypeScript Vue Plugin)
- Also consider:
- VS Code for full stack development.
- JetBrains Rider
- Recommended:
Creating a Project
The quickest and easiest way to create a new Coalesce Vue application is to use the dotnet new
template. In your favorite shell:
dotnet new install IntelliTect.Coalesce.Vue.Template
dotnet new coalescevue -o MyCompany.MyProject
cd MyCompany.MyProject/*.Web
npm ci
Project Structure
Important
The Vue template is based on Vite. You are strongly encouraged to read through at least the first few pages of the Vite Documentation before getting started on any development.
The structure of the Web project follows the conventions of both ASP.NET Core and Vite. The Vue-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 as files. Includes index.html, the root document of the application./wwwroot
- Target for compiled output. This directory is excluded from git.
During development, no special tooling 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 before running:
Create an initial Data Model by adding EF entity classes to the data project and the corresponding
DbSet<>
properties toAppDbContext
. 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 - Running the
coalesce
npm script (Vue) or gulp task (Knockout) in the Task Runner Explorer
- Running
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.