Legacy systems & integrations

#SOAP, WSDL and XML: start with the contract

A modern store may still need an older invoicing service. SOAP is an XML messaging protocol, not simply any XML sent over HTTP. Messages contain an Envelope, an optional Header, and a Body holding an operation or Fault. WSDL describes operations, messages, bindings and endpoints; XSD defines data types.

<!-- (1) SOAP 1.1 envelope namespace -->
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body>
    <!-- (2) Operation namespace belongs to the service contract -->
    <GetInvoice xmlns="urn:store:invoices">
      <invoiceId>42</invoiceId>
    </GetInvoice>
  </s:Body>
</s:Envelope>

Choose a binding matching the WSDL. SOAP is not restricted to HTTP, and WS-Security is distinct from TLS. Preserve an existing contract when consumers depend on it; REST and gRPC are not wire-compatible replacements.

#Consuming SOAP from .NET 10

Generate a proxy from a trusted WSDL using dotnet-svcutil or Visual Studio's WCF Web Service Reference instead of assembling XML manually. The tool adds suitable System.ServiceModel packages, such as System.ServiceModel.Http and System.ServiceModel.Primitives. These provide client support, not the original WCF server.

dotnet tool install --global dotnet-svcutil
# (1) Local, reviewed WSDL and its imported schemas
dotnet-svcutil ./contracts/invoices.wsdl
dotnet restore

using System.ServiceModel;

// (2) Generated names depend on your WSDL.
var binding = new BasicHttpsBinding
{
    SendTimeout = TimeSpan.FromSeconds(15),
    MaxReceivedMessageSize = 1_000_000
};
var endpoint = new EndpointAddress("https://partner.example/Invoices.svc");
var client = new InvoiceServiceClient(binding, endpoint);
try
{
    var result = await client.GetInvoiceAsync(42); // (3)
    client.Close();
}
catch
{
    client.Abort(); // (4)
    throw;
}

Source: Microsoft's WCF client generation guide.

#An anti-corruption layer at the boundary

If a partner calls a status X9, that should not become a domain concept everywhere. An adapter translates interfaces; an anti-corruption layer also translates meaning: currencies, quantity units, time zones and failures.

public record InvoiceStatus(bool Paid);
public record LegacyInvoice(string StateCode);
public interface ILegacyInvoices
{
    Task<LegacyInvoice> FetchAsync(int id, CancellationToken ct);
}
public interface IInvoiceStatus
{
    Task<InvoiceStatus> GetAsync(int id, CancellationToken ct);
}
public sealed class InvoiceAdapter(ILegacyInvoices legacy) : IInvoiceStatus
{
    public async Task<InvoiceStatus> GetAsync(int id, CancellationToken ct)
    {
        var dto = await legacy.FetchAsync(id, ct); // (1)
        return dto.StateCode switch // (2)
        {
            "X9" => new(true),
            "N0" => new(false),
            _ => throw new InvalidDataException("Unknown invoice state")
        };
    }
}

Cover mapping with contract tests and log correlation IDs without sensitive payloads. This boundary adds code; avoid layers of forwarding when models already match and the integration is simple.

#Moving a WCF server: CoreWCF or gRPC?

Changing the target framework does not bring the original WCF server to .NET 10. If existing SOAP clients must remain, evaluate CoreWCF and test required bindings, security and behaviors. If all consumers can change, gRPC is an option for a new contract, requiring regenerated clients and a different wire protocol.

Prototype one operation with the hardest security requirement first. Separate runtime migration from wholesale contract redesign. A SOAP facade can remain over a new implementation while clients migrate.

#Strangler fig with YARP: migrate route by route

A complete rewrite delays feedback and concentrates risk. Put one entry point in front of old and new systems, then move complete features gradually. Here ASP.NET Core serves migrated routes locally, and YARP forwards everything else to the legacy application.

// Package: Yarp.ReverseProxy; configuration shown below.
builder.Services.AddReverseProxy()
    .LoadFromConfig(builder.Configuration.GetSection("ReverseProxy")); // (1)
var app = builder.Build();
app.MapGet("/products/{id:int}", (int id) => new { Id = id }); // (2)
app.MapReverseProxy(); // (3)
app.Run();

{
  "ReverseProxy": {
    "Routes": {
      "fallback": {
        "ClusterId": "legacy",
        "Order": 1000,
        "Match": { "Path": "{**catch-all}" }
      }
    },
    "Clusters": {
      "legacy": {
        "Destinations": {
          "primary": { "Address": "https://legacy.example/" }
        }
      }
    }
  }
}

Define data write ownership, compatible schemas, cookies, sessions, authentication and rollback. Shadow reads can compare behavior; shadow writes must not charge twice. Monitor remaining legacy traffic and define retirement criteria.

Source: Incremental ASP.NET migration.

#A verifiable .NET Framework to .NET 10 migration

1. Inventory dependencies, Windows-specific APIs and integration contracts; baseline failures and performance.
2. Capture current behavior with characterization tests, and choose a valuable small slice with rollback.
3. Upgrade leaf libraries required by that slice first. netstandard2.0 bridges shared libraries to Framework; it is not a runtime. Framework 4.7.2 or later is preferable in practice to avoid older compatibility problems. Framework does not support netstandard2.1.
4. Replace hosting and configuration boundaries, then validate end-to-end behavior, deployment and load before shifting traffic.

#Characterization tests and seams

Before refactoring, establish what the code actually does, including surprising behavior. A characterization test captures current behavior; a seam lets you substitute a dependency such as a clock or API without changing the business logic.

// TimeProvider is the seam; this example captures an existing date rule.
public sealed class InvoiceDates(TimeProvider clock)
{
    public DateOnly Today() =>
        DateOnly.FromDateTime(clock.GetUtcNow().UtcDateTime); // (1)
}
public sealed class FixedClock : TimeProvider
{
    public override DateTimeOffset GetUtcNow() =>
        new(2026, 10, 22, 0, 0, 0, TimeSpan.Zero);
}

[Fact]
public void PreservesUtcInvoiceDate()
{
    var dates = new InvoiceDates(new FixedClock()); // (2)
    Assert.Equal(new DateOnly(2026, 10, 22), dates.Today());
}

For golden masters, normalize only nondeterministic fields such as generated IDs, never meaningful differences. Record incorrect behavior explicitly and fix it as a separate agreed change; characterization does not permanently endorse a bug.

#Reliable integration: outbox, idempotency and reconciliation

Saving an order and sending a message are separate operations: the process can crash between them. Store the order and an outbox row in the same local transaction, then dispatch later. Delivery can repeat if the process crashes after sending but before marking success.

(1) Transaction: save Order + Outbox(MessageId, OrderId, Version, Payload)
(2) Dispatcher: lease pending row, send with stable MessageId, record success
(3) Receiver transaction: unique Inbox(MessageId) + apply business update
(4) Reconciliation: compare by business key, version, amount and currency

An outbox provides neither exactly-once delivery nor a distributed transaction. If the partner cannot deduplicate, a timeout is an unknown outcome: query status or reconcile rather than retry blindly. Monitor oldest-message age, retries and stuck messages.

#CSV, SFTP and batch processing

Not every partner exposes an API. Agree a file contract covering encoding, delimiters, quoted fields, schema version, time zone, business keys, row counts and checksums. SFTP transfers over SSH; it differs from FTPS, which uses TLS.

1. Verify the SSH host key, upload under a temporary name, then use an agreed rename or completion marker.
2. Register the file ID and checksum, stage and validate records, and quarantine rejected rows with reasons and line numbers.
3. Apply small batches with unique business keys and durable checkpoints. Record progress after commit; a crash before checkpointing requires safe replay.
4. Return accepted and rejected counts and reconcile totals. Specify partial acceptance versus whole-file atomicity.

File: invoices-20261022-v1.csv
FileId: stable partner batch identifier
Staging: FileId + RowNumber + BusinessKey + ValidationStatus
Checkpoint: FileId + LastCommittedBatch
Result: accepted count + rejected count + totals by currency

Do not treat Split(',') as a general CSV parser: quoted fields can contain commas and newlines. Streaming limits loaded rows, but a HashSet of every key may still exhaust memory. Use database staging or external sorting when needed.

BackgroundService hosts a worker but is not a durable scheduler by itself. Hangfire, Quartz.NET or an external scheduler can manage schedules according to their configuration, but jobs still need idempotency. Define overlap protection across instances, misfires, daylight saving behavior, cancellation, retries and missed-run alerts. Do not launch critical jobs with Task.Run inside requests.