afonsoft/create-abp-io-template

Create ABP.IO Template

Create a new ABP.IO project using the ABP CLI with proper template selection, configuration, and initial setup.

Primary Directive

Your goal is to create a new ABP.IO project using the CLI with the appropriate template, configuration, and setup based on the specified requirements.

ABP CLI Installation

Install ABP CLI

# Install ABP CLI globally
dotnet tool install -g Volo.Abp.Cli

# Verify installation
abp --version

# Update to latest version
abp update

Alternative Installation Methods

# Install specific version
dotnet tool install -g Volo.Abp.Cli --version 8.0.0

# Install from local source
dotnet tool install -g Volo.Abp.Cli --add-source ./local-packages

Available Templates

1. Application Template (app)

Standard layered application for most scenarios.

Use Cases:

• Medium to large applications
• Multiple developers or teams
• Long-term maintainability required
• Complex business domains

Command:

abp new <solution-name> -t app [options]

2. Single-Layer Template (app-nolayers)

Simplified template for small applications.

Use Cases:

• Small project with simple requirements
• 1-3 developers team
• Temporary or POC projects
• No expected growth in complexity

Command:

abp new <solution-name> -t app-nolayers [options]

3. Microservice Template (microservice)

For distributed microservice architectures.

Use Cases:

• Very large distributed systems
• Independent deployment needed
• Multiple technology stacks
• High scalability requirements

Command:

abp new <solution-name> -t microservice [options]

4. Empty Template (empty)

Minimal template for custom solutions.

Use Cases:

• Custom architecture requirements
• Learning ABP framework
• Minimal starting point

Command:

abp new <solution-name> -t empty [options]

Configuration Options

UI Framework Options (-u, --ui-framework)

• mvc: ASP.NET Core MVC (default)
• angular: Angular SPA
• blazor-webapp: Blazor Web App
• blazor: Blazor Server
• blazor-server: Blazor Server
• no-ui: No UI layer

Database Provider Options (-d, --database-provider)

• ef: Entity Framework Core (default)
• mongodb: MongoDB

Mobile Options (-m, --mobile)

• none: No mobile app (default)
• react-native: React Native
• maui: .NET MAUI

Architecture Options

• --tiered: Creates tiered architecture (separate API and UI layers)
• --separate-tenant-schema: Different DbContext for tenant schema

Theme Options (-th, --theme)

• leptonx: LeptonX Theme (premium)
• leptonx-lite: LeptonX-Lite Theme (default)
• basic: Basic Theme

Additional Options

• --connection-string: Custom database connection string
• --skip-migrations: Skip initial database migration
• --skip-migrator: Skip database migrator
• --public-website: Add public website (PRO)
• --without-cms-kit: Exclude CmsKit module
• --sample-crud-page: Add sample CRUD page
• --use-open-source-template: Use open-source template

Template Selection Guide

Decision Tree

1. Project Size & Complexity

• Small/Simple → Single-Layer
• Medium/Complex → Layered
• Large/Distributed → Microservice

2. Team Size

• 1-3 developers → Single-Layer
• 4+ developers → Layered
• Multiple teams → Microservice

3. UI Requirements

• Web only → MVC
• SPA experience → Angular
• Modern web → Blazor
• No UI needed → no-ui

4. Database Needs

• Relational → EF Core
• Document → MongoDB

Common Template Commands

Standard Web Application

# Basic MVC application
abp new Acme.BookStore

# With specific options
abp new Acme.BookStore -t app -u mvc -d ef -th leptonx-lite

# With custom connection string
abp new Acme.BookStore -t app -u mvc -d ef --connection-string "Server=localhost;Database=BookStore;Trusted_Connection=true"

Angular SPA Application

# Angular application
abp new Acme.BookStore -t app -u angular -d ef

# Angular with tiered architecture
abp new Acme.BookStore -t app -u angular -d ef --tiered

# Angular with PWA
abp new Acme.BookStore -t app -u angular -d ef --progressive-web-app

