Skip to content

21_GlobalConfigurationDefaults.md

Latest commit

 

History

History
186 lines (139 loc) · 6.07 KB

21_GlobalConfigurationDefaults.md

File metadata and controls

186 lines (139 loc) · 6.07 KB

Global Configuration Defaults

Overview

Facet allows you to override the default values for attribute properties globally using MSBuild properties. This is useful when you want to apply consistent settings across all your facets without having to specify the same property on every attribute.

Use Case

When working with mapping libraries like Mapperly, you may need to disable certain Facet features (like constructor generation) to avoid conflicts. Instead of setting GenerateConstructor = false on every facet, you can configure this globally.

Supported Configuration Properties

The following properties can be configured globally for the [Facet] attribute:

Property Default MSBuild Property
GenerateConstructor true Facet_GenerateConstructor
GenerateParameterlessConstructor true Facet_GenerateParameterlessConstructor
GenerateProjection true Facet_GenerateProjection
GenerateToSource false Facet_GenerateToSource
IncludeFields false Facet_IncludeFields
ChainToParameterlessConstructor false Facet_ChainToParameterlessConstructor
NullableProperties false Facet_NullableProperties
CopyAttributes false Facet_CopyAttributes
UseFullName false Facet_UseFullName
GenerateCopyConstructor false Facet_GenerateCopyConstructor
GenerateEquality false Facet_GenerateEquality
MaxDepth 10 Facet_MaxDepth
MaxDepthToSource 0 Facet_MaxDepthToSource
PreserveReferences true Facet_PreserveReferences

How to Configure

Option 1: Project File (.csproj)

Add MSBuild properties to your .csproj file:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>

    <!-- Override Facet defaults -->
    <Facet_GenerateConstructor>false</Facet_GenerateConstructor>
    <Facet_GenerateProjection>true</Facet_GenerateProjection>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Facet" Version="5.7.0" />
  </ItemGroup>
</Project>

Option 2: Directory.Build.props

For multi-project solutions, create a Directory.Build.props file at the solution root:

<Project>
  <PropertyGroup>
    <!-- Override Facet defaults for all projects -->
    <Facet_GenerateConstructor>false</Facet_GenerateConstructor>
    <Facet_GenerateParameterlessConstructor>true</Facet_GenerateParameterlessConstructor>
  </PropertyGroup>
</Project>

This approach applies the settings to all projects in the solution directory tree.

Example: Using with Mapperly

When using Facet alongside Mapperly for mapping, you may want to disable Facet's constructor generation to let Mapperly handle the mapping logic:

Directory.Build.props:

<Project>
  <PropertyGroup>
    <!-- Disable constructor generation for Mapperly compatibility -->
    <Facet_GenerateConstructor>false</Facet_GenerateConstructor>
  </PropertyGroup>
</Project>

Your code:

// Domain model
public class User
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
}

// Facet DTO - constructor generation is disabled globally
[Facet(typeof(User))]
public partial class UserDto;

// Mapperly mapper
[Mapper]
public partial class UserMapper
{
    public partial UserDto MapToDto(User user);
}

Now all facets will have GenerateConstructor = false by default, unless explicitly overridden on the attribute.

Overriding Global Defaults

You can still override the global default on individual facets by explicitly setting the property:

// This facet will generate a constructor despite the global setting
[Facet(typeof(User), GenerateConstructor = true)]
public partial class UserDtoWithConstructor;

// This facet uses the global default (no constructor)
[Facet(typeof(User))]
public partial class UserDtoWithoutConstructor;

Precedence

The configuration precedence from highest to lowest is:

  1. Explicit attribute property > Set directly on the [Facet] attribute
  2. Global MSBuild property > Set via Facet_PropertyName in .csproj or Directory.Build.props
  3. Hardcoded default > The default value defined in the Facet library

Example Scenarios

Scenario 1: All Facets as Query DTOs

Make all facets nullable by default for query/filter scenarios:

<PropertyGroup>
  <Facet_NullableProperties>true</Facet_NullableProperties>
</PropertyGroup>

Scenario 2: Disable All Code Generation Except Properties

<PropertyGroup>
  <Facet_GenerateConstructor>false</Facet_GenerateConstructor>
  <Facet_GenerateParameterlessConstructor>false</Facet_GenerateParameterlessConstructor>
  <Facet_GenerateProjection>false</Facet_GenerateProjection>
</PropertyGroup>

Scenario 3: Enable Full Name Generation

Avoid naming conflicts by using full type names for all generated files:

<PropertyGroup>
  <Facet_UseFullName>true</Facet_UseFullName>
</PropertyGroup>

Scenario 4: Copy All Attributes by Default

Preserve validation and serialization attributes from source types:

<PropertyGroup>
  <Facet_CopyAttributes>true</Facet_CopyAttributes>
</PropertyGroup>

Notes

  • Global defaults are read at build time from MSBuild properties
  • Changes to global configuration require a rebuild to take effect
  • These settings only affect the [Facet] attribute (support for [Wrapper] and [GenerateDtos] may be added in future versions)
  • Boolean values should be true or false (case-insensitive)
  • Numeric values (like MaxDepth) should be valid integers
  • The Facet package automatically makes these properties visible to the source generator via CompilerVisibleProperty - no manual configuration needed

Related Documentation