Troubleshooting

This guide helps you diagnose and resolve common issues with JD.Efcpt.Build.

Diagnostic Tools

Enable Detailed Logging

Add these properties to your .csproj for maximum visibility:

<PropertyGroup>
  <EfcptLogVerbosity>detailed</EfcptLogVerbosity>
  <EfcptDumpResolvedInputs>true</EfcptDumpResolvedInputs>
</PropertyGroup>

Inspect Build Output

Run with detailed MSBuild logging:

dotnet build /v:detailed > build.log 2>&1

Search for JD.Efcpt.Build entries in the log.

Check Resolved Inputs

When EfcptDumpResolvedInputs is true, check obj/efcpt/resolved-inputs.json:

{
  "sqlProjPath": "..\\database\\MyDatabase.sqlproj",
  "configPath": "efcpt-config.json",
  "renamingPath": "efcpt.renaming.json",
  "templateDir": "Template",
  "connectionString": null,
  "useConnectionString": false
}

Common Issues

Generated Files Don't Appear

Symptoms:

No files in obj/efcpt/Generated/
Build succeeds but no DbContext available

Solutions:

Verify package is referenced:

dotnet list package | findstr JD.Efcpt.Build

Check if EfcptEnabled is true:

<PropertyGroup>
  <EfcptEnabled>true</EfcptEnabled>
</PropertyGroup>

Check if database project is found:
- Enable EfcptDumpResolvedInputs
- Look for sqlProjPath in resolved-inputs.json
- Set EfcptSqlProj explicitly if needed
Force regeneration:
```
dotnet clean
dotnet build
```

Database Project Not Found

Symptoms:

Build warning: "Could not find SQL project"
sqlProjPath is empty in resolved inputs

Solutions:

Set path explicitly:

<PropertyGroup>
  <EfcptSqlProj>..\database\MyDatabase.sqlproj</EfcptSqlProj>
</PropertyGroup>

Add project reference:

<ItemGroup>
  <ProjectReference Include="..\database\MyDatabase.sqlproj" />
</ItemGroup>

Check solution directory probing:

<PropertyGroup>
  <EfcptProbeSolutionDir>true</EfcptProbeSolutionDir>
  <EfcptSolutionDir>$(SolutionDir)</EfcptSolutionDir>
</PropertyGroup>

efcpt CLI Not Found

Symptoms:

Error: "efcpt command not found"
Error: "dotnet tool run efcpt failed"

Solutions for .NET 10+:

This should not occur on .NET 10+ (uses dnx)
Verify .NET version: dotnet --version

Solutions for .NET 8-9:

Verify installation:

dotnet tool list --global
dotnet tool list

Reinstall globally:

dotnet tool uninstall -g ErikEJ.EFCorePowerTools.Cli
dotnet tool install -g ErikEJ.EFCorePowerTools.Cli --version "10.*"

Use tool manifest:

dotnet new tool-manifest
dotnet tool install ErikEJ.EFCorePowerTools.Cli --version "10.*"

<PropertyGroup>
  <EfcptToolMode>tool-manifest</EfcptToolMode>
</PropertyGroup>

DACPAC Build Fails

Symptoms:

Error during EfcptEnsureDacpac target
MSBuild errors related to SQL project

Solutions:

Verify SQL project builds independently:
```
dotnet build path\to\Database.sqlproj
```
Install SQL Server Data Tools:
- On Windows, install Visual Studio with SQL Server Data Tools workload
- Or install the standalone SSDT

Use pre-built DACPAC:

<PropertyGroup>
  <EfcptDacpac>path\to\MyDatabase.dacpac</EfcptDacpac>
</PropertyGroup>

Check MSBuild/dotnet path:

<PropertyGroup>
  <EfcptDotNetExe>C:\Program Files\dotnet\dotnet.exe</EfcptDotNetExe>
</PropertyGroup>

Build Doesn't Detect Schema Changes

Symptoms:

Schema changed but models not regenerated
Same fingerprint despite changes

Solutions:

