Skip to content
API Contracts

ICustomerService

Interface public
Defines the contract for managing customer lifecycle operations including creation, retrieval, search, update, and deactivation.
Namespace SampleApi
Assembly SampleApi
Package v1.0.0.0

Definition

Section titled Definition 
public interface ICustomerService

Remarks

Section titled Remarks
Implementations of ICustomerService are responsible for enforcing business rules such as email uniqueness, required-field validation, and the invariant that deactivated customers cannot place new orders. All methods are asynchronous and return Task`1 to support non-blocking I/O against the underlying data store. Callers should handle null returns from Guid) gracefully, as a missing customer is a normal condition rather than an error.

Methods5

Section titled Methods
CreateAsync Section titled CreateAsync abstract
Task<Customer> 
Task<Customer> ICustomerService.CreateAsync(
    Customer customer)

Persists a new Customer and returns the created entity with any server-generated values (e.g., timestamps) populated.

Parameters
customer Customer
The customer to create. The Id and FullName properties are required.
Returns
Task<Customer> A Task`1 that resolves to the newly created Customer with CreatedAt set by the server.
Examples
var customer = new Customer
{
    Id = Guid.NewGuid(),
    FullName = "Alice Smith",
    Email = "alice@example.com",
    Tags = ["premium"]
};
var created = await service.CreateAsync(customer);
Console.WriteLine($"Created {created.FullName} at {created.CreatedAt}");
DeactivateAsync Section titled DeactivateAsync abstract
Task<bool> 
Task<bool> ICustomerService.DeactivateAsync(
    Guid id)

Marks a customer as inactive, preventing them from placing new orders or appearing in search results.

Parameters
id Guid
The identifier of the customer to deactivate.
Returns
Task<bool> true if the customer was found and successfully deactivated; false if no customer with the given id exists or the customer was already inactive.
Remarks
Deactivation is a soft operation\u2014the customer record is retained in the data store with IsActive set to false. This method is idempotent: calling it on an already-inactive customer returns false without side effects.
GetByIdAsync Section titled GetByIdAsync abstract
Task<Customer?> 
Task<Customer?> ICustomerService.GetByIdAsync(
    Guid id)

Retrieves a single customer by its globally unique identifier.

Parameters
id Guid
The Guid identifier of the customer to retrieve.
Returns
Task<Customer?> The Customer if a record with the specified id exists; otherwise, null.
Remarks
This method does not throw when the customer is not found. Callers should check for a null result and return an appropriate HTTP 404 or equivalent response.
SearchAsync Section titled SearchAsync abstract
Task<IReadOnlyList<Customer>> 
Task<IReadOnlyList<Customer>> ICustomerService.SearchAsync(
    string query,
    int skip = 0,
    int take = 25)

Searches for customers whose FullName or Email matches the given query string, with support for offset-based pagination.

Parameters
query string
A case-insensitive search string. The implementation performs a contains-style match against FullName and Email.
skip int optional
The number of matching results to skip, enabling offset-based pagination. Defaults to 0.
take int optional
The maximum number of results to return per page. Defaults to 25. Values above 100 may be clamped by the implementation.
Returns
Task<IReadOnlyList<Customer>> A read-only list of customers matching the search criteria, ordered by FullName ascending. Returns an empty list when no matches are found.
Examples

Paginated search for customers containing "contoso":

var page1 = await service.SearchAsync("contoso", skip: 0, take: 10);
var page2 = await service.SearchAsync("contoso", skip: 10, take: 10);
UpdateAsync Section titled UpdateAsync abstract
Task<Customer> 
Task<Customer> ICustomerService.UpdateAsync(
    Customer customer)

Replaces the stored customer record with the values from the supplied customer object.

Parameters
customer Customer
The customer entity containing the updated values. The Id must match an existing record.
Returns
Task<Customer> The updated Customer as persisted, which may include server-modified fields such as an updated timestamp.

Examples

Section titled Examples

Registering a new customer and immediately retrieving it:

ICustomerService service = GetService();


var customer = new Customer
{
    Id = Guid.NewGuid(),
    FullName = "Contoso Ltd.",
    Email = "info@contoso.com"
};


var created = await service.CreateAsync(customer);
var fetched = await service.GetByIdAsync(created.Id);

See Also

Section titled See Also
Customer Order