# MSBuild integration

> Understand generated alproj files, Alice SDK imports, mixed C# sources, and build defaults.

Canonical: https://alice-lang.org/documentation/tools/sdk/

[Documentation index](https://alice-lang.org/documentation/llms.txt) · [Complete book](https://alice-lang.org/llms-full.txt)

## The generated project

The CLI synchronizes a manifest into `.alice/<package>.alproj`, then uses MSBuild for project builds. This connects Alice to the .NET SDK, project references, NuGet, and publishing without making generated XML your primary configuration.

`alice.toml` remains authoritative. `.alice/` can be removed and recreated. Use manifest dependencies or stable MSBuild files for settings that must survive a rebuild.

## SDK files

| File            | Role                                                                 |
| --------------- | -------------------------------------------------------------------- |
| `Alice.props`   | Target-framework defaults, nullable checking, TieredPGO, GC defaults |
| `Alice.targets` | Compile Alice source and include generated C# in the .NET build      |

The current default framework is `net10.0`. Nullable errors are enabled. Server and concurrent GC are defaults that can be overridden by the consuming project where appropriate.

The targets can participate in `.alproj` and `.csproj` builds. Repository samples import the SDK through their checked-in `Directory.Build.props` and `Directory.Build.targets` files.

## Additional build configuration

Put framework references, content rules, and extra MSBuild properties in a stable `Directory.Build.props` or `Directory.Build.targets`. For example, an ASP.NET package needs a `FrameworkReference` to `Microsoft.AspNetCore.App`; it is not an ordinary NuGet package dependency.

When a `Directory.Build.props` already exists higher in the tree, remember that MSBuild's discovery/import rules apply. Preserve intended parent settings explicitly rather than accidentally shadowing them with a new local file.

## Mixed projects

Alice package sources can include `.al` and `.cs` files under `src/`. A C# project can reference an Alice-generated `.alproj`, and an Alice manifest can reference a C# project path. Generate and build dependency metadata before expecting an editor to resolve its public API.

`dotnet build` and `dotnet run` work against a generated project after synchronization. For ordinary Alice work, `alice build` and `alice run` perform that synchronization for you.

## Troubleshoot a build

Check the source manifest, selected SDK, and resolved dependencies first. Inspect the generated project when diagnosing, but make the lasting fix in the manifest or stable MSBuild input. `alice emit` helps isolate an Alice lowering issue from a package/framework-reference issue.

## Continue reading

- Previous: [Toolchains and updates](https://alice-lang.org/documentation/tools/toolchains.md)
- Next: [Diagnostic reference](https://alice-lang.org/documentation/reference/diagnostics.md)