Clean and rebuild:
```
dotnet clean
dotnet build
```
Verify DACPAC was rebuilt:
- Check DACPAC file timestamp
- Ensure SQL project sources are newer
Check fingerprint file:
- Look at obj/efcpt/fingerprint.txt
- Compare with expected hash

Connection String Issues

Symptoms:

"Connection refused" errors
"Authentication failed" errors
No tables generated

Solutions:

Test connection manually:

sqlcmd -S localhost -d MyDb -E -Q "SELECT 1"

Check connection string format:

<EfcptConnectionString>Server=localhost;Database=MyDb;Integrated Security=True;TrustServerCertificate=True;</EfcptConnectionString>

Verify appsettings.json path:

<PropertyGroup>
  <EfcptAppSettings>appsettings.json</EfcptAppSettings>
  <EfcptConnectionStringName>DefaultConnection</EfcptConnectionStringName>
</PropertyGroup>

Enable detailed logging to see resolved connection:
```
<EfcptLogVerbosity>detailed</EfcptLogVerbosity>
```

Templates Not Being Used

Symptoms:

Custom templates exist but default output generated
Template changes not reflected

Solutions:

Verify T4 is enabled:

{
  "code-generation": {
    "use-t4": true,
    "t4-template-path": "."
  }
}

Check template location:
- Verify Template/CodeTemplates/EFCore/ structure
- Check EfcptDumpResolvedInputs for resolved path
Force regeneration:
```
dotnet clean
dotnet build
```

Compilation Errors in Generated Code

Symptoms:

Build errors in .g.cs files
Missing types or namespaces

Solutions:

Check EF Core package version compatibility:

<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.0" />

Verify efcpt version matches:

<EfcptToolVersion>10.*</EfcptToolVersion>

Check nullable reference types setting:

<Nullable>enable</Nullable>

{
  "code-generation": {
    "use-nullable-reference-types": true
  }
}

Slow Builds

Symptoms:

Build takes long even without schema changes
DACPAC rebuilds unnecessarily

Solutions:

Preserve fingerprint cache:
- Don't delete obj/efcpt/ between builds
- Cache in CI/CD pipelines
Use connection string mode:
- Skips DACPAC compilation
- Faster for development

Select specific tables:

{
  "table-selection": [
    {
      "schema": "dbo",
      "tables": ["Users", "Orders"],
      "include": true
    }
  ]
}

Files Generated in Wrong Location

Symptoms:

Files appear in unexpected directory
Multiple copies of generated files

Solutions:

Check output properties:

<PropertyGroup>
  <EfcptOutput>$(BaseIntermediateOutputPath)efcpt\</EfcptOutput>
  <EfcptGeneratedDir>$(EfcptOutput)Generated\</EfcptGeneratedDir>
</PropertyGroup>

Verify no conflicting configurations:
- Check Directory.Build.props
- Check for inherited properties
Check efcpt-config.json T4 Template Path:
- Check "code-generation": { "t4-template-path": "..." } setting for a correct path. At generation time, it is relative to Generation output directory.

Warning and Error Codes

JD.Efcpt.Build uses specific codes for warnings and errors to help identify issues quickly.

EFCPT001: .NET Framework MSBuild Not Supported

Type: Error

Message:

EFCPT001: JD.Efcpt.Build requires .NET Core MSBuild but detected .NET Framework MSBuild

Cause: JD.Efcpt.Build task assemblies target .NET 8.0+ and cannot run on the .NET Framework MSBuild runtime. This typically occurs when building from older versions of Visual Studio or using legacy build tools.

Solutions:

Use Visual Studio 2019 or later with SDK-style projects
Build from command line with dotnet build
Set EfcptEnabled=false to disable code generation if you only need to compile the project

EFCPT001: Auto-Detection Informational Message

Type: Informational (configurable)

Message:

EFCPT001: No SQL project references found in project; using SQL project detected from solution: path/to/project.sqlproj

EFCPT001: No .sqlproj found. Using auto-discovered connection string.

Cause: The build automatically detected a SQL project from the solution or a connection string from configuration files when no explicit reference was provided. This is expected behavior in zero-config scenarios.

