# Getting started

## Add the library

Reference the release DLL from your .NET 10 project:

```xml
<ItemGroup>
  <Reference Include="SWIFTFramework">
    <HintPath>path/to/2026.2/lib/SWIFTFramework.dll</HintPath>
  </Reference>
</ItemGroup>
```

Or add a project reference if you are building from source:

```xml
<ProjectReference Include="..\SourceCode\SWIFTFramework\SWIFTFramework.csproj" />
```

Target framework must be `net10.0` (or a compatible `net10.0-*` TFM).

## Set the license first

Every `SwiftMessage` constructor (including parse) checks the license. Set the key before any message work:

```csharp
using SWIFTFramework;

Licensing.RunTimeLicenseKey = Environment.GetEnvironmentVariable("SWIFTFRAMEWORK_RUNTIME_LICENSE_KEY");
// or rely on .NET User Secrets: SWIFTFramework:RuntimeLicenseKey
```

If the key is missing or not a `SWF-26-2x` product, constructing a message throws `System.ComponentModel.LicenseException`.

Run a sample (no key is shipped):

```bash
export SWIFTFRAMEWORK_RUNTIME_LICENSE_KEY='your-purchased-key'
dotnet run --project Framework/SourceCode/ConsoleSample/ConsoleSample.csproj
```

From this release package:

```bash
export SWIFTFRAMEWORK_RUNTIME_LICENSE_KEY='your-purchased-key'
dotnet run --project samples/ParseAndModify/ParseAndModify.csproj
```

See [licensing.md](licensing.md) and [../samples/README.md](../samples/README.md).

## Parse a message

```csharp
using SWIFTFramework;
using SWIFTFramework.Messages.Category1;
using SWIFTFramework.Validation;

var parser = new SwiftParser(); // or SwiftParser.Instance
var errors = new List<ValidationError>();

SwiftMessage message = parser.GetMessage(rawSwiftText, errors);

if (errors.Count > 0)
{
    foreach (var error in errors)
        Console.WriteLine($"{error.Type}: {error.Description}");
}

MT103 mt103 = (MT103)message;
Console.WriteLine(mt103.SendersReference_20.Value);
Console.WriteLine(mt103.ValueDateCurrencyInterbankSettledAmount_32A.Amount);
Console.WriteLine(mt103.ValueDateCurrencyInterbankSettledAmount_32A.Currency);
Console.WriteLine(mt103.ValueDateCurrencyInterbankSettledAmount_32A.Date);
```

`GetMessage` returns a typed subclass (`MT103`, `MT202`, `MT300`, …) when the FIN type is recognized. Cast with `is` / `as` if the type is not known in advance:

```csharp
if (message is MT103 payment)
    Console.WriteLine(payment.BankOperationCode_23B.Value);
```

## Change fields and write SWIFT text

```csharp
mt103.Tag59_BeneficiaryCustomer.Value = "/1122334455";
mt103.ValueDateCurrencyInterbankSettledAmount_32A.Date = DateTime.Today;

string fin = parser.GetMessageAsText(mt103);
```

## Create a message from scratch

```csharp
using SWIFTFramework;
using SWIFTFramework.Messages.Category1;

var mt103 = new MT103();

mt103.Block1.ApplicationIdentifier = "F";
mt103.Block1.ServiceIdentifier = "01";
mt103.Block1.LTAddress = "BANKUSPPAXXX";
mt103.Block1.SessionNumber = "0000";
mt103.Block1.SequenceNumber = "000000";

mt103.Block2.MessageType = "103";
mt103.Block2.MessagePriority = "N";
((SwiftBlock2Input)mt103.Block2).DestinationAddress = "BANKUKZHAXXX";

mt103.SendersReference_20.Value = "ABCDEREF";
mt103.BankOperationCode_23B.Value = "CRED";
mt103.ValueDateCurrencyInterbankSettledAmount_32A.Amount = 14551m;
mt103.ValueDateCurrencyInterbankSettledAmount_32A.Currency = "USD";
mt103.ValueDateCurrencyInterbankSettledAmount_32A.Date = new DateTime(2026, 7, 24);
mt103.DetailsOfCharges_71A.Value = "SHA";

string fin = SwiftParser.Instance.GetMessageAsText(mt103);
```

See [creating-messages.md](creating-messages.md).

## Namespaces you will use

| Namespace | Purpose |
|---|---|
| `SWIFTFramework` | Parser, `SwiftMessage`, blocks, tags, `Licensing` |
| `SWIFTFramework.Messages.CategoryN` | Typed MT classes (`N` = 0–9, no space) |
| `SWIFTFramework.Validation` | `ValidationError`, `ValidationErrorType` |
| `SWIFTFramework.Definition` | Message/tag definitions (advanced) |

Folder names on disk are `Category 1`; C# namespaces are `Category1`.

## Common pitfalls

1. **License not set** — `LicenseException` on the first `new MT103()` or `GetMessage`.
2. **Wrong year/release key** — 2026.1 keys (`SWF-26-1x`) are rejected. Use a 2026.2 key (`SWF-26-2x`).
3. **Decimal separator** — SWIFT uses `,` not `.` (`USD14551,`). Prefer the typed `Amount` / `Currency` / `Date` properties.
4. **Input vs output Block 2** — outgoing messages use `SwiftBlock2Input` (`DestinationAddress`). Incoming/output copies use `SwiftBlock2Output`.
5. **Do not pass the generator prefix** — set only the hex groups, not `SWF-26-2x-SL-…`.
