MSBuild properties and environment variables

Environment variables

Property	Type	Description
`METALAMA_TEMP`	String	The root path of Metalama temporary directory. The default value is the result of `Path.GetTempPath()`.

MSBuild properties

All environment variables are imported as MSBuild properties by default.

Property	Type	Description
`MetalamaCompilerTransformerOrder`	Semicolon-separated list	Specifies the execution order of transformers in the current project. Transformers are identified by their namespace-qualified type name, excluding the assembly name. This property is generally unimportant because the only transformer is typically Metalama.Framework.
`MetalamaDebugTransformedCode`	Boolean	Indicates whether to debug the transformed code instead of the source code. The default value is `False`.
`MetalamaEmitCompilerTransformedFiles`	Boolean	Indicates whether `Metalama.Compiler` should write the transformed code files to disk. The default is `True` if `MetalamaDebugTransformedCode` is enabled, and `False` otherwise.
`MetalamaCompilerTransformedFilesOutputPath`	Path	Specifies the directory path where transformed code files are written. The default is `obj/$(Configuration)/$(TargetFramework)/metalama` (for example, `obj/LamaDebug/net10.0/metalama`).
`MetalamaDebugCompiler`	Boolean	Specifies whether to attach a debugger to the compiler process. The default value is `False`.
`MetalamaLicense`	String	Represents a Metalama license key or license server URL. Any license key or license server URL provided this way takes precedence over the license registered via the `metalama` global tool.
`MetalamaEnabled`	Boolean	When set to `False`, specifies that Metalama.Framework won't execute in this project, even though the Metalama.Framework package is referenced. It doesn't affect the Metalama.Compiler package.
`MetalamaFormatOutput`	Boolean	Indicates whether the transformed code should be nicely formatted. The default value is `True` if `MetalamaDebugTransformedCode` is `True` and `False` otherwise. This default is evaluated after the project file, so setting `MetalamaDebugTransformedCode` to `True` in your `.csproj` correctly triggers `MetalamaFormatOutput`. You can also set `MetalamaFormatOutput` explicitly in your project file to override the default. Formatting the transformed code has a performance overhead and should only be performed when the code is being troubleshot or exported. When formatting is enabled, the build emits warning LAMA0066 as a reminder of this overhead. This warning is expected and harmless.
`MetalamaFormatCompileTimeCode`	Boolean	Indicates whether the compile-time code should be nicely formatted. The default value is `False`. Formatting the compile-time code has a performance overhead and should only be performed when the code is being troubleshot or exported.
`MetalamaCompileTimeProject`	Boolean	Indicates whether the complete project is compile-time code. This property is set to `True` by the Metalama.Framework.Sdk package. Otherwise, the default value is `False`.
`MetalamaDesignTimeEnabled`	Boolean	Indicates whether the real-time design-time experience is enabled. The default value is `True`, and it can be set to `False` to work around performance issues. When this property is set to `False`, refreshing the IntelliSense cache requires you to rebuild the project.
`MetalamaRemoveCompileTimeOnlyCode`	Boolean	Indicates whether Metalama should replace compile-time-only code with `throw new NotSupportedException()` in produced assemblies. The default value is `True` because Metalama normally executes compile-time-only code from the compile-time sub-project embedded as a managed resource in the assembly. This property should be set to `False` in public assemblies referenced by a weaver-style project (using Metalama SDK) because Metalama SDK needs to execute compile-time-only code from the main assembly.
`MetalamaCompileTimeTargetFrameworks`	Semicolon-separated list	Specifies the list of target frameworks for which compile-time projects should be built. The default value covers all native frameworks that are known to host the compiler. Override this property if you don't need all of them and can't install the required .NET targeting packs on the machine. `netstandard2.0` is required.
`MetalamaRestoreSources`	Semicolon-separated list	Specifies the list of NuGet feeds used when restoring the compile-time project. The default value is `https://api.nuget.org/v3/index.json`.
`MetalamaCreateLamaDebugConfiguration`	Boolean	Indicates whether the `LamaDebug` build configuration should be automatically defined (see below). The default value is `True`.
`MetalamaTemplateLanguageVersion`	String	Specifies the C# language version (e.g., `10.0`) that's used by templates. Any syntax from higher C# versions isn't allowed in template bodies. Such templates can then be used in projects that use this C# version.
`MetalamaConcurrentBuildEnabled`	Boolean	Specifies whether Metalama can parallelize work across several cores. The default value is `True`.
`MetalamaRoslynIsCompileTimeOnly`	Boolean	Indicates whether types from the `Microsoft.CodeAnalysis` namespaces are considered compile-time-only. The default value is `False`, except in projects that reference the `Metalama.Framework.Sdk` package, which sets it to `True`. Set it to `False` if such a project uses Roslyn in run-time code. See LAMA0291.
`MetalamaRootDirectory`	Path	Specifies the directory to which the path of the project is made relative when Metalama computes the identifier of the project. The default value is `$(SolutionDir)`. A relative path keeps the build reproducible, because the identifier is a part of the compilation and a full path would make the compiled assembly depend on the directory into which the repository is cloned. Set this property when a project is built from several solutions located in different directories and the build must be reproducible in all of them. When neither this property nor `$(SolutionDir)` is defined, which is the case when a project is built without a solution, only the file name of the project is used.
`MetalamaAssemblyLocatorHooksDirectory`	Path	Specifies a directory whose `Metalama.AssemblyLocator.Build.props` and `Metalama.AssemblyLocator.Build.targets` files, if they exist, are imported into the internal project that Metalama builds to determine which APIs are available to compile-time code. There is no default value, and no file is imported unless this property is set. See Restoring compile-time dependencies.
`MetalamaAssemblyLocatorSalt`	String	Specifies an arbitrary value that is included in the cache key of the project that Metalama builds to resolve the compile-time dependencies. There is no default value. Change it to any other value to have that project restored and built again instead of its cached result being reused. See Restoring compile-time dependencies.
`MetalamaDiagnoseMemoryLeaks`	Boolean	Indicates whether the objects that your compile-time code leaves behind should be analyzed for references that keep a project snapshot in memory. The default value is `False`. Pass this property on the command line of a single build while you're investigating a memory leak: the analysis walks a large object graph and is too slow for an ordinary build. See Diagnosing memory leaks caused by compile-time code.
`MetalamaCheckSupportedPlatform`	Boolean	Indicates whether the build reports a target framework, a .NET SDK or a Visual Studio version outside the configuration matrix that Metalama supports. The default value is `True`. Set it to `False` to turn off every warning of the check. See The supported platform check below.