Severity Control: Control the message severity using EfcptAutoDetectWarningLevel:

<PropertyGroup>
  <!-- Valid values: None, Info, Warn, Error -->
  <EfcptAutoDetectWarningLevel>Info</EfcptAutoDetectWarningLevel>
</PropertyGroup>

Default: Info (informational message)

Solutions:

If you want to suppress this message entirely, set EfcptAutoDetectWarningLevel=None
If you want to make it a warning, set EfcptAutoDetectWarningLevel=Warn
To be explicit about your SQL project or connection string, configure EfcptSqlProj, EfcptConnectionString, or other relevant properties

EFCPT002: Newer SDK Version Available

Type: Warning (opt-in, configurable)

Message:

EFCPT002: A newer version of JD.Efcpt.Sdk is available: X.Y.Z (current: A.B.C)

Cause: When EfcptCheckForUpdates is enabled, the build checks NuGet for newer SDK versions. This warning indicates an update is available.

Severity Control: Control the message severity using EfcptSdkVersionWarningLevel:

<PropertyGroup>
  <!-- Valid values: None, Info, Warn, Error -->
  <EfcptSdkVersionWarningLevel>Warn</EfcptSdkVersionWarningLevel>
</PropertyGroup>

Default: Warn (warning message)

Solutions:

Update your project's Sdk attribute: Sdk="JD.Efcpt.Sdk/X.Y.Z"
Or update global.json if using centralized version management:
```
{
  "msbuild-sdks": {
    "JD.Efcpt.Sdk": "X.Y.Z"
  }
}
```
To change the severity level, set EfcptSdkVersionWarningLevel to None, Info, Warn, or Error
To disable version checking entirely, set EfcptCheckForUpdates=false

Note: This check is opt-in for package references and opt-out for SDK references. Results are cached for 24 hours to minimize network calls.

Error Messages

"The database provider 'X' is not supported"

Verify the provider value is one of the supported options: mssql, postgres, mysql, sqlite, oracle, firebird, or snowflake. See Connection String Mode for provider-specific configuration.

"Could not find configuration file"

The package couldn't find efcpt-config.json. Either:

Create the file in your project directory
Set EfcptConfig property explicitly
Use package defaults (no action needed)

"Fingerprint file not found"

This is normal on first build. The fingerprint is created after successful generation.

"Failed to query schema metadata"

In connection string mode, the database connection failed. Check:

Connection string syntax
Database server availability
Authentication credentials
Firewall rules

Getting Help

If you're still stuck:

Enable full diagnostics:

<PropertyGroup>
  <EfcptLogVerbosity>detailed</EfcptLogVerbosity>
  <EfcptDumpResolvedInputs>true</EfcptDumpResolvedInputs>
</PropertyGroup>

Capture MSBuild log:

dotnet build /v:detailed > build.log 2>&1

Report an issue with:
- .NET version (dotnet --info)
- JD.Efcpt.Build version
- EF Core Power Tools CLI version
- Relevant MSBuild log sections
- Contents of resolved-inputs.json

Next Steps

Configuration - Review all configuration options
API Reference - Complete MSBuild task reference
CI/CD Integration - Pipeline-specific troubleshooting

Table of Contents

Troubleshooting

Diagnostic Tools

Enable Detailed Logging

Inspect Build Output

Check Resolved Inputs

Common Issues

Generated Files Don't Appear

Database Project Not Found

efcpt CLI Not Found

DACPAC Build Fails

Build Doesn't Detect Schema Changes

Connection String Issues

Templates Not Being Used

Compilation Errors in Generated Code

Slow Builds

Files Generated in Wrong Location

Warning and Error Codes

EFCPT001: .NET Framework MSBuild Not Supported

EFCPT001: Auto-Detection Informational Message

EFCPT002: Newer SDK Version Available

Error Messages

"The database provider 'X' is not supported"

"Could not find configuration file"

"Fingerprint file not found"

"Failed to query schema metadata"

Getting Help

Next Steps