Quickstart

This guide will get you up and running with Xams and covers the following:

Creating tables
Displaying and creating records from a datatable
Writing service logic
Creating forms

Templates

Clone one of the following templates from GitHub to get started quickly.

Install EF Core Tools

Ensure you have version 8+ of the Entity Framework Core tools installed.

Terminal

dotnet tool install --global dotnet-ef

Create an Entity

In the ASP.NET project create a new class file in the Entities folder and name it "Widget.cs"

Project / Entities / Widget.cs

[Table(nameof(Widget))]
public class Widget
{
    public Guid WidgetId { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

Add the Widget class to the DataContext class.

Project / DataContext.cs

public class DataContext : XamsDbContext
{
    public DbSet<Widget> Widgets { get; set; }
    ...
}

In the ASP.NET project directory execute the commands below to create a migration and update the database.

Terminal

dotnet ef migrations add migration01
dotnet ef database update

Run the https project. You can access the admin dashboard by navigating to /xams in your browser. In development you can provide the user id of any user you want to impersonate via the query string. For example, to impersonate the SYSTEM user: https://localhost:7102/xams?userid=f8a43b04-4752-4fda-a89f-62bebcd8240c

A new Xams project isn't configured with Authentication or Authorization but still has users. Whenever the api starts, it creates system records. One of those system records is the "SYSTEM" user. The Id of this user is always f8a43b04-4752-4fda-a89f-62bebcd8240c.

Create a Datatable

In the NextJs project run npm install
Run npm run dev to start the development server and navigate to http://localhost:3000/?userid=f8a43b04-4752-4fda-a89f-62bebcd8240c
Paste the following code in index.tsx

src / pages / index.tsx

import { DataTable } from '@ixeta/xams'
import React from 'react'

const Index = () => {
  return (
    <div className="h-96 w-[500px] p-10">
      <DataTable tableName="Widget"></DataTable>
    </div>
  )
}

export default Index

This will create the following table.

If you click the "Add" button on the table, a form will open where a new record can be created.

Add Service Logic

We can have the service layer automatically set a price for the Widget based on the number of Widgets in the database.

Create a new folder named Services. Create a new class file in the Services folder and name it "WidgetService.cs"
Replace the class in the file with the code below.

Project / Services / WidgetService.cs

// Execute on Create or Update of the Widget entity before the Save to the database.
[ServiceLogic(nameof(Widget), DataOperation.Create | DataOperation.Update, LogicStage.PreOperation)]
public class WidgetService : IServiceLogic
{
    public async Task<Response<object?>> Execute(ServiceContext context)
    {
        var db = context.GetDbContext<DataContext>();

        // Get the entity being saved
        Widget widget = context.GetEntity<Widget>();

        var countWidgets = await db.Widgets.CountAsync();

        // Only set on create
        if (context.DataOperation is DataOperation.Create)
        {
            // Because this is a PreOperation (before save), the Price will
            // eventually get saved to the database
            widget.Price = countWidgets * 10.5M;
        }

        return ServiceResult.Success();
    }
}

Create a Record

Replace the code in index.tsx with the following.

src / pages / index.tsx

import { useAuthRequest } from '@ixeta/xams'
import { Button } from '@mantine/core'
import React from 'react'

const Index = () => {
  const authRequest = useAuthRequest()

  const onClick = async () => {
    const resp = await authRequest.create('Widget', {
      Name: 'My Widget',
      Price: 9.99,
    })
    if (!resp.succeeded) {
      return
    }
  }

  return <Button onClick={onClick}>Create Widget</Button>
}

export default Index

When the button is clicked, a Widget record will be created with the provided data.

Create a Form

Replace the code in index.tsx with the following.

src / pages / index.tsx

import { Field, FormContainer, SaveButton, useFormBuilder } from '@ixeta/xams'
import { Grid } from '@mantine/core'
import React from 'react'

const Index = () => {
  // Use the useFormBuilder hook to specify the table we're creating the form for
  const formBuilder = useFormBuilder({
    tableName: 'Widget',
  })

  return (
    <div className="h-full w-full max-w-md p-6">
      {/* Create a form container for this table's fields */}
      <FormContainer formBuilder={formBuilder}>
        <div className="flex flex-col gap-4">
          <Grid>
            <Grid.Col span={6}>
              {/* Define the table fields to bind to */}
              <Field name="Name" />
            </Grid.Col>
            <Grid.Col span={6}>
              <Field name="Price" />
            </Grid.Col>
          </Grid>
          <SaveButton />
        </div>
      </FormContainer>
    </div>
  )
}

export default Index

This will create the below form:

Build and Deploy

When you're ready to deploy your application:

In the NextJS project directory, build the static site:

Terminal

npm run build

The build outputs to the out folder. Copy the contents of this folder to the wwwroot directory in your ASP.NET project.
Run your ASP.NET application - it will serve the static NextJS site.