<!--
  Copyright (c) 2009-2026 ASN Lab
  All rights reserved.
-->

# ASN.1 C# Compiler Guide

The ASN.1 C# Compiler (`asncsc`) generates C# source code from ASN.1
modules. Generated types are C# classes/structs and work with the C# runtime
library for encoding and decoding.

## Compiler Options

| Field                       | Type    | Default      | Description |
|-----------------------------|---------|--------------|-------------|
| `output-folder`             | string  | `"c#"`       | Output directory for generated C# sources. |
| `mapping.integer`           | ENUM    | `automatic`  | See [Integer Mapping](#integer-mapping). |
| `mapping.real`              | ENUM    | `double`     | `automatic`, `float`, `double`. |
| `lower-case-namespace`      | BOOLEAN | TRUE         | Convert module names to lower case for C# namespace names. |
| `namespace-prefix`          | string  | `""`         | Prefix prepended to every generated namespace. |
| `generate.properties`       | BOOLEAN | FALSE        | Generate C# properties instead of public fields. |
| `generate.clones`           | BOOLEAN | FALSE        | Generate `Clone()` methods. |
| `generate.equals`           | BOOLEAN | TRUE         | Generate `Equals()` and `GetHashCode()` overrides. |
| `generate.prints`           | BOOLEAN | FALSE        | Generate `ToString()` overrides. |
| `generate.hash-code`        | BOOLEAN | TRUE         | Generate `GetHashCode()` overrides. |

## Integer Mapping

Controls how ASN.1 INTEGER is mapped to C# types:

| Option        | C# type |
|---------------|---------|
| `automatic`   | `BigInteger` when unconstrained; smallest `long`/`int` that fits otherwise. |
| `int32`       | `int`. |
| `int64`       | `long`. |
| `big-integer` | `BigInteger`. |

## Real Mapping

| Option      | C# type |
|-------------|---------|
| `automatic` | `double`. |
| `float`     | `float`. |
| `double`    | `double`. |

## Project Configuration Example

```asn1
compilers {
    {
        language "c#",
        options {
            output-folder "c#",
            mapping {
                integer automatic,
                real double
            },
            lower-case-namespace TRUE,
            namespace-prefix "MyCompany.Protocols",
            generate {
                properties FALSE,
                clones FALSE,
                equals TRUE,
                prints FALSE,
                hash-code TRUE
            }
        }
    }
}
```

## Runtime Integration

Add the C# runtime library to your project references. The generated types
provide `Encode` and `Decode` methods that accept an encoding rule constant
(BER, DER, UPER, APER, OER, XER, JER).

## Generated Output

With `output "build"` and `csharp.output-folder "c#"`, output is written under
`build/c#/`. Each ASN.1 module produces C# source files inside a namespace
derived from the module name.