MSBuild items

Item	Description
`MetalamaTransformedCodeAnalyzer`	Represents a list of analyzers that must execute on the transformed code instead of the source code. Items can be set to a namespace or a full type name.
`MetalamaCompileTimePackage`	Represents a list of packages accessible from the compile-time code. These packages must explicitly target .NET Standard 2.0 and be included in the project as a `ProjectReference`. By default, only the .NET Standard 2.0 API and the Metalama API are available to compile-time code.
`MetalamaExtensionAssembly`	Loads an assembly as a Metalama extension at compile time. The assembly must contain types exported via ExportExtensionAttribute. Supports `TargetFramework` (e.g., `net472`, `net10.0`) and `TargetRoslynVersion` (e.g., `4.8`, `4.12`, `5.0`) metadata to specify which build of the extension to load. See SDK extension projects.
`MetalamaCompileTimeAssembly`	Makes an assembly available to compile-time code. Use this when your compile-time code references types from an external assembly that isn't a NuGet package. See SDK extension projects.
`MetalamaSupportedPlatformExclusion`	Turns off the supported platform check for the package whose name it gives, and leaves the check of the other packages in place. See The supported platform check below.

The supported platform check

Metalama supports a defined set of target frameworks, .NET SDK versions and Visual Studio versions. When your project falls outside that set, the build reports one of the following warnings. The build continues, but a problem that is specific to an unsupported configuration will not be fixed. When you cannot move to a supported configuration, use an earlier version of Metalama that supports it, typically a long-term support (LTS) version.

Code	Reported when
`LAMA0600`	The target framework of the project is outside the supported set.
`LAMA0601`	The .NET SDK that drives the build is older or newer than the supported set.
`LAMA0602`	The build runs on `msbuild.exe` from a version of Visual Studio older than the oldest supported one. A build started by `dotnet build` never reports it.

To turn the warnings off, use one of the following mechanisms, from the broadest to the narrowest:

Set the MetalamaCheckSupportedPlatform property to False to turn off the whole check.
Add a warning code, in its full LAMA form, to the NoWarn property to turn off one dimension of the check.
Add a MetalamaSupportedPlatformExclusion item naming a package, for example <MetalamaSupportedPlatformExclusion Include="Metalama.Patterns.Wpf" />, to turn off the check for that package only.

MSBuild build configurations

When you import Metalama.Framework, a new build configuration named LamaDebug is defined unless you set the MetalamaCreateLamaDebugConfiguration property to False.

The LamaDebug configuration assigns the following properties:

Full screen

<PropertyGroup Condition="'$(Configuration)'=='LamaDebug'">
    <MetalamaDebugTransformedCode>True</MetalamaDebugTransformedCode>
</PropertyGroup>

Note

Because MetalamaDebugTransformedCode enables code formatting by default, builds in the LamaDebug configuration report warning LAMA0066 ("Formatting of generated code is enabled. Build performance could be significantly affected."). This warning is expected in this configuration and doesn't indicate a problem.