Server method

What are server methods ?

Server methods are used to execute business code on the server-side. They can be exposed as an API.

Writing the code of a server method

In this article, we will focus on the available properties.

You can either write the C# code directly in the Neos Studio code editor or in Visual Studio (after the server method has been saved once). See more about adding/editing server code.

Method properties

Name : name of the server method, used to name the corresponding C# class and its interface.
Business assembly : business assembly that will contain the C# class representing the server method. The chosen assembly must belong to the server method module or one of its children.

Editing options :

Name : name of the server method, used to name the corresponding C# class and its interface.
Description : description of the server method

Advanced options :

Parameters and return type : lists the parameters that must be passed to the server method and its return type. Those informations are automatically deduced from the signature of the C# method in which your write the server method code. To add / update / delete a parameter or the return type, you just have to change the method signature. If the server method is exposed as an API, you can define how the parameters are passed to server method in the HTTP request.

API options :

Exposed as API : Indicates whether the server method will be available via the API.
Authentication required [only if exposed as API] : Indicates whether the user must be authenticated and authorized to execute the server method. If set to false, anonymous connections are allowed.
Internal use only [only if exposed as API] : Indicates whether the access to the server method REST API endpoint is restricted to local incoming addresses. If set to true, requests from external servers will not be allowed. This property is used to protect the method server from being called from outside the local network (in production, this is the Kubernetes namespace, which excludes calls from outside, but not inter-cluster communications). An example of use is a method server exposed by a Neos cluster that is needed by other clusters and is called by service invocation. For security reasons, if this method is not to be exposed to the outside world, it is recommended that it be restricted to the local network. And if this method is not subject to authentication and exposes sensitive or confidential data, it is essential to restrict it to the local network.
Display in API explorer [only if exposed as API] : Indicates whether the method server REST API endpoind is displayed in the documentation UI (e.g. Swagger UI). If set to false, method server REST API endpoint is ignored by the API explorer.
HTTP method [only if exposed as API] : GET / POST / PUT / DELETE. When using the GET verb, the server method cannot persist data.
Route [only if exposed as API] : Determines the route to use to call the server method API.

Complementary routes

A server method exposed as an API is reachable through its primary route (the HTTP method + Route from the API options above; when no Route is set, the implicit route is methods/<ServerMethodName>). You can expose the same server method through additional complementary routes. This lets you evolve an API — versioning, route-convention changes — without breaking already-integrated clients.

All routes of a server method invoke the same business code. Complementary routes are purely additive: the primary route keeps working unchanged.

Defining complementary routes

In Neos Studio, open the server method editor and use the routes button next to the Route field (its badge shows the number of complementary routes) to open the routes dialog. Each complementary route defines:

Route : the path of the additional endpoint.
HTTP method : the verb for this route. It can differ from the primary route's verb.
Authentication required / Internal use only / Display in API explorer : the same per-route options as the primary route (see the API options above).
Description : an optional summary shown for this route in the API documentation (Swagger / OpenAPI).
Deprecation : a route can be marked obsolete (see below).

Complementary routes are stored as ServerMethodRoutes/<ServerMethodName>.yml metadata.

Promoting a complementary route to the primary route

From the routes dialog, the Set as primary route action swaps a complementary route with the primary route: path, verb, options, description and deprecation are exchanged. This supports a progressive migration — add the new route, promote it to primary, then deprecate the former primary route (now a complementary route).

Deprecation strategy

A route marked obsolete keeps working but is reported as deprecated in the generated OpenAPI / Swagger documentation, signalling consumers to migrate. Evolution rules:

Adding a new route is backward compatible.
Modifying or removing an existing route is a breaking change for its consumers — prefer adding a new route and deprecating the old one.

Marking the server method itself obsolete deprecates all of its routes (primary and complementary) in the generated OpenAPI / Swagger documentation. A complementary route that also carries its own deprecation keeps its own message; otherwise it inherits the server method's deprecation.

Conflict detection

Two routes of the same server method must not resolve to the same HTTP method + path. This includes a complementary route colliding with the primary route, even the implicit methods/<ServerMethodName> one. Such conflicts are detected at generation time and fail the build.

Organizing server method files

Server method implementation files can be organized in subfolders within your business assembly project for better code organization. This is particularly useful when you have many server methods and want to group them by feature, domain area, or any logical structure.

File location flexibility

By default, Neos Studio creates server method files in a Methods/ folder (e.g., Methods/MyServerMethod.cs). However, you are free to organize these files in subfolders:

Application/
├── Methods/
│   ├── Orders/
│   │   ├── CreateOrder.cs
│   │   └── CancelOrder.cs
│   ├── Customers/
│   │   ├── RegisterCustomer.cs
│   │   └── UpdateCustomerProfile.cs
│   └── Billing/
│       └── ProcessPayment.cs

You can also place server method files outside the Methods/ folder entirely if it better suits your project structure.

Namespace reflection

The generated C# class namespace reflects the file path structure. For example:

File path	Generated namespace
`Methods/CreateOrder.cs`	`MyModule.Application.Methods.CreateOrder`
`Methods/Orders/CreateOrder.cs`	`MyModule.Application.Methods.Orders.CreateOrder`
`Methods/Orders/Export/ExportToExcel.cs`	`MyModule.Application.Methods.Orders.Export.ExportToExcel`
`CustomFolder/MyMethod.cs`	`MyModule.Application.CustomFolder.MyMethod`

Important

Folder names must be valid C# namespace identifiers. Avoid using special characters, spaces, or names that start with numbers.

Warning

The Neos code generator automatically determines the namespace based on the file's folder structure. If you manually move a server method file to a different folder, you must update the namespace in the C# file to match the new folder structure. If the namespace in your code doesn't match the folder path, the generated code will not compile.

For example, if you move Methods/CreateOrder.cs to Methods/Orders/CreateOrder.cs, you must update the namespace from MyModule.Application.Methods to MyModule.Application.Methods.Orders.

After moving or renaming a server method file, incremental generation in Neos Studio will fail. You must perform a full generation to rebuild the generated code correctly.

Handling duplicate file names

If multiple files with the same name exist in different locations (e.g., Methods/CreateOrder.cs and Methods/Orders/CreateOrder.cs), Neos applies a deterministic resolution strategy:

Default path: If the file exists in the default location Methods/<Name>.cs, it takes precedence
Shortest path: Otherwise, the file with the shortest relative path is selected
Alphabetical order: If paths have equal length, the first path alphabetically is chosen

Caution

Having duplicate file names is not recommended and may lead to confusion. It's best to use unique names or ensure they are in clearly separate contexts.

Calling the server method from the client

The ServerMethods property is available on the client-side. It lists all the available server methods exposed in the API :

CopyOrderResult result = await ServerMethods.CopyOrder.ExecuteAsync(orderId);
await ShowMessageAsync(
    MessageType.Info,
    GroupeIsa.Northwind.Domain.Properties.Resources.Sales.OrderCopy,
    string.Format(GroupeIsa.Northwind.Domain.Properties.Resources.Sales.OrderCreated, result.OrderId));

Before calling a server method, client code can check whether the current user is allowed to execute it with ServerMethods.{ServerMethodName}.IsAllowed(). This lets the client avoid triggering the API call when the user does not have access, preventing an expected 403 Forbidden response:

if (ServerMethods.CopyOrder.IsAllowed())
{
    CopyOrderResult result = await ServerMethods.CopyOrder.ExecuteAsync(orderId);
}

Table of Contents