Utility Commands

Manage database migrations, package updates, and project maintenance.

peardrop migrate

Run database migrations for all modules in dependency order.

# Migrate all modules
peardrop migrate

# Migrate with seed data
peardrop migrate --seed

# Migrate specific module
peardrop migrate --module Authentication

# Dry run (show what would be migrated)
peardrop migrate --dry-run

What It Does:

1. Discovers all DbContexts in your application automatically
2. Determines migration order based on module dependencies
3. Runs migrations using connection strings from appsettings.json
4. Optionally seeds data with --seed flag

Migration Order:

run: dotnet tool run peardrop update --dry-run

1. Core module (your app's main DbContext)
2. PearDrop.Authentication (if present)
3. PearDrop.Multitenancy (if present)
4. PearDrop.Files (if present)
5. PearDrop.Messaging (if present)
6. Custom modules

### Options

| Option | Description | Example |
|--------|-------------|---------|
| `--seed` | Run data seeders after migrations | `peardrop migrate --seed` |
| `--module` | Migrate only specific module | `--module Authentication` |
| `--dry-run` | Show migration plan without executing | `--dry-run` |

### Connection String Resolution

The CLI resolves connection strings in this order:

1. **Module-specific:** `ConnectionStrings:{ModuleName}` (e.g., `PearDrop-Auth`)
2. **Default:** `ConnectionStrings:PearDrop`
3. **Fallback:** `PearDrop:modules:core:PrimaryConnectionString` (deprecated)

**Example appsettings.json:**
```json
{
  "ConnectionStrings": {
    "PearDrop": "Server=localhost,1440;Database=MyApp;User Id=sa;Password=...;",
    "PearDrop-Auth": "Server=localhost,1440;Database=MyApp;...",
    "PearDrop-Files": "Server=files-db,1440;Database=Files;..."
  }
}

Use Cases

Local Development:

# After adding new aggregate or entity
dotnet ef migrations add CreateEquipment
peardrop migrate

Initial Setup:

# After cloning repository
docker-compose up -d
peardrop migrate --seed
dotnet run

Deployment (CI/CD):

# Azure DevOps pipeline
- task: DotNetCoreCLI@2
  displayName: 'Run Migrations'
  inputs:
    command: 'custom'
    custom: 'tool'
    arguments: 'run peardrop migrate'

Troubleshooting Migrations:

# See what would run without executing
peardrop migrate --dry-run

# Run specific module only
peardrop migrate --module Authentication

peardrop update

Update PearDrop framework packages to latest or specific version.

# Update all PearDrop packages to latest
peardrop update

# Update to specific version
peardrop update --version 2.1.0

# Preview what would change without applying it
peardrop update --dry-run

# Include preview versions
peardrop update --preview

# Skip refreshing docs/templates during update
peardrop update --skip-docs

What It Does:

1. Scans project files for PearDrop package references
2. Updates the CLI tool first when a specific target version is requested
3. Resolves feed information from environment or NuGet config when needed
4. Updates package versions in .csproj files
5. Refreshes project docs and guides unless --skip-docs is specified
6. Restores packages with dotnet restore

Updated Packages:

PearDrop.Client
PearDrop.Client.Commands
PearDrop.Server
PearDrop.Authentication
PearDrop.Multitenancy
PearDrop.Files
PearDrop.Messaging
... all PearDrop.* packages

Options

Option	Description	Example
--version	Update to specific version	--version 2.1.0
--dry-run	Preview updates without applying them	--dry-run
--preview	Include preview/prerelease versions	--preview
--skip-docs	Skip refreshing docs and guides	--skip-docs

Use Cases

Regular Maintenance:

# Preview changes monthly
peardrop update --dry-run

# Update if acceptable
peardrop update

Pinned Version Deployment:

# Production: use specific tested version
peardrop update --version 2.0.5

Beta Testing:

# Try latest prerelease
peardrop update --preview

Update Without Refreshing Docs:

# Keep local docs untouched during package update
peardrop update --skip-docs --version 2.1.0

Version Compatibility

When you pass --version, the CLI updates the PearDrop CLI tool first so the tool and project packages stay aligned. It also attempts to resolve the NuGet feed from PEARDROP_NUGET_FEED, .peardrop/nuget.config, nuget.config, or the user NuGet config.

The CLI still warns when major version changes may introduce breaking changes:

⚠️ Warning: PearDrop 3.0.0 contains breaking changes:
   - Removed deprecated PrimaryConnectionString configuration
   - Updated to .NET 9
   
   Review CHANGELOG.md before updating.
   
Continue? [y/N]:

peardrop info

Display project information and configuration.

peardrop info

Example Output:

PearDrop Project Information
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project
  Name:           MyApp
  Root:           C:\Projects\MyApp
  Framework:      .NET 10.0
  Template:       peardrop-local-auth

Framework
  Version:        2.0.5
  Modules:        Authentication, Files

Database
  Default:        Server=localhost,1440;Database=MyApp
  Auth:           Server=localhost,1440;Database=MyApp
  Files:          Server=files-db,1440;Database=Files

Features
  Authentication: Enabled (Internal + Entra ID)
  Multi-tenancy:  Disabled
  File Storage:   Enabled (Azure Blob)

Migrations
  Pending:        3 migrations not applied
  ├─ Core:        CreateEquipmentTables
  ├─ Auth:        AddExternalProviders
  └─ Files:       AddFileVersioning

External Providers
  Entra ID:       2 configured (1 enabled)

Run 'peardrop migrate' to apply pending migrations.

Use Cases

Quick Status Check:

# What's configured in this project?
peardrop info

Debugging Configuration:

# Check connection strings and module setup
peardrop info

# Verify framework version
peardrop info | grep "Framework Version"

CI/CD Health Check:

# Verify environment before deployment
- task: DotNetCoreCLI@2
  displayName: 'Check Project Info'
  inputs:
    command: 'custom'
    custom: 'tool'
    arguments: 'run peardrop info'

peardrop extract-context

Extract a bounded context into a separate module (experimental).

# Interactive mode
peardrop extract-context

# Specify context to extract
peardrop extract-context --context Equipment \
  --target-project ../EquipmentManagement

What It Does:

1. Analyzes aggregates in your domain
2. Identifies bounded context by aggregate relationships
3. Creates new module project structure
4. Moves domain files to new module
5. Updates references in original project
6. Creates migration for new module
7. Updates manifest - Adds extracted module to projects[] and usedModules in peardrop.json

⚠️ Experimental Feature:

This command is currently experimental. Always:

• Commit changes before running
• Review extracted code carefully
• Test thoroughly after extraction

Options

Option	Description
--context	Context name to extract
--target-project	Destination project path
--dry-run	Show extraction plan

Use Cases

Growing Application:

# Started with one module, now need separation
peardrop extract-context --context Equipment \
  --target-project ../EquipmentModule

Microservices Migration:

# Extract context to separate deployable service
peardrop extract-context --context Orders \
  --target-project ../OrderService

What Gets Extracted

Original Project:
  Infrastructure/Domain/EquipmentAggregate/  ─→  New Module:
  Infrastructure/Domain/CheckoutAggregate/       PearDrop.EquipmentManagement/
                                                   Infrastructure/Domain/EquipmentAggregate/
                                                   Infrastructure/Domain/CheckoutAggregate/

Also Moves:

• Commands and handlers
• Queries and handlers
• Projections and read models
• Domain events
• Integration events
• Entity configurations

peardrop cleanup

Remove temporary files and backups.

# Remove all temporary files
peardrop cleanup

# Dry run (see what would be removed)
peardrop cleanup --dry-run

# Remove specific file types
peardrop cleanup --backups-only

What It Removes:

• .pbak files - Backup files created during CLI operations
• Temporary migrations - Failed or rolled-back migrations
• Build artifacts - bin/, obj/ in CLI temp directories

Safe by Design:

• Never removes source code files
• Never removes user migrations
• Never removes configuration files
• Creates confirmation prompt before deletion

Options

Option	Description
--dry-run	Show what would be removed
--backups-only	Remove only .pbak files
--force	Skip confirmation prompt

Use Cases

After Bulk Changes:

# Made lots of CLI changes, now clean up
peardrop cleanup

Pre-Commit Cleanup:

# Clean temp files before committing
peardrop cleanup --dry-run
peardrop cleanup
git status

Disk Space Recovery:

# Remove old backups
peardrop cleanup --backups-only

CI/CD Integration Examples

Azure DevOps Pipeline

trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
  - task: UseDotNet@2
    inputs:
      version: '8.x'

  - script: dotnet tool restore
    displayName: 'Restore .NET Tools'

  - script: dotnet tool run peardrop info
    displayName: 'Project Information'

  - script: dotnet tool run peardrop migrate
    displayName: 'Run Migrations'
    env:
      ConnectionStrings__PearDrop: $(DATABASE_CONNECTION_STRING)

  - script: dotnet build --configuration Release
    displayName: 'Build Project'

GitHub Actions

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v3
      
      - uses: actions/setup-dotnet@v3
        with:
          dotnet-version: '8.x'
      
      - name: Restore tools
        run: dotnet tool restore
      
      - name: Check updates
        run: dotnet tool run peardrop update --check
      
      - name: Run migrations
        run: dotnet tool run peardrop migrate
        env:
          ConnectionStrings__PearDrop: ${{ secrets.DATABASE_CONNECTION_STRING }}
      
      - name: Deploy
        run: # ... deployment steps

GitLab CI

stages:
  - build
  - migrate
  - deploy

migrate:
  stage: migrate
  script:
    - dotnet tool restore
    - dotnet tool run peardrop migrate
  only:
    - main

Troubleshooting

Migration Connection Failed

Problem: peardrop migrate can't connect to database

Solution:

# Check connection string
peardrop info

# Test connection manually
sqlcmd -S localhost,1440 -U sa -P YourPassword

# Update appsettings.json with correct connection string
# Retry migration
peardrop migrate

Update Failed: Package Not Found

Problem: peardrop update can't find package version

Solution:

# Check available versions
dotnet package search PearDrop.Client

# Verify NuGet source
dotnet nuget list source

# Update with explicit version
peardrop update --version 2.0.5

Extract Context Fails

Problem: peardrop extract-context fails with "aggregate not found"

Solution:

# Ensure aggregate exists
peardrop info

# Try dry run first
peardrop extract-context --context Equipment --dry-run

# Check aggregate naming (case-sensitive)
peardrop extract-context --context EquipmentAggregate

Next Steps

• Project Commands - Initialize projects
• Domain Commands - Build your domain model
• Data Persistence Guide - Learn about migrations