F#
Target F# 11, which ships with .NET 11.
Domain modelling
- Make illegal states unrepresentable: model them as discriminated unions, not as combinations of flags and nullable fields. When a value takes one of several shapes, such as cash, card, or direct debit, give the union one case per shape. The compiler then rejects every invalid combination, so you need no defensive checks or tests for states that can't exist. (Wlaschin: Designing with types: Making illegal states unrepresentable, and the whole Wlaschin: Designing with types series)
-
Wrap domain primitives in single-case unions with a private constructor and a validating
createfunction.CustomerId of intcan't be confused withOrderId of int. Wlaschin's post keeps the constructor private only by convention, "Of course the type is not really private in this case", and says "If you need to enforce encapsulation, use signature files". Theprivatecase in the sample below gets the compiler to enforce it without one, but only as far as the enclosing module:privatemeans "the entity can be accessed only from the enclosing type or module". So give the type and itsEmailAddressmodule a module of their own, asEmailis below. Declared straight in a namespace, the case is open to every module of that namespace in the assembly. Code outsideEmailcan't construct anEmailAddress, so every instance it sees has passedcreate. (Wlaschin: Designing with types: Single case union types, Microsoft Learn: Access control) -
Return
ResultorOptionfrom domain operations instead of throwing. Model failure as data, and compose operations withResult.bind(railway-oriented programming). (Wlaschin: Railway oriented programming) Throw for infrastructure faults, not for "customer not found":Resultis "only for expected control-flow, not for unexpected situations". When "you can't continue, don't return a Result and keep going. Fail fast instead with an exception". (Wlaschin: Against Railway-Oriented Programming)
type CustomerId = CustomerId of int
// A module of their own: `private` reaches as far as the enclosing module.
module Email =
type EmailAddress = private EmailAddress of string
module EmailAddress =
let create (s: string) =
if s.Contains "@" then Some(EmailAddress s) else None
let value (EmailAddress s) = s
type PaymentMethod =
| Cash
| Card of cardNumber: string * expiry: string
| DirectDebit of iban: string
// Exhaustive match: adding a case is a compile error at every use site until handled
let describe payment =
match payment with
| Cash -> "cash"
| Card(number, _) -> $"card ending {number.Substring(max 0 (number.Length - 4))}"
| DirectDebit iban -> $"direct debit from {iban}"
Language opinions (F# 11)
-
Use
and!intaskexpressions to await independent operations concurrently. A sequence oflet!bindings starts each operation only after the one before it completes. (Microsoft Learn: What's new in F# 10) -
On hot paths, mark optional parameters
[<Struct>], so they compile toValueOption<'T>and skip the heap allocation ofOption<'T>. (.NET Blog: Introducing F# 10, Microsoft Learn: What's new in F# 10) -
Write
seq { ... }explicitly. F# 10 deprecates a bare brace block as a sequence expression and reportsFS3873: This construct is deprecated. Sequence expressions should be of the form 'seq { ... }'. The warning is about the missingseq, not the contents. (Microsoft Learn: What's new in F# 10, dotnet/fsharp: FSComp.txt, fsharp/fslang-design: FS-1033 Deprecate places where seq can be omitted) -
Scope a warning suppression with a
#nowarnand#warnonpair around the lines concerned. Never leave a bare#nowarnthat runs to the end of the file. (.NET Blog: Introducing F# 10) - Remove
<ParallelCompilation>from F# project files. It was a preview opt-in in F# 10. In F# 11, "Parallel compilation is now enabled by default, with deterministic output and source-order rules preserved." (Microsoft Learn: What's new in F# 11)
Mixed C#/F# solutions
- Put the domain model and core business logic in F# projects. Hosts and framework-heavy edges, such as ASP.NET Core startup and UI shells, can stay in C#. The domain is where the type-driven modelling under Domain modelling applies. At the edges, Seemann credits C# with Razor integration and better editor tooling. (Seemann: Worse is better: C# versus F#)
- Use F# projects to ban dependency cycles. F# compiles files in declaration order and rejects circular dependencies between them, so a layering violation fails the build. Seemann calls this the strongest architectural argument for F#: C# relies on convention where F# enforces the rule. He also credits C# with more mature complexity, coverage, and mutation testing tools. (Seemann: Worse is better: C# versus F#)
- Keep F#-specific types off public APIs that C# consumes. Inside F#, use
Option, F# lists, and curried functions freely. At the boundary, write what the guidelines call a vanilla .NET library, "minimizing the use of F#-specific constructs in the public API": expose namespaces with classes and tupled methods, and keepFSharpOptionandFSharpListout of C# signatures. (Microsoft Learn: F# component design guidelines) - Share
Directory.Build.propsandDirectory.Packages.propsfromtemplates/across both languages. F# projects then get the same TFM, Central Package Management, and CI setup. Central Package Management covers every project that usesPackageReference, including.fsprojfiles. (Microsoft Learn: Central Package Management)
Testing F#
Use xUnit v3 for F# tests, the same stack as the rest of the solution. Put [<Fact>] on a let-bound function, with no class. The Microsoft Learn walkthrough shows that form on xUnit v2, and it's the same on v3. One stack shares fixtures, tooling, and CI configuration across C# and F#. For details, see testing.md. Expecto puts a second runner and a second assertion style in the solution, and its tests-as-values model isn't worth maintaining both. (Microsoft Learn: Unit testing F# with dotnet test and xUnit)
module EmailAddressTests
open Email
open Xunit
[<Fact>]
let ``Create_StringWithoutAtSign_ReturnsNone`` () =
// Arrange
let input = "not-an-email"
// Act
let result = EmailAddress.create input
// Assert
Assert.Equal(None, result)
Source redundancy
Independent F# sources are scarce:
- F# for Fun and Profit hasn't published since its two-part design series in December 2025. Its back catalogue on domain modelling and functional design is still the standard reference. The 2026-09-14 harvest flagged the gap for a
vet-sourcepass. - F# Weekly reports news, not argument.
mark-seemannis independent and unmarked, and this file cites him only on F# versus C# trade-offs.
So the F# opinions lean on official sources more than the C# ones do.