Blazor Application

# Blazor Web App
abp new Acme.BookStore -t app -u blazor-webapp -d ef

# Blazor Server
abp new Acme.BookStore -t app -u blazor-server -d ef

# Blazor with tiered architecture
abp new Acme.BookStore -t app -u blazor-webapp -d ef --tiered

Microservice Solution

# Basic microservice
abp new Acme.Microservice -t microservice -u mvc -d ef

# Microservice with Angular
abp new Acme.Microservice -t microservice -u angular -d ef

# Microservice with multiple services
abp new Acme.Microservice -t microservice -u mvc -d ef --tiered

Simple API Project

# Single-layer API
abp new Acme.Api -t app-nolayers -u no-ui -d ef

# API with sample CRUD
abp new Acme.Api -t app-nolayers -u no-ui -d ef --sample-crud-page

Implementation Workflow

Step 1: CLI Preparation

# Ensure ABP CLI is installed
abp --version

# Update to latest version
abp update

# Verify available templates
abp list-templates

Step 2: Project Creation

# Create project with selected template
abp new <solution-name> [options]

# Example: Create layered MVC application
abp new Acme.BookStore -t app -u mvc -d ef -th leptonx-lite

Step 3: Initial Setup

# Navigate to project directory
cd <solution-name>

# Restore packages
dotnet restore

# Create and apply database migrations
dotnet ef database update

# Run the application
dotnet run --project src/<solution-name>.Web

Step 4: Verification

# Verify solution builds
dotnet build

# Run tests
dotnet test

# Check application startup
# Navigate to https://localhost:44300

Project Structure Examples

Layered Application Structure

Acme.BookStore.sln
├── src/
│   ├── Acme.BookStore.Application/
│   │   ├── BookStoreApplicationModule.cs
│   │   ├── Books/
│   │   │   ├── BookAppService.cs
│   │   │   └── IBookAppService.cs
│   │   └── Acme.BookStore.Application.csproj
│   ├── Acme.BookStore.Application.Contracts/
│   │   ├── Books/
│   │   │   ├── BookDto.cs
│   │   │   └── IBookAppService.cs
│   │   └── Acme.BookStore.Application.Contracts.csproj
│   ├── Acme.BookStore.Domain/
│   │   ├── BookStoreDomainModule.cs
│   │   ├── Books/
│   │   │   ├── Book.cs
│   │   │   └── IBookRepository.cs
│   │   └── Acme.BookStore.Domain.csproj
│   ├── Acme.BookStore.Domain.Shared/
│   │   ├── BookStoreDomainSharedModule.cs
│   │   └── Acme.BookStore.Domain.Shared.csproj
│   ├── Acme.BookStore.EntityFrameworkCore/
│   │   ├── BookStoreEntityFrameworkCoreModule.cs
│   │   ├── BookStoreDbContext.cs
│   │   ├── Configurations/
│   │   │   └── BookConfiguration.cs
│   │   └── Acme.BookStore.EntityFrameworkCore.csproj
│   ├── Acme.BookStore.HttpApi/
│   │   ├── BookStoreHttpApiModule.cs
│   │   ├── Controllers/
│   │   │   └── BooksController.cs
│   │   └── Acme.BookStore.HttpApi.csproj
│   ├── Acme.BookStore.HttpApi.Client/
│   │   └── Acme.BookStore.HttpApi.Client.csproj
│   ├── Acme.BookStore.Web/
│   │   ├── BookStoreWebModule.cs
│   │   ├── Pages/
│   │   ├── wwwroot/
│   │   └── Acme.BookStore.Web.csproj
│   └── Acme.BookStore.Web.Unified/
├── test/
│   ├── Acme.BookStore.Application.Tests/
│   ├── Acme.BookStore.Domain.Tests/
│   ├── Acme.BookStore.EntityFrameworkCore.Tests/
│   ├── Acme.BookStore.Web.Tests/
│   └── Acme.BookStore.HttpApi.Host.Tests/
└── etc/
    └── docker-compose.yml

