Configuration Options

OmniSharp exposes a set of configuration options that can be used to modify the behavior of OmniSharp regarding:

• project system options (project.json projects, MSBuild projects, CSX projects)
• code formatting options
• Roslyn extensions options
• file options (used to explicitly define which folders and files OmniSharp should exclude from its scanning)

At startup, OmniSharp obtains the configuration options using the following (hierarchical) order:

• its own hardcoded defaults
• Environment variables
• Command line arguments
• An omnisharp.json file located in %USERPROFILE%/.omnisharp/
• An omnisharp.json file located in the working directory which OmniSharp has been pointed at

Each of the configuration sources, can overwrite any of the settings set by the previous source.

Configuration sections

All the possible configuration options (with their default values) are defined below.

Project system options

Each project system deals with different types of projects and can be disabled if you wish to only focus on specific features and don't need anything else.

MSBuild

Used to configure MSBuild solutions and projects.

{
  "msbuild": {
     "enabled": true,
     "ToolsVersion": null,
     "VisualStudioVersion": null,
     "Configuration": null,
     "Platform": null,
     "EnablePackageAutoRestore" : false,
     "MSBuildExtensionsPath": null,
     "TargetFrameworkRootPath" : null,
     "MSBuildSDKsPath": null,
     "RoslynTargetsPath" : null,
     "CscToolPath": null,
     "CscToolExe": null
  }
}

DotNet

Used to configure legacy project.json-based projects.

{
  "dotnet": {
     "enabled": true
  }
}

Scripting

Used to configure C# scripting (CSX files).

{
  "script": {
     "enabled": true,
     "defaultTargetFramework": "net461",
     "enableScriptNuGetReferences": false
  }
}

Formatting options

Used to control C# formatting.

{
  "FormattingOptions": {
    "NewLine": "\n",
    "UseTabs": false,
    "TabSize": 4,
    "IndentationSize": 4,
    "SpacingAfterMethodDeclarationName": false,
    "SpaceWithinMethodDeclarationParenthesis": false,
    "SpaceBetweenEmptyMethodDeclarationParentheses": false,
    "SpaceAfterMethodCallName": false,
    "SpaceWithinMethodCallParentheses": false,
    "SpaceBetweenEmptyMethodCallParentheses": false,
    "SpaceAfterControlFlowStatementKeyword": true,
    "SpaceWithinExpressionParentheses": false,
    "SpaceWithinCastParentheses": false,
    "SpaceWithinOtherParentheses": false,
    "SpaceAfterCast": false,
    "SpacesIgnoreAroundVariableDeclaration": false,
    "SpaceBeforeOpenSquareBracket": false,
    "SpaceBetweenEmptySquareBrackets": false,
    "SpaceWithinSquareBrackets": false,
    "SpaceAfterColonInBaseTypeDeclaration": true,
    "SpaceAfterComma": true,
    "SpaceAfterDot": false,
    "SpaceAfterSemicolonsInForStatement": true,
    "SpaceBeforeColonInBaseTypeDeclaration": true,
    "SpaceBeforeComma": false,
    "SpaceBeforeDot": false,
    "SpaceBeforeSemicolonsInForStatement": false,
    "SpacingAroundBinaryOperator": "single",
    "IndentBraces": false,
    "IndentBlock": true,
    "IndentSwitchSection": true,
    "IndentSwitchCaseSection": true,
    "LabelPositioning": "oneLess",
    "WrappingPreserveSingleLine": true,
    "WrappingKeepStatementsOnSingleLine": true,
    "NewLinesForBracesInTypes": true,
    "NewLinesForBracesInMethods": true,
    "NewLinesForBracesInProperties": true,
    "NewLinesForBracesInAccessors": true,
    "NewLinesForBracesInAnonymousMethods": true,
    "NewLinesForBracesInControlBlocks": true,
    "NewLinesForBracesInAnonymousTypes": true,
    "NewLinesForBracesInObjectCollectionArrayInitializers": true,
    "NewLinesForBracesInLambdaExpressionBody": true,
    "NewLineForElse": true,
    "NewLineForCatch": true,
    "NewLineForFinally": true,
    "NewLineForMembersInObjectInit": true,
    "NewLineForMembersInAnonymousTypes": true,
    "NewLineForClausesInQuery": true
  }
}

Roslyn extensions options

Used to define code actions locations (refactorings) that OmniSharp should use (i.e. Roslynator).

{
  "locationPaths": [
     "//path_to/code_actions.dll"
  ]
}

File options

Used to define which directories and files should not be included in OmniSharp's file scanning/discovery process.

{
  "fileOptions": {
    "systemExcludeSearchPatterns": [
      "**/node_modules/**/*",
      "**/bin/**/*",
      "**/obj/**/*",
      "**/node_modules/**/*"
    ],
    "userExcludeSearchPatterns": []
  }
}

Overriding the configuration

Environment variables

Environment variables should be passed into the OmniSharp process as flattened JSON paths. Instead of ., : should be used as a delimiter. Environment variables must be prefixed with OMNISHARP_.

Example

To override the default formattingOptions > tabSize setting of config.json (4) with 2, you should set environment variable OMNISHARP_formattingOptions:tabSize with the value 2.

Command line arguments

Command line arguments are parsed by OmniSharp after environment variables. Their format is the same as environment variables - flattened JSON paths, with : as a delimiter. Additionally, the do not require any prefix - neither -, nor --.

Example

To override the default formattingOptions > tabSize setting of config.json (4), or anything set by environment variables, with 2, you should launch OmniSharp with the following command:

OmniSharp.exe -s {folder path} {other arguments} formattingOptions:tabSize=2

Global omnisharp.json

Next in order is a global omnisharp.json located at %USERPROFILE%/.omnisharp/omnisharp.json. This doesn't need to be a full copy of config.json - it can contain only individual settings, and they will be merged into the settings provided by config.json, environment variables and command line args, and simply overwrite the matching ones. It's worth noting that,the file is not automatically created by OmniSharp - only its containing folder is. So if you can't find omnisharp.json inside %USERPROFILE%/.omnisharp, create it manually.

Example

To override the default formattingOptions > tabSize setting of config.json (4), or anything set by environment variables/command line args with 2, you should create the following omnisharp.json file at %USERPROFILE%/.omnisharp/omnisharp.json:

{
    "formattingOptions": {
        "tabSize": 2
    }
}

Because the global omnisharp.json is picked up any time OmniSharp starts, regardless of the folder you point OmniSharp at, a global configuration file is the best option for any settings you want to automatically apply to all your projects (machine-wide settings).

Local omnisharp.json

The highest order of precedence is given to omnisharp.json located in the folder which OmniSharp server is looking at. Just like it's the case for the global omnisharp.json - you can use it to overwrite the relevant configuration keys.

While a global omnisharp.json is relevant for machine-wide settings, a local omnisharp.json is suitable for project-specific settings.