Skip to content

Commit d14d787

Browse files
JerrettDavisJerrettDavis
authored
feat: add JD.Efcpt.Sdk MSBuild SDK package and documentation (#28)
* feat: add JD.Efcpt.Sdk MSBuild SDK package and documentation - Add JD.Efcpt.Sdk as MSBuild SDK for cleaner project integration - Create sdk-zero-config sample demonstrating SDK usage - Extract FileSystemHelpers utility class for code reuse - Add comprehensive SDK integration tests - Update all documentation with SDK approach as primary option - Fix troubleshooting docs for multi-provider support - Clarify CI/CD docs for cross-platform DACPAC builds
1 parent 04cd7eb commit d14d787

59 files changed

Lines changed: 3497 additions & 725 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,6 @@ obj/
77
*.log
88
docs/api
99
docs/_site
10-
coverage.cobertura.xml
10+
coverage.cobertura.xml
11+
pkg/
12+
artifacts/

‎JD.Efcpt.Build.sln‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "JD.Efcpt.Build.Tasks", "src
88
EndProject
99
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "JD.Efcpt.Build.Tests", "tests\JD.Efcpt.Build.Tests\JD.Efcpt.Build.Tests.csproj", "{0E3C0266-4B23-4F2C-8BA9-AE26EF9C98FE}"
1010
EndProject
11+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "JD.Efcpt.Sdk", "src\JD.Efcpt.Sdk\JD.Efcpt.Sdk.csproj", "{A8E5F3D1-4C82-4E9F-9B3A-7D6E8F2B1C9D}"
12+
EndProject
13+
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "JD.Efcpt.Sdk.IntegrationTests", "tests\JD.Efcpt.Sdk.IntegrationTests\JD.Efcpt.Sdk.IntegrationTests.csproj", "{C7D8E9F0-1A2B-3C4D-5E6F-708192A3B4C5}"
14+
EndProject
1115
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Solution Items", "Solution Items", "{27D3D38E-658D-4F9D-83DF-6B2124B16573}"
1216
ProjectSection(SolutionItems) = preProject
1317
CONTRIBUTING.md = CONTRIBUTING.md
@@ -35,5 +39,13 @@ Global
3539
{0E3C0266-4B23-4F2C-8BA9-AE26EF9C98FE}.Debug|Any CPU.Build.0 = Debug|Any CPU
3640
{0E3C0266-4B23-4F2C-8BA9-AE26EF9C98FE}.Release|Any CPU.ActiveCfg = Release|Any CPU
3741
{0E3C0266-4B23-4F2C-8BA9-AE26EF9C98FE}.Release|Any CPU.Build.0 = Release|Any CPU
42+
{A8E5F3D1-4C82-4E9F-9B3A-7D6E8F2B1C9D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
43+
{A8E5F3D1-4C82-4E9F-9B3A-7D6E8F2B1C9D}.Debug|Any CPU.Build.0 = Debug|Any CPU
44+
{A8E5F3D1-4C82-4E9F-9B3A-7D6E8F2B1C9D}.Release|Any CPU.ActiveCfg = Release|Any CPU
45+
{A8E5F3D1-4C82-4E9F-9B3A-7D6E8F2B1C9D}.Release|Any CPU.Build.0 = Release|Any CPU
46+
{C7D8E9F0-1A2B-3C4D-5E6F-708192A3B4C5}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
47+
{C7D8E9F0-1A2B-3C4D-5E6F-708192A3B4C5}.Debug|Any CPU.Build.0 = Debug|Any CPU
48+
{C7D8E9F0-1A2B-3C4D-5E6F-708192A3B4C5}.Release|Any CPU.ActiveCfg = Release|Any CPU
49+
{C7D8E9F0-1A2B-3C4D-5E6F-708192A3B4C5}.Release|Any CPU.Build.0 = Release|Any CPU
3850
EndGlobalSection
3951
EndGlobal

‎README.md‎

Lines changed: 59 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,22 @@ Automate database-first EF Core model generation as part of your build pipeline.
1313

1414
## 🚀 Quick Start
1515

16-
### Install (2 steps, 30 seconds)
16+
Choose your integration approach:
17+
18+
### Option A: SDK Approach (Recommended for new projects)
19+
20+
Use the SDK in your project file:
21+
22+
```xml
23+
<Project Sdk="JD.Efcpt.Sdk/1.0.0">
24+
<PropertyGroup>
25+
<TargetFramework>net8.0</TargetFramework>
26+
</PropertyGroup>
27+
<!-- ProjectReference to your SQL project -->
28+
</Project>
29+
```
30+
31+
### Option B: PackageReference Approach
1732

1833
**Step 1:** Add the NuGet package to your application project / class library:
1934

@@ -29,7 +44,7 @@ dotnet build
2944

3045
**That's it!** Your EF Core DbContext and entities are now automatically generated from your database project during every build.
3146

32-
> **✨ .NET 8 and 9 Users must install the `ErikEJ.EFCorePowerTools.Cli` tool in advance:**
47+
> **✨ .NET 8 and 9 Users must install the `ErikEJ.EFCorePowerTools.Cli` tool in advance:**
3348
3449
```bash
3550
dotnet tool install --global ErikEJ.EFCorePowerTools.Cli --version "8.*"
@@ -42,6 +57,7 @@ dotnet tool install --global ErikEJ.EFCorePowerTools.Cli --version "9.*"
4257

4358
- [Overview](#-overview)
4459
- [Quick Start](#-quick-start)
60+
- [SDK vs PackageReference](#-sdk-vs-packagereference)
4561
- [Features](#-features)
4662
- [Installation](#-installation)
4763
- [Minimal Usage Example](#-minimal-usage-example)
@@ -78,6 +94,47 @@ The package orchestrates a MSBuild pipeline with these stages:
7894

7995
---
8096

97+
## 📦 SDK vs PackageReference
98+
99+
JD.Efcpt.Build offers two integration approaches:
100+
101+
### JD.Efcpt.Sdk (SDK Approach)
102+
103+
Use the SDK when you want the **cleanest possible setup**:
104+
105+
```xml
106+
<Project Sdk="JD.Efcpt.Sdk/1.0.0">
107+
<PropertyGroup>
108+
<TargetFramework>net8.0</TargetFramework>
109+
</PropertyGroup>
110+
</Project>
111+
```
112+
113+
**Best for:**
114+
- Dedicated EF Core model generation projects
115+
- The simplest, cleanest project files
116+
117+
### JD.Efcpt.Build (PackageReference Approach)
118+
119+
Use the PackageReference when adding to an **existing project**:
120+
121+
```xml
122+
<ItemGroup>
123+
<PackageReference Include="JD.Efcpt.Build" Version="1.0.0" />
124+
</ItemGroup>
125+
```
126+
127+
**Best for:**
128+
- Adding EF Core generation to existing projects
129+
- Projects already using custom SDKs
130+
- Version management via Directory.Build.props
131+
132+
Both approaches provide **identical features** - choose based on your project structure.
133+
134+
See the [SDK documentation](docs/user-guide/sdk.md) for detailed guidance.
135+
136+
---
137+
81138
## ✨ Features
82139

83140
### Core Capabilities

‎docs/index.md‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,22 @@ JD.Efcpt.Build transforms EF Core Power Tools into a fully automated build step.
2020

2121
## Quick Start
2222

23+
Choose your preferred integration approach:
24+
25+
### Option A: SDK Approach (Cleanest Setup)
26+
27+
Use the SDK in your project:
28+
29+
```xml
30+
<Project Sdk="JD.Efcpt.Sdk/1.0.0">
31+
<PropertyGroup>
32+
<TargetFramework>net8.0</TargetFramework>
33+
</PropertyGroup>
34+
</Project>
35+
```
36+
37+
### Option B: PackageReference Approach
38+
2339
**Step 1:** Add the NuGet package:
2440

2541
```xml
@@ -34,7 +50,7 @@ JD.Efcpt.Build transforms EF Core Power Tools into a fully automated build step.
3450
dotnet tool install --global ErikEJ.EFCorePowerTools.Cli --version "10.*"
3551
```
3652

37-
**Step 3:** Build your project:
53+
### Build Your Project
3854

3955
```bash
4056
dotnet build
@@ -62,6 +78,7 @@ The package orchestrates a six-stage MSBuild pipeline:
6278
## Next Steps
6379

6480
- [Getting Started](user-guide/getting-started.md) - Complete installation and setup guide
81+
- [Using JD.Efcpt.Sdk](user-guide/sdk.md) - SDK integration approach
6582
- [Core Concepts](user-guide/core-concepts.md) - Understanding the build pipeline
6683
- [Configuration](user-guide/configuration.md) - Customize generation behavior
6784

‎docs/user-guide/ci-cd.md‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -424,10 +424,19 @@ steps:
424424
425425
### DACPAC Mode Requirements
426426
427-
Building `.sqlproj` to DACPAC typically requires Windows agents with SQL Server Data Tools installed.
427+
**Modern SDK-style SQL Projects** (`Microsoft.Build.Sql` or `MSBuild.Sdk.SqlProj`) build cross-platform:
428428

429429
```yaml
430-
# GitHub Actions - Windows for DACPAC
430+
# GitHub Actions - Linux works with modern SQL SDKs
431+
jobs:
432+
build:
433+
runs-on: ubuntu-latest # Works with Microsoft.Build.Sql and MSBuild.Sdk.SqlProj
434+
```
435+
436+
**Traditional SQL Projects** (legacy `.sqlproj` format) require Windows with SQL Server Data Tools:
437+
438+
```yaml
439+
# GitHub Actions - Windows required for traditional .sqlproj
431440
jobs:
432441
build:
433442
runs-on: windows-latest
@@ -438,7 +447,7 @@ jobs:
438447
Connection string mode works on both Windows and Linux:
439448

440449
```yaml
441-
# GitHub Actions - Linux is fine for connection string mode
450+
# GitHub Actions - Any platform works
442451
jobs:
443452
build:
444453
runs-on: ubuntu-latest
@@ -457,13 +466,15 @@ For .NET 8-9, ensure tool restore runs before build:
457466

458467
### DACPAC build fails
459468

460-
Ensure Windows agent with SQL Server Data Tools:
469+
For **traditional SQL Projects**, use Windows with SQL Server Data Tools:
461470

462471
```yaml
463472
pool:
464473
vmImage: 'windows-latest'
465474
```
466475

476+
For **modern SDK-style projects** (`Microsoft.Build.Sql` or `MSBuild.Sdk.SqlProj`), Linux works fine - verify your project SDK is configured correctly.
477+
467478
### Inconsistent generated code
468479

469480
Clear the cache to force regeneration:
@@ -482,7 +493,7 @@ Enable caching for the efcpt intermediate directory to skip regeneration when sc
482493
1. **Use .NET 10+** when possible to eliminate tool installation steps
483494
2. **Use local tool manifests** (.NET 8-9) for version consistency
484495
3. **Cache intermediate directories** to speed up incremental builds
485-
4. **Use Windows agents** for DACPAC mode
496+
4. **Use modern SQL SDKs** (`Microsoft.Build.Sql` or `MSBuild.Sdk.SqlProj`) for cross-platform DACPAC builds
486497
5. **Use environment variables** for connection strings
487498
6. **Never commit credentials** to source control
488499

‎docs/user-guide/getting-started.md‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,43 @@ Before you begin, ensure you have:
1414

1515
## Installation
1616

17-
### Step 1: Add the NuGet Package
17+
Choose your integration approach:
18+
19+
| Approach | Best For |
20+
|----------|----------|
21+
| **JD.Efcpt.Sdk** | New projects, cleanest setup |
22+
| **JD.Efcpt.Build** | Existing projects, projects with custom SDKs |
23+
24+
### Option A: SDK Approach (Recommended for new projects)
25+
26+
The SDK approach provides the cleanest project files.
27+
28+
Use the SDK in your project file with the version specified inline:
29+
30+
```xml
31+
<Project Sdk="JD.Efcpt.Sdk/1.0.0">
32+
<PropertyGroup>
33+
<TargetFramework>net8.0</TargetFramework>
34+
<ImplicitUsings>enable</ImplicitUsings>
35+
<Nullable>enable</Nullable>
36+
</PropertyGroup>
37+
38+
<ItemGroup>
39+
<ProjectReference Include="..\DatabaseProject\DatabaseProject.sqlproj">
40+
<ReferenceOutputAssembly>false</ReferenceOutputAssembly>
41+
<OutputItemType>None</OutputItemType>
42+
</ProjectReference>
43+
</ItemGroup>
44+
45+
<ItemGroup>
46+
<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.11" />
47+
</ItemGroup>
48+
</Project>
49+
```
50+
51+
See [Using JD.Efcpt.Sdk](sdk.md) for complete SDK documentation.
52+
53+
### Option B: PackageReference Approach
1854

1955
Add JD.Efcpt.Build to your application project (the project that should contain the generated DbContext and entities):
2056

‎docs/user-guide/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -102,5 +102,6 @@ Generated files are:
102102
## Next Steps
103103

104104
- [Getting Started](getting-started.md) - Install and configure JD.Efcpt.Build
105+
- [Using JD.Efcpt.Sdk](sdk.md) - SDK integration for the cleanest setup
105106
- [Core Concepts](core-concepts.md) - Deep dive into the pipeline architecture
106107
- [Configuration](configuration.md) - Customize generation behavior

0 commit comments

Comments
 (0)