Single-Layer Application Structure

Acme.SimpleApp.sln
├── src/
│   ├── Acme.SimpleApp.Application/
│   │   ├── SimpleAppApplicationModule.cs
│   │   ├── Books/
│   │   │   ├── BookAppService.cs
│   │   │   └── Book.cs
│   │   └── Acme.SimpleApp.Application.csproj
│   ├── Acme.SimpleApp.Application.Contracts/
│   │   └── Acme.SimpleApp.Application.Contracts.csproj
│   ├── Acme.SimpleApp.Domain.Shared/
│   │   └── Acme.SimpleApp.Domain.Shared.csproj
│   ├── Acme.SimpleApp.EntityFrameworkCore/
│   │   ├── SimpleAppDbContext.cs
│   │   └── Acme.SimpleApp.EntityFrameworkCore.csproj
│   ├── Acme.SimpleApp.HttpApi/
│   │   └── Acme.SimpleApp.HttpApi.csproj
│   └── Acme.SimpleApp.Web/
│       ├── Program.cs
│       ├── Pages/
│       └── Acme.SimpleApp.Web.csproj
└── test/
    ├── Acme.SimpleApp.Application.Tests/
    ├── Acme.SimpleApp.EntityFrameworkCore.Tests/
    └── Acme.SimpleApp.Web.Tests/

Advanced Configuration

Database Provider Configuration

SQL Server (Default)

abp new Acme.BookStore -t app -u mvc -d ef

PostgreSQL

abp new Acme.BookStore -t app -u mvc -d ef
# Then manually update to PostgreSQL in appsettings.json

SQLite

abp new Acme.BookStore -t app -u mvc -d ef
# Then manually update to SQLite in DbContext

MongoDB

abp new Acme.BookStore -t app -u mvc -d mongodb

Authentication Configuration

Built-in Authentication

abp new Acme.BookStore -t app -u mvc -d ef
# Default includes OpenIddict authentication

Custom Authentication

abp new Acme.BookStore -t app -u mvc -d ef
# Configure custom authentication in WebModule

Multi-Tenancy Configuration

Shared Database

abp new Acme.BookStore -t app -u mvc -d ef
# Default multi-tenancy with shared database

Separate Tenant Schema

abp new Acme.BookStore -t app -u mvc -d ef --separate-tenant-schema
# Different schema for each tenant

Post-Creation Customization

1. Package Management

# Add additional packages
abp add-package Volo.Abp.Emailing
abp add-package Volo.Abp.Sms
abp add-package Volo.Abp.Caching

# Add module
abp add-module Volo.CmsKit

2. Configuration Updates

// appsettings.json
{
  "ConnectionStrings": {
    "Default": "Server=localhost;Database=AcmeBookStore;Trusted_Connection=true"
  },
  "App": {
    "SelfUrl": "https://localhost:44300",
    "CorsOrigins": "https://localhost:44300"
  },
  "AuthServer": {
    "Authority": "https://localhost:44300",
    "RequireHttpsMetadata": "false"
  },
  "StringLocalizations": {
    "Languages": [
      {
        "CultureName": "en",
        "DisplayName": "English"
      },
      {
        "CultureName": "pt-BR",
        "DisplayName": "Português"
      }
    ]
  }
}

3. Database Configuration

# Create initial migration
dotnet ef migrations add InitialCreate

# Update database
dotnet ef database update

# Add new migration
dotnet ef migrations add AddedBookEntity

4. First Entity Creation

// src/Acme.BookStore.Domain/Books/Book.cs
public class Book : FullAuditedAggregateRoot<Guid>
{
    public string Name { get; set; }
    public BookType Type { get; set; }
    public DateTime PublishDate { get; set; }
    public float Price { get; set; }
    
    protected Book() { }
    
    public Book(
        Guid id, 
        string name, 
        BookType type, 
        DateTime publishDate, 
        float price) : base(id)
    {
        Name = Check.NotNullOrWhiteSpace(name, nameof(name));
        Type = type;
        PublishDate = publishDate;
        Price = price;
    }
}

5. Application Service

// src/Acme.BookStore.Application/Books/BookAppService.cs
public class BookAppService : ApplicationService, IBookAppService
{
    private readonly IRepository<Book, Guid> _bookRepository;

    public BookAppService(IRepository<Book, Guid> bookRepository)
    {
        _bookRepository = bookRepository;
    }

    public async Task<PagedResultDto<BookDto>> GetListAsync(GetBooksInput input)
    {
        var queryable = await _bookRepository.GetQueryableAsync();
        
        var books = await AsyncExecuter.ToListAsync(
            queryable
                .WhereIf(!input.Filter.IsNullOrWhiteSpace(), 
                    book => book.Name.Contains(input.Filter))
                .OrderBy(book => book.Name)
                .PageBy(input.SkipCount, input.MaxResultCount)
        );

        var totalCount = await AsyncExecuter.CountAsync(
            queryable.WhereIf(!input.Filter.IsNullOrWhiteSpace(), 
                book => book.Name.Contains(input.Filter))
        );

        return new PagedResultDto<BookDto>(
            totalCount,
            ObjectMapper.Map<List<Book>, List<BookDto>>(books)
        );
    }
}

Development Tools Integration

ABP Suite Integration

# Install ABP Suite (separate tool)
# Generate CRUD pages automatically
# Create entities with visual designer
# Manage application settings

ABP Studio Integration

# Open project in ABP Studio
# Visual module management
# Advanced debugging tools
# Performance monitoring

Docker Support

# Build Docker image
docker build -t acme/bookstore .

# Run with Docker Compose
docker-compose up -d

# Database migrations in Docker
docker-compose exec web dotnet ef database update

Troubleshooting

Common Issues and Solutions

1. CLI Not Found

# Install ABP CLI
dotnet tool install -g Volo.Abp.Cli

# Check PATH
echo $PATH

# Reinstall if corrupted
dotnet tool uninstall -g Volo.Abp.Cli
dotnet tool install -g Volo.Abp.Cli

2. Template Creation Fails

# Check .NET SDK version
dotnet --version

# Clear NuGet cache
dotnet nuget locals all --clear

# Use specific template version
abp new Acme.BookStore -t app --use-open-source-template

3. Database Issues

# Check connection string
dotnet ef database update --verbose

# Recreate database
dotnet ef database drop
dotnet ef database update

# Check migrations
dotnet ef migrations list

4. Build Errors

# Clean and rebuild
dotnet clean
dotnet restore
dotnet build

# Check for package conflicts
dotnet list package --outdated

Validation Checklist

Pre-Development Validation

• [ ] ABP CLI installed and updated
• [ ] Correct template selected for requirements
• [ ] Project created successfully
• [ ] Solution builds without errors
• [ ] Database connection configured
• [ ] Initial migrations applied
• [ ] Application starts successfully

Development Readiness

• [ ] Default login page accessible
• [ ] User registration working
• [ ] Basic CRUD operations functional
• [ ] API endpoints responding
• [ ] Test projects compile
• [ ] Localization working
• [ ] Theme applied correctly

Best Practices

Template Selection

• Choose the simplest template that meets requirements
• Consider future growth and scalability
• Factor in team expertise and experience
• Plan for multi-tenancy if needed

Configuration Management

• Use environment-specific configuration files
• Store sensitive data in user secrets
• Leverage ABP's setting system
• Implement proper logging

Development Workflow

• Use ABP CLI for all project operations
• Follow ABP conventions and patterns
• Implement proper unit tests
• Use version control from the start

Performance Optimization

• Choose appropriate database provider
• Implement proper caching strategies
• Use async operations consistently
• Monitor application performance

This skill provides comprehensive guidance for creating ABP.IO projects using the CLI with the right template and configuration for your specific needs.