Create App API Project

Project Overview & Use Cases

ZhonTai.Template.App template is used to quickly create .NET-based backend API projects, supporting both multi-module distributed architecture and monolithic application development modes. With this template, you can generate a well-structured, properly configured server-side project in one click, with built-in capabilities such as authentication, permission control, data filtering, and remote calls (gRPC/HTTP).

Projects created from the template reference the platform's maintained NuGet packages for core framework features (permissions, logging, data filtering, remote calls, etc.), rather than embedding source code directly. When the platform releases new features or fixes, you simply update the corresponding NuGet package version in your project to get the latest capabilities — no need to regenerate the project or manually merge code. Truly "create once, continuously upgrade."

The template provides three project types to match different responsibility boundaries:

Type	Role	When to Use
Platform sys	System core and permission management center	When you need unified management of users, roles, permissions, and logs — create first as the foundation of the entire system
Business app	Modules focused on specific business logic	When business is complex and needs to be split into multiple independent services (e.g., orders, products, CMS), relying on the platform's permissions and user data
User mem	APIs for end users/members	When developing mobile apps, web frontends, or other consumer-facing applications that need login and data isolation but not backend permission management

Core Use Case Examples

• Distributed Microservices: The platform provides unified gRPC services; business and user projects remotely fetch user, permission, and log information via gRPC, each connecting to independent databases, enabling team parallel development and independent deployment.
• Monolithic Agile Development: Merge the permission database into the business database (--merge-db) and complete all functionality in a single project — ideal for rapid delivery of small to medium projects.
• Member Portal Quick Setup: User projects skip complex functional permissions and only retain login and data permissions — ideal for building lightweight user centers or mini-program APIs.

Below, starting from installing the template, we'll detail the creation methods and best practices for each project type.

Install or Upgrade Template

dotnet new install ZhonTai.Template.App

The upgrade template command is the same as the install template command.

Note

If ZhonTai.Template template is already installed, you need to uninstall the old ZhonTai.Template template first before installing the new ZhonTai.Template.App template to avoid short name MyApp conflicts.

dotnet new uninstall ZhonTai.Template

Install Specific Version

dotnet new install ZhonTai.Template.App::10.0.5

View Help

dotnet new MyApp -h

[Template Options]

-at, --app-type <app|mem|sys>
  Select different categories based on project requirements
  Type: choice
    sys  Includes Admin permission management APIs. Suitable for system extension or monolithic project development. Has login, data permissions, and function permission restrictions.
    app  Does not include Admin permission management APIs. Requires gRPC and HTTP remote communication. Suitable for business module project development. Has login, data permissions, and function permission restrictions.
    mem  Does not include Admin permission management APIs. Suitable for user-side or member-side development. Does not depend on Admin APIs. Requires gRPC and HTTP remote communication.
         Has login and data permission restrictions. No function permission restrictions.
  Default: app
-ac, --app-code <app-code>
  Optional. If not set, defaults to the app-type project category option.
  Used to uniquely identify different functional modules in the project for management and differentiation, such as sys | biz | mem.
  Type: string
-p, --port <port>
  Set the port number the API project listens on at startup, such as 18010 | 18020 | 18030.
  Required: true
  Type: int
-gp, --grpc-port <grpc-port>
  Configure the port number for gRPC remote communication. It is recommended to set it to the HTTP port + 1, such as 18011 | 18021 | 18031.
  Required: true
  Type: int
-sk, --security-key <security-key>
  Optional. If not set, a Guid is auto-generated.
  Sets the value of jwtconfig.securityKey for JWT token security verification to ensure API call security.
  Enabled when: AppType == sys
  Type: string
-db, --db-type <MySql|PostgreSQL|...>
  Select the appropriate database type based on project requirements. Supports mainstream domestic and international databases.
  Type: choice
    MySql       MySql
    PostgreSQL  PostgreSQL
    SqlServer   SqlServer
    Oracle      Oracle
    Sqlite      Sqlite
    Firebird    Firebird
    MsAccess    MsAccess
    Dameng      Dameng database, providing stable and reliable data storage and query services.
    ShenTong    ShenTong database, featuring high performance and scalability for complex business needs.
    KingbaseES  KingbaseES database, providing comprehensive data management and security protection.
    Gbase       GBase database, supporting large-scale data processing and analysis.
    ClickHouse  ClickHouse
    QuestDb     QuestDb
    Xugu        Xugu database, providing flexible data storage and efficient query performance.
  Default: Sqlite
-nau, --no-apiui
  Select this option to disable the new API documentation feature, reducing unnecessary resource usage.
  Type: bool
  Default: false
-nts, --no-task-scheduler
  Select this option to not integrate the task scheduling service. Suitable for projects that don't need scheduled tasks.
  Type: bool
  Default: false
-nc, --no-cap
  Select this option to not use CAP distributed transactions and event bus features, reducing system complexity.
  Type: bool
  Default: false
-nt, --no-tests
  Select this option to not generate test projects. Suitable for projects that don't need automated testing.
  Type: bool
  Default: false
-ns, --no-sample
  Select this option to not generate default sample modules and related files. Suitable for developers familiar with the development workflow who want to quickly start development.
  Type: bool
  Default: false
-md, --merge-db
  Select this option to merge the admindb database into appdb for unified database resource management and maintenance. Suitable for monolithic project development.
  Type: bool
  Default: false

View Installed Templates

dotnet new list

Uninstall Template

dotnet new uninstall ZhonTai.Template.App

Create Platform Project

Why do you need a Platform project?
The platform is the "brain" of the entire system, responsible for unified management of backend fundamentals such as users, roles, menus, permissions, and operation logs. It exposes gRPC services for business and user projects to remotely verify permissions and fetch user information. Any system that requires backend permission management should create a platform project first.

When to use?

• Starting a brand new system — create the platform first as the permission foundation.
• Developing multi-module distributed applications — the platform is independently deployed, and other modules depend on it via gRPC.
• When you need to provide operations staff with a fully functional admin management interface (Admin).

The project APIs include platform APIs and Admin permission management APIs. dbconfig needs to configure sysdb (business primary database), admindb (permission database), logdb (log database), providing data permissions, user permissions, and operation log gRPC service interfaces.

• Set project code and port number

Platform Project

dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011

Monolithic Project

dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -p 16010 -gp 16011

• Switch database to MySql

Platform Project

dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -db MySql

Monolithic Project

dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 16010 -gp 16011 -db MySql

• Merge the permission database admindb into the business database appdb, and switch database to MySql

Platform Project

dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -md true -db MySql

Monolithic Project

dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 16010 -gp 16011 -md true -db MySql

• For multi-module development, if you are familiar with development and don't need sample modules or test projects:

Platform Project

dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 18010 -gp 18011 -nt true -ns true -db MySql

Monolithic Project

dotnet new MyApp -n MyCompanyName.Module.MySys -at sys -ac sys -p 16010 -gp 16011 -nt true -ns true -db MySql

Note

Platform project default port range: 18010 - 18999, Monolithic project default port range: 16010 - 16999

gRPC port default range: port + 1

Create Business Project

Why do you need a Business project?
As system features grow more complex, piling all code into the platform becomes hard to maintain. A business project lets you extract specific business modules (such as orders, products, reports) into independent services. It doesn't include an Admin management interface, but reuses the platform's login, permissions, and user data via gRPC — maintaining data isolation while enabling secure collaboration.

When to use?

• The platform is ready and you need to extend new business feature modules (e.g., splitting out an "e-commerce business service" from the platform).
• Team parallel development: multiple business services can be developed simultaneously without interfering with each other.
• When you need independent deployment and per-business scaling (e.g., the order service can be scaled independently under high load).

Below we'll start creating a business project

dotnet new MyApp -n MyCompanyName.Module.MyBiz -at app -ac biz -p 19010 -gp 19011

• Switch database to MySql

dotnet new MyApp -n MyCompanyName.Module.MyBiz -at app -ac biz -p 19010 -gp 19011 -db MySql

• For multi-module development, if you are familiar with development and don't need sample modules or test projects:

dotnet new MyApp -n MyCompanyName.Module.MyBiz -at app -ac biz -p 19010 -gp 19011 -nt true -ns true -db MySql

Note

Business project default port range: 19010 - 19999

gRPC port default range: port + 1

Create User Project

Why do you need a User project?
Consumer-facing applications such as mobile apps, WeChat mini-programs, and websites only need user registration/login and personal data management — not complex backend role and menu permission control. User projects remove functional permission restrictions, focusing on "user authentication + data permissions (users can only operate their own data)," providing lightweight and secure external APIs.

When to use?

• Building member centers, mini-program APIs, or mobile APIs for end consumers.
• When you need an independent user service, physically isolated from the backend admin system for security.
• Working with the platform and business projects to provide users with login, profile updates, order queries, and other frontend APIs.

Below we'll start creating a user project

dotnet new MyApp -n MyCompanyName.Module.MyMem -at mem -ac mem -p 20010 -gp 20011

• Switch database to MySql

dotnet new MyApp -n MyCompanyName.Module.MyMem -at mem -ac mem -p 20010 -gp 20011 -db MySql

• For multi-module development, if you are familiar with development and don't need sample modules or test projects:

dotnet new MyApp -n MyCompanyName.Module.MyMem -at mem -ac mem -p 20010 -gp 20011 -nt true -ns true -db MySql

Note

Member project default port range: 20010 - 20999

gRPC port default range: port + 1

Note

When using the source code project, remember to change the securityKey in the ZhonTai.Admin.Host/ConfigCenter/jwtconfig.json configuration file.

{
  "JwtConfig": {
    // Security key, note: string length must not be less than 32 characters
    "securityKey": "33ce0d4b3a7b11ef8563526747b33ad4",
  }
}