AbpDevTools

KO | EN

gitlite — search

#python #golang #go #selenium #nodejs #typescript #cpp #ios #docker #hacktoberfest #vue #map

★ 54 Open GitHub ↗

A set of tools to make development with ABP easier.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# AbpDevTools
A set of tools to make development with ABP easier. It's a dotnet tool and accessed via `abpdev` **CLI** command.

It helps the developer, build, run, replace, and manage logs of the projects. It makes running **multiple** solutions and projects easier.

> Done with [Enisn.Templates.CLI](https://github.com/enisn/Enisn.Templates.CLI). You can build similar CLI tools with this template.

<a href="https://enisn.github.io/AbpDevTools/"><img src="https://img.shields.io/badge/Documentation-available-blue" alt="Documentation" /></a>
# Documentation
Read the [full documentation](https://enisn.github.io/AbpDevTools/)
# Installation

- Install [AbpDevTools from NuGet](https://www.nuget.org/packages/AbpDevTools) as dotnet tool:
```bash
dotnet tool update -g AbpDevTools
```

- Installation for a specific runtime other than the latest:
    
    ```bash
    dotnet tool update -g AbpDevTools --framework net8.0
    # or
    dotnet tool update -g AbpDevTools --framework net6.0
    ```

> This package is compiled for .NET 6.0, 7.0, 8.0 and 9.0. So you can install it for a specific runtime. If you don't specify a runtime, it'll install the latest version.

## Local Installation
If you don't have access to the package source. You can install it from the source code by the following code:

```bash
pwsh install.ps1
```

# Getting Started
  You can watch the **'Getting Started'** video for onboarding this tool:
  
  <a href="https://youtu.be/wG7MfdIq_Fo"> <img src="https://github.com/enisn/AbpDevTools/assets/23705418/b31a37a0-96c7-418c-8287-80922c178b3c"/> </a>

# Usage

Execute `abpdev` command in the terminal and it'll show you the help message.

```bash
abpdev --help
```

# Commands
The following commands are available:

## abpdev build
Builds all solutions/projects in the current directory recursively. _(Multiple solutions)_

```
abpdev build <workingdirectory> [options]
```

```bash
abpdev build -h

PARAMETERS
  workingdirectory  Working directory to run build. Probably project or solution directory path goes here. Default: . (Current Directory) 
OPTIONS
  -f|--build-files  (Array) Names or part of names of projects or solutions will be built.
  -i|--interactive  Interactive build file selection. Default: "False".
  -c|--configuration
  -h|--help         Shows help text.
```

Convention: `*.sln` files are considered as solutions and `*.csproj` files are considered as projects.

![abpdev build](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevbuild.gif)

### Example commands

- Run in a specific path
    ```bash
    abpdev build C:\Path\To\Projects
    ```

- Run in a specific configuration
    ```bash
    abpdev build C:\Path\To\Projects -c Release
    ```

- Run in a specific path with specific configuration and specific projects
    ```bash
    abpdev build C:\Path\To\Projects -c Release -f ProjectA.csproj ProjectB.csproj
    ```

- Run in interactive mode **(Select projects to build)**
    ```bash
    abpdev build -i
    ```
    ![abpdev build interactive](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevbuild-interactive.gif)

## abpdev add-package

Adds a NuGet package to the project and automatically configures the module dependency. This command is designed to work with **any NuGet source**, unlike the official `abp add-package` command which only works with the official ABP package registry.

### The Problem with `abp add-package`

ABP's official CLI has a strict policy that only allows adding packages from their official registry. If you try to add a third-party package or a package from a custom NuGet source, you'll get an error:

```
PS C:\P\AbpSolution3025> abp add-package AbpDev.QoL.Mvc.DataTables
🔒 'AbpDev.QoL.Mvc.DataTables' nuget package could not be found!
```

This is because `abp add-package` queries the ABP's internal package database instead of directly using the NuGet API. Any package not registered in their database will fail, even if it exists on NuGet.

### The Solution: AbpDevTools `add-package`

AbpDevTools takes a **developer-friendly approach**:

- **NuGet source agnostic**: Uses `dotnet add package` which respects all configured sources in `nuget.config`
- **Auto-configures DependsOn**: Automatically finds and adds the `[DependsOn(typeof(ModuleName))]` attribute to your module
- **No assembly loading**: Uses metadata reflection to read module classes from DLLs without loading them into runtime (avoids target framework conflicts)
- **Multi-project support**: Prompts to select from multiple projects or adds to all projects at once

```
abpdev add-package <packagename> [options]
```

```bash
abpdev add-package -h

PARAMETERS
* packagename       Name of the NuGet package to add.

OPTIONS
  -p|--project        Path to the project file (.csproj). Default: searches current directory. 
  -v|--version        Version of the package to install. 
  --prerelease      Allow installing prerelease package versions. Default: "False".
  -s|--skip-dependency  Skip adding module dependency (DependsOn attribute). Default: "False".
  --no-restore        Skip restoring the project after adding the package. Default: "False".
  -a|--all          Add package to all projects in the solution/folder. Default: "False".
  -h|--help         Shows help text.
```

### Example commands

- Add a package to the current project
    ```bash
    abpdev add-package AbpDev.QoL.Mvc.DataTables
    ```

- Add a specific version
    ```bash
    abpdev add-package AbpDev.QoL.Mvc.DataTables -v 1.0.0
    ```

- Add latest prerelease version
    ```bash
    abpdev add-package AbpDev.QoL.Mvc.DataTables --prerelease
    ```

- Add to all projects in the solution
    ```bash
    abpdev add-package AbpDev.QoL.Mvc.DataTables -a
    ```

- Add to a specific project
    ```bash
    abpdev add-package AbpDev.QoL.Mvc.DataTables -p C:\Path\To\Project.csproj
    ```

- Skip adding the DependsOn attribute (if not an ABP module)
    ```bash
    abpdev add-package Some.Other.Package -s
    ```

### How It Works

1. **Add Package**: Uses `dotnet add package` which respects your `nuget.config` sources
2. **Restore**: Restores packages to download the DLL to NuGet cache
3. **Find Module**: Uses metadata reflection to find the module class in the package DLL (without loading the assembly)
4. **Find Project Module**: Uses Roslyn to parse your project's source files to find the ABP module class
5. **Configure Dependency**: Adds `[DependsOn(typeof(ModuleName))]` attribute to your module

> **Note**: This command is safe to run multiple times - it won't add duplicate dependencies.

## abpdev run
Runs the solution in the current directory. _(Multiple solution, multiple applications including DbMigrator)_

```
abpdev run <workingdirectory> [options]
```

```bash
PARAMETERS
  workingdirectory  Working directory to run build. Probably project or solution directory path goes here. Default: . (Current Directory)

OPTIONS
  -w|--watch        Watch mode Default: "False".
  --skip-migrate    Skips migration and runs projects directly. Default: "False".
  -a|--all          Projects to run will not be asked as prompt. All of them will run. Default: "False".
  --no-build        Skipts build before running. Passes '--no-build' parameter to dotnet run. Default: "False".
  -i|--install-libs  Runs 'abp install-libs' command while running the project simultaneously. Default: "False".
  -g|--graphBuild   Uses /graphBuild while running the applications. So no need building before running. But it may cause some performance. Default: "False".
  -p|--projects     (Array) Names or part of names of projects will be ran.
  --msbuild-property MSBuild property passed to every selected dotnet run process. Use Name=Value and repeat for multiple properties.
  -c|--configuration
  -e| --env        Virtual Environment name. You can manage virtual environments by using 'abpdev env config'
  -h|--help         Shows help text.
```

Convention: `*.csproj` files with `Program.cs` are considered runnable .NET applications or dbmigrators. `package.json` files are considered runnable npm applications when they define a `dev`, `serve`, or known web-server `start` script such as `ng serve`, `vite`, `react-scripts start`, or `vue-cli-service serve`.

Unknown `start` scripts are shown during interactive selection but are skipped by `--all` unless they are explicitly selected with `--projects` or configured in `abpdev.yml`:

```yaml
run:
  npm:
    scripts:
      - web
      - start
```

> _Use `abpdev run config` command to change project name conventions according to your requirements_

![abpdev run](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevrun.gif)

### Example commands

- Run multiple solutions
    ```bash
    abpdev run C:\Path\To\Top\Folder\Of\Solutions
    ```
    ![abpdev run multiple solutions](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevrun-multiplesolutions.gif)

- Run in a specific path
    ```bash
    abpdev run C:\Path\To\Projects
    ```

- Run in a specific configuration and specific path
    ```bash
    abpdev run C:\Path\To\Projects -c Release
    ```

- Run all projects instead prompt selection
    ```bash
    abpdev run -a
    ```

![abpdev run all](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevrun-all.gif)

- Skip migration and run projects directly
    ```bash
    abpdev run --skip-migrate
    ```

- Run in watch mode
    ```bash
    abpdev run -w
    ```
    > Please note that we cannot print URL's because dotnet does give any output.

## Virtual Environments
Virtual environments are used to run multiple solutions with different configurations. For example, you can run different solutions with different environments _(connectionstrings etc.)_.

You can manage virtual environments by using `abpdev env config` command and use those pre-configured environments with other commands like: `abpdev run -e SqlServer`. This command will use the environment named SqlServer. You can set different connectionstrings for each environment.

```bash
abpdev env config
```

> You'll see the following screen. You can add, edit, delete, and select virtual environments.
> ```json
> {
>  "SqlServer": {
>    "Variables": {
>      "ConnectionStrings__Default": "Server=localhost;Database={AppName}_{Today};User ID=SA;Password=12345678Aa;TrustServerCertificate=True"
>    }
>  },
>  "MongoDB": {
>    "Variables": {
>      "ConnectionStrings__Default": "mongodb://localhost:27017/{AppName}_{Today}"
>    }
>  }
>}
> ```
> **{Today}** will be replaced with the current date. So you can run multiple solutions with different databases.
> **{AppName}** will be replaced with the application name. So you can run multiple solutions with different databases. _When app name couldn't be detected, folder name will be used.

### Example commands

- Run in a specific virtual environment
    ```bash
    abpdev run -e SqlServer
    ```

## abpdev prepare
Prepares the project for the first running on this machine. Automatically detects project dependencies, starts required environment apps (databases, message brokers), installs ABP libraries, and creates local configuration files. You can use the `abpdev.yml` configuration file to run the project with different environments without changing the `appsettings.json` files. You can modify the created `abpdev.yml` file to change or add new environment variables to run profile.

```
abpdev prepare <workingdirectory> [options]
```

```bash
abpdev prepare -h

PARAMETERS
  workingdirectory  Working directory to run build. Probably project or solution directory path goes here. Default: . (Current Directory)

OPTIONS
  --no-config       Do not create local configuration file. (abpdev.yml) Default: "False".
  -h|--help         Shows help text.
```

Convention: The command analyzes project dependencies to determine which environment apps are needed (SQL Server, MongoDB, Redis, etc.) and automatically configures the environment accordingly.

![abpdev prepare](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevprepare.gif)

### Example commands

- Prepare project in current directory
    ```bash
    abpdev prepare
    ```

- Prepare project in a specific path
    ```bash
    abpdev prepare C:\Path\To\Projects
    ```

- Prepare without creating local configuration files
    ```bash
    abpdev prepare --no-config
    ```

This command performs the following operations:
- **Dependency Analysis**: Scans projects for database and messaging dependencies
- **Environment Apps**: Starts required Docker containers (SQL Server, MongoDB, Redis, etc.)
- **Library Installation**: Runs `abp install-libs` to install client-side libraries
- **Blazor Bundling**: Bundles Blazor WASM projects
- **Configuration**: Creates `abpdev.yml` files with appropriate environment settings

## abpdev logs
Finds a project under the current directory and prints the last log lines to the terminal by default. Use `--open` to keep the old file/folder opening behavior.

![abpdev logs](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevlogs.gif)
---
![abpdev logs clear](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevlogs-clear.gif)

```bash
  abpdev logs <projectname> [options]
  abpdev logs [command] [...]

PARAMETERS
  projectname       Determines the project to show logs of.

OPTIONS
  -p|--path         Working directory of the command. Probably solution directory. Default: . (CurrentDirectory)
  -i|--interactive  Options will be asked as prompt when this option used. Default: "False".
  -n|--lines        Number of lines to print from the end of logs.txt. Default: 100.
  -o|--open         Opens logs with the operating system default app instead of printing them.
  -h|--help         Shows help text.

COMMANDS
  clear
```

### Example commands

- Show the last 100 log lines of the **.Web** project
    ```bash
    abpdev logs Web
    ```

- Show the last 20 log lines
    ```bash
    abpdev logs Web -n 20
    ```

- Open the log file or folder with the operating system default app
    ```bash
    abpdev logs Web --open
    ```

- Clear logs of the **.Web** project
    ```bash
    abpdev logs clear -p Web
    ```

- Clear logs without approval
    ```bash
    abpdev logs clear -p Web -f
    ```

## abpdev replace
Replaces specified text in files under the current directory recursively. Mostly used to replace connection strings in `appsettings.json` files. But it can be used for any other purposes.

```bash
USAGE
  abpdev replace <replacementconfigname> [options]
  abpdev replace [command] [...]

DESCRIPTION
  Runs file replacement according to configuration.

PARAMETERS
  replacementconfigname  If you execute single option from config, you can pass the name or pass 'all' to execute all of them

OPTIONS
  -p|--path         Working directory of the command. Probably solution directory. Default: . (CurrentDirectory)
  -i|--interactive  Interactive Mode. It'll ask prompt to pick one config. Default: "False".
  -h|--help         Shows help text.

COMMANDS
  config            Allows managing replacement configuration. Subcommands: config clear.
```

![abpdev replace](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevreplace.gif)

> Use `abpdev replace config` command to change file name conventions according to your requirements.
> _You'll see something like that by default:
> ```json 
> {
>   "ConnectionStrings": {
>     "FilePattern": "appsettings.json",
>     "Find": "Trusted_Connection=True;",
>     "Replace": "User ID=SA;Password=12345678Aa;"
>   }
> }
> ```

### Example commands

- Replace connection strings in `appsettings.json` files
    ```bash
    abpdev replace ConnectionStrings
    ```

- Run all the configurations at once
    ```bash
    abpdev replace all
    ```

## Local Source Management
You can configure and manage local source mappings to easily switch between package references and local project references during development. This is especially useful when working with local forks or development versions of external packages.

### Configure Local Sources
```bash
abpdev local-sources
```

or shortcut command for grouping all the 'references' commands:

```bash
abpdev references config
```

This command opens a YAML configuration file where you can define your local source mappings:

```yaml
abp:
  RemotePath: https://github.com/abpframework/abp.git
  Path: C:\github\abp
  Packages:
    - Volo.Abp.*
    - Volo.Abp.Core
other-lib:
  Path: C:\source\other-lib
  Packages:
    - MyOrg.OtherLib.*
```

**Configuration Properties:**
- **RemotePath**: The remote repository URL _(optional)_, for cloning if not exists)
- **Path**: Local path where the source code is located. It'll be used to find the project files. Descendants of this path will be scanned for project files.
- **Packages**: List of package patterns to match (supports wildcards with `*`)

> **Important**: The order of sources in the configuration file matters. When switching references, the first matching source will be used for a package. It only matters if the same package exists in different sources. Otherwise, don't worry about it.

## Reference Management
Manage project and package references efficiently with local source switching capabilities.

### Switch to Local References
Converts package references to local project references for development:

```bash
abpdev references to-local [workingdirectory] [options]
```

```bash
abpdev references to-local -h

PARAMETERS
  workingdirectory  Working directory to run build. Probably project or solution directory path goes here. Default: . (Current Directory)

OPTIONS
  -s|--sources      (Array) Sources to switch to local. Default: all sources.
  -h|--help         Shows help text.
```

This command:
- Finds all `.csproj` files in the working directory.
- Matches package references against configured [local source](#local-source-management) patterns
- Converts matching packages to project references with **relative paths**
- **Backs up** original package versions in PropertyGroup for later restoration

### Switch to Package References
Converts local project references back to package references:

```bash
abpdev references to-package [workingdirectory] [options]
```

```bash
abpdev references to-package -h

PARAMETERS
  workingdirectory  Working directory to run build. Probably project or solution directory path goes here. Default: . (Current Directory)

OPTIONS
  -s|--sources      (Array) Sources to switch to package. Default: all sources.
  -h|--help         Shows help text.
```

This command:
- Finds all `.csproj` files in the working directory
- Identifies project references pointing to configured local sources
- Converts them back to package references using backed-up versions
- Prompts for version input if no backed-up version exists

### Example commands

- Configure local sources
    ```bash
    abpdev references config
    ```

- Switch all package references to local development versions
    ```bash
    abpdev references to-local
    ```

- Switch specific sources to local
    ```bash
    abpdev references to-local --sources abp
    ```

- Switch back to package references
    ```bash
    abpdev references to-package
    ```

- Switch specific sources back to packages
    ```bash
    abpdev references to-package --sources abp other-lib
    ```

- Work in specific directory
    ```bash
    abpdev references to-local C:\Path\To\Projects --sources abp
    ```

## Enable Notifications
You can enable notifications to get notified when a build or run process is completed. You can enable it by using `abpdev enable-notifications` command and disable it by using `abpdev disable-notifications` command.

> _It only works on **Windows** and **MacOS**. Linux is not supported yet._

```bash
abpdev enable-notifications
abpdev disable-notifications
```

It'll send a notification when a **migration**, **build** or **run** process is completed.

![abpdev notifications](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevnotification.gif)

## Environment Apps
You can easily run commonly used environment apps like **SQL Server**, **PostgreSQL**, **Redis**, **MySQL**, **MongoDB** and **RabbitMQ** by using `abpdev envapp start` command.

```bash
abpdev envapp [command] <appname> [options]

abpdev envapp start <appname> [options]
abpdev envapp stop <appname> [options]
```

> You can change the default running commands by using `abpdev envapp config` command.

![abpdev envapp](https://raw.githubusercontent.com/enisn/AbpDevTools/master/images/abpdevenvapp.gif)

Available app names by **default**:
```bash
 - sqlserver
 - sqlserver-edge
 - postgresql
 - mysql
 - mongodb
 - redis
 - rabbitmq
```

_You can extend the list or change environments of apps by using `abpdev envapp config` command._

### Example commands

- Start SQL Server with custom SA password
    ```bash
    abpdev envapp start sqlserver -p myPassw0rd
    ```

## Switch ABP Studio Version
Switches the locally installed **ABP Studio** to any published version/channel, ensuring directories exist, caching packages for reuse, and invoking the platform-specific updater with live log streaming and desktop notifications.

```bash
abpdev abp-studio switch <version> [options]
```

```bash
PARAMETERS
  version            Target ABP Studio version to install. Default: 1.0.0

OPTIONS
  -c|--channel       Channel to download from. Default: "stable".
  -f|--force         Forces re-download even if the package already exists.
  -i|--install-dir   Custom install directory. Default: %LOCALAPPDATA%\abp-studio (Windows) or OS equivalent.
  -p|--packages-dir  Custom cache directory for downloaded packages.
  -h|--help          Shows help text.
```

The command:

- Detects your OS/CPU (Windows x64/ARM, macOS Intel/ARM, Linux) to pick the right package suffix.
- Creates/uses the requested install and packages directories _(defaults to `%LOCALAPPDATA%\abp-studio` on Windows, `/Applications` or `~/Applications` on macOS)_.
- Streams download progress while fetching `abp-studio-{version}-{channel}-full.nupkg`; `--force` wipes existing packages first.
- Verifies that the platform updater (`Update.exe` on Windows or `UpdateMac` on macOS) exists before applying `apply --package <path>`.
- Applies the downloaded package to the installed ABP Studio by using official updater.

> ⚠️ This command doesn't add any custom DLL or executable files to your system. It only applies **official** ABP Studio nuget packages to the existing installation.

Using a shared packages directory (for example on a fast SSD or network drive) makes switching between versions nearly instant because only the apply step needs to run.

### When to use?

- You're working on a project that requires a specific version of ABP Studio.
- You need to create a new project with a specific version of ABP Studio.
- You have a critical bug in a specific version of ABP Studio and you need to **rollback** to a previous version.

> ❌ Don't use this command to install ABP Studio for the first time. Use the official installer instead. This command is only for switching between versions by applying nuget package updates.

### Example commands

- Switch to a specific stable version (default paths)
    ```bash
    abpdev abp-studio switch 2.0.1
    ```

- Download and apply a beta channel release and reuse cached packages across machines
    ```bash
    abpdev abp-studio switch 1.1.0 -c beta -p D:\abp-studio-cache
    ```

- Redownload and install a version even if it is already downloaded
    ```bash
    abpdev abp-studio switch 0.9.0 -f
    ```

AbpDevTools

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README