.NET Service Contracts

Introduction

Service contracts are a foundational concept in building distributed systems and service-oriented applications in the .NET ecosystem. They define the agreement between a service provider and its consumers, specifying what operations a service can perform and how clients should interact with it.

In this guide, you'll learn what service contracts are, how they're implemented in .NET, and why they're crucial for building robust, maintainable service-oriented applications. Whether you're creating a Web API, WCF service, or gRPC service, understanding service contracts will help you design better interfaces between your applications.

What Are Service Contracts?

A service contract is essentially a formal agreement that defines:

What operations a service provides
What data formats these operations accept and return
How clients should interact with the service
What exceptions or errors might occur

In .NET, service contracts are typically defined using interfaces decorated with special attributes that provide metadata about the service.

Service Contracts in Different .NET Technologies

Service contracts can be implemented in several ways depending on which .NET technology you're using:

1. WCF (Windows Communication Foundation)

In WCF, service contracts are explicitly defined using the ServiceContract and OperationContract attributes.

2. ASP.NET Web API

Web API uses model classes and controller methods to implicitly define contracts.

3. gRPC

gRPC uses Protocol Buffers (protobuf) to define service contracts.

Let's explore each of these approaches.

Implementing Service Contracts in WCF

Although WCF is considered legacy technology in .NET Core and .NET 5+, understanding its contract model provides a good foundation for service-oriented design principles.

Basic WCF Service Contract

csharp
using System.ServiceModel;

[ServiceContract]
public interface ICalculatorService
{
    [OperationContract]
    double Add(double a, double b);
    
    [OperationContract]
    double Subtract(double a, double b);
    
    [OperationContract]
    double Multiply(double a, double b);
    
    [OperationContract]
    double Divide(double a, double b);
}

Implementing the Contract

csharp
public class CalculatorService : ICalculatorService
{
    public double Add(double a, double b)
    {
        return a + b;
    }
    
    public double Subtract(double a, double b)
    {
        return a - b;
    }
    
    public double Multiply(double a, double b)
    {
        return a * b;
    }
    
    public double Divide(double a, double b)
    {
        if (b == 0)
            throw new DivideByZeroException("Cannot divide by zero.");
        return a / b;
    }
}

Data Contracts in WCF

When you need to exchange complex data types, you use the DataContract and DataMember attributes:

csharp
[DataContract]
public class Person
{
    [DataMember]
    public string Name { get; set; }
    
    [DataMember]
    public int Age { get; set; }
    
    // This property won't be serialized since it lacks the DataMember attribute
    public string Address { get; set; }
}

[ServiceContract]
public interface IPersonService
{
    [OperationContract]
    void AddPerson(Person person);
    
    [OperationContract]
    Person GetPerson(int id);
}

Service Contracts in ASP.NET Web API

In ASP.NET Web API, service contracts are more implicit. They're defined by the HTTP methods and routes in your controllers.

Example Web API Controller

csharp
using Microsoft.AspNetCore.Mvc;
using System.Collections.Generic;

[ApiController]
[Route("api/[controller]")]
public class BooksController : ControllerBase
{
    private static List<Book> _books = new List<Book>
    {
        new Book { Id = 1, Title = "Clean Code", Author = "Robert C. Martin" },
        new Book { Id = 2, Title = "Design Patterns", Author = "Gang of Four" }
    };

    // GET api/books
    [HttpGet]
    public ActionResult<IEnumerable<Book>> GetBooks()
    {
        return _books;
    }

    // GET api/books/1
    [HttpGet("{id}")]
    public ActionResult<Book> GetBook(int id)
    {
        var book = _books.Find(b => b.Id == id);
        
        if (book == null)
            return NotFound();
            
        return book;
    }

    // POST api/books
    [HttpPost]
    public ActionResult<Book> PostBook(Book book)
    {
        book.Id = _books.Count + 1;
        _books.Add(book);
        
        return CreatedAtAction(nameof(GetBook), new { id = book.Id }, book);
    }
}

public class Book
{
    public int Id { get; set; }
    public string Title { get; set; }
    public string Author { get; set; }
}

In this example, the contract is defined by:

The HTTP methods (GET, POST)
The routes (api/books, api/books/{id})
The request and response data types (Book, IEnumerable<Book>)
The status codes returned (200 OK, 201 Created, 404 Not Found)

Open API/Swagger Definition

Modern Web APIs often use Swagger/OpenAPI to formally document the service contract. In ASP.NET Core, you can add this with minimal configuration:

csharp
// In ConfigureServices
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

// In Configure
app.UseSwagger();
app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API v1"));

This generates a comprehensive API documentation that serves as a service contract for API consumers.

Service Contracts in gRPC

gRPC uses Protocol Buffers (protobuf) for defining service contracts. Here's an example:

protobuf
syntax = "proto3";

option csharp_namespace = "GrpcService";

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

The corresponding C# implementation would look like:

csharp
public class GreeterService : Greeter.GreeterBase
{
    public override Task<HelloReply> SayHello(HelloRequest request, ServerCallContext context)
    {
        return Task.FromResult(new HelloReply
        {
            Message = "Hello " + request.Name
        });
    }
}

Best Practices for Designing Service Contracts

Design for Evolution: Services change over time. Design contracts that can evolve without breaking existing clients.
Keep It Simple: Don't expose more operations or data than necessary.
Use Clear Naming: Method and parameter names should be self-explanatory.
Document Everything: Add XML comments to describe what each operation does.
Versioning Strategy: Plan for versioning from the start (URL paths, headers, etc.).
Validate Input: Clearly define what constitutes valid input and handle validation thoroughly.
Error Handling: Define error responses and codes as part of your contract.

Real-World Example: E-Commerce Order Service

Let's design a simple service contract for an e-commerce order system:

csharp
[ServiceContract]
public interface IOrderService
{
    [OperationContract]
    OrderResponse CreateOrder(OrderRequest order);
    
    [OperationContract]
    OrderStatus GetOrderStatus(string orderId);
    
    [OperationContract]
    bool CancelOrder(string orderId, string reason);
    
    [OperationContract]
    IEnumerable<Order> GetOrdersForCustomer(string customerId);
}

[DataContract]
public class OrderRequest
{
    [DataMember]
    public string CustomerId { get; set; }
    
    [DataMember]
    public List<OrderItem> Items { get; set; }
    
    [DataMember]
    public string ShippingAddress { get; set; }
    
    [DataMember]
    public PaymentInfo Payment { get; set; }
}

[DataContract]
public class OrderResponse
{
    [DataMember]
    public string OrderId { get; set; }
    
    [DataMember]
    public bool Success { get; set; }
    
    [DataMember]
    public string ErrorMessage { get; set; }
    
    [DataMember]
    public decimal TotalAmount { get; set; }
    
    [DataMember]
    public DateTime EstimatedDelivery { get; set; }
}

// Additional classes would be defined for OrderItem, PaymentInfo, etc.

This contract clearly defines what data is needed to create an order and what information is returned. It provides operations for the full lifecycle of an order (create, check status, cancel).

Implementing This in ASP.NET Core Web API

csharp
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
    private readonly IOrderService _orderService;
    
    public OrdersController(IOrderService orderService)
    {
        _orderService = orderService;
    }
    
    [HttpPost]
    public ActionResult<OrderResponse> CreateOrder(OrderRequest orderRequest)
    {
        var response = _orderService.CreateOrder(orderRequest);
        
        if (!response.Success)
            return BadRequest(response);
            
        return CreatedAtAction(nameof(GetOrderStatus), new { orderId = response.OrderId }, response);
    }
    
    [HttpGet("{orderId}")]
    public ActionResult<OrderStatus> GetOrderStatus(string orderId)
    {
        var status = _orderService.GetOrderStatus(orderId);
        
        if (status == null)
            return NotFound();
            
        return status;
    }
    
    [HttpDelete("{orderId}")]
    public IActionResult CancelOrder(string orderId, [FromQuery] string reason)
    {
        var success = _orderService.CancelOrder(orderId, reason);
        
        if (!success)
            return NotFound();
            
        return NoContent();
    }
    
    [HttpGet("customer/{customerId}")]
    public ActionResult<IEnumerable<Order>> GetOrdersForCustomer(string customerId)
    {
        var orders = _orderService.GetOrdersForCustomer(customerId);
        return Ok(orders);
    }
}

Summary

Service contracts are a critical part of building distributed systems in .NET. They define the agreement between services and their consumers, promoting loose coupling and ensuring clear communication between different parts of your system.

Key takeaways:

Service contracts define what operations a service provides and how to interact with it
In WCF, contracts are explicitly defined with attributes
In Web API, contracts are defined through HTTP methods, routes, and data models
gRPC uses Protocol Buffers for strongly-typed contracts
Well-designed contracts should be simple, evolvable, and well-documented

By mastering service contracts, you'll be able to design more robust and maintainable service-oriented applications that can evolve over time without breaking existing integrations.

Additional Resources

Microsoft Docs: WCF Service Contracts
ASP.NET Core Web API Documentation
gRPC Services with .NET
Book: "REST in Practice" by Jim Webber, Savas Parastatidis, and Ian Robinson

Exercises

Design a service contract for a basic banking system that supports account creation, deposits, withdrawals, and balance inquiries.
Convert a WCF-style contract to an equivalent ASP.NET Core Web API controller.
Create a gRPC service contract for a notification system that can send messages to users via different channels (email, SMS, push).
Add OpenAPI/Swagger documentation to an existing Web API.
Implement versioning for a service contract to support both v1 and v2 of an API without breaking existing clients.

If you spot any mistakes on this website, please let me know at feedback@compilenrun.com. I’d greatly appreciate your feedback! :)

Introduction​

What Are Service Contracts?​

Service Contracts in Different .NET Technologies​

1. WCF (Windows Communication Foundation)​

2. ASP.NET Web API​

3. gRPC​

Implementing Service Contracts in WCF​

Basic WCF Service Contract​

Implementing the Contract​

Data Contracts in WCF​

Service Contracts in ASP.NET Web API​

Example Web API Controller​

Open API/Swagger Definition​

Service Contracts in gRPC​

Best Practices for Designing Service Contracts​

Real-World Example: E-Commerce Order Service​

Implementing This in ASP.NET Core Web API​

Summary​

Additional Resources​

Exercises​