咨询：NSwag.MSBuild生成单个C#客户端类/接口的缺失配置

Problem Description #

I've noticed an odd discrepancy: when generating C# client code via NSwagStudio (without file output), it creates a single client class (and corresponding interface) that includes all controller methods. But when I run the same generation using NSwag.MSBuild, it produces separate partial classes/interfaces for each controller.

Here's my current nswag.json configuration:

{
  "openApiToCSharpClient": {
    "clientBaseClass": "BillingBaseClient",
    "configurationClass": "ConnectionOptions",
    "generateClientClasses": true,
    "generateClientInterfaces": true,
    "clientBaseInterface": null,
    "injectHttpClient": true,
    "disposeHttpClient": true,
    "protectedMethods": [ ],
    "generateExceptionClasses": true,
    "exceptionClass": "ApiException",
    "wrapDtoExceptions": true,
    "useHttpClientCreationMethod": false,
    "httpClientType": "System.Net.Http.HttpClient",
    "useHttpRequestMessageCreationMethod": true,
    "useBaseUrl": true,
    "generateBaseUrlProperty": false,
    "generateSyncMethods": false,
    "exposeJsonSerializerSettings": false,
    "clientClassAccessModifier": "public",
    "typeAccessModifier": "public",
    "generateContractsOutput": false,
    "contractsNamespace": null,
    "contractsOutputFilePath": null,
    "parameterDateTimeFormat": "s",
    "parameterDateFormat": "yyyy-MM-dd",
    "generateUpdateJsonSerializerSettingsMethod": true,
    "useRequestAndResponseSerializationSettings": false,
    "serializeTypeInformation": false,
    "queryNullValue": "",
    "className": "BillingClient",
    "operationGenerationMode": "MultipleClientsFromOperationId",
    "additionalNamespaceUsages": [ ],
    "additionalContractNamespaceUsages": [ ],
    "generateOptionalParameters": true,
    "generateJsonMethods": true,
    "enforceFlagEnums": false,
    "parameterArrayType": "System.Collections.Generic.IEnumerable",
    "parameterDictionaryType": "System.Collections.Generic.IDictionary",
    "responseArrayType": "System.Collections.Generic.ICollection",
    "responseDictionaryType": "System.Collections.Generic.IDictionary",
    "wrapResponses": false,
    "wrapResponseMethods": [ ],
    "generateResponseClasses": true,
    "responseClass": "SwaggerResponse",
    "namespace": "ServiceTitan.Billing.Api.Client",
    "requiredPropertiesMustBeDefined": true,
    "dateType": "System.DateTimeOffset",
    "jsonConverters": null,
    "anyType": "object",
    "dateTimeType": "System.DateTimeOffset",
    "timeType": "System.TimeSpan",
    "timeSpanType": "System.TimeSpan",
    "arrayType": "System.Collections.Generic.ICollection",
    "arrayInstanceType": "System.Collections.ObjectModel.Collection",
    "dictionaryType": "System.Collections.Generic.IDictionary",
    "dictionaryInstanceType": "System.Collections.Generic.Dictionary",
    "arrayBaseType": "System.Collections.ObjectModel.Collection",
    "dictionaryBaseType": "System.Collections.Generic.Dictionary",
    "classStyle": "Poco",
    "generateDefaultValues": true,
    "generateDataAnnotations": true,
    "excludedTypeNames": [ ],
    "excludedParameterNames": [ ],
    "handleReferences": false,
    "generateImmutableArrayProperties": false,
    "generateImmutableDictionaryProperties": false,
    "jsonSerializerSettingsTransformationMethod": null,
    "inlineNamedArrays": false,
    "inlineNamedDictionaries": false,
    "inlineNamedTuples": true,
    "inlineNamedAny": false,
    "generateDtoTypes": true,
    "generateOptionalPropertiesAsNullable": false,
    "templateDirectory": null,
    "typeNameGeneratorType": null,
    "propertyNameGeneratorType": null,
    "enumNameGeneratorType": null,
    "serviceHost": null,
    "serviceSchemes": null,
    "output": "BillingClient.g.cs"
  }
}

What configuration setting do I need to adjust to get NSwag.MSBuild to generate a single client class/interface instead?

Solution #

Oh, I know exactly what's causing this! The issue lies in the operationGenerationMode setting in your config. Right now you have it set to "MultipleClientsFromOperationId"—this mode splits the client into partial classes based on the operation IDs (which typically map to different controllers).

To generate a single unified client class, you need to change this value to either "SingleClient" or "SingleClientFromOperationId":

• "SingleClient": All API operations are generated into the same client class, regardless of how your operation IDs are structured. This is the simplest option if you just want one big client.
• "SingleClientFromOperationId": This still merges everything into a single client but respects the namespace/structure of your operation IDs (useful if you have grouped operations but want them all in one class).

Here's the adjusted key part of your config:

{
  "openApiToCSharpClient": {
    // ... keep all your existing config settings
    "className": "BillingClient",
    "operationGenerationMode": "SingleClient", // This is the line you need to change
    // ... keep all your existing config settings
  }
}

As for why NSwagStudio and MSBuild behave differently? Chances are you had the single client mode selected in NSwagStudio's UI, but when exporting the config, that setting wasn't properly carried over—or maybe the MSBuild tool uses a different default for this parameter.

After making this change, re-run your NSwag.MSBuild task, and you should get a single BillingClient class (and matching interface) that contains all your controller methods, no more separate partial classes!

内容的提问来源于stack exchange，提问作者Grigoryants Artem