.Net and Asp.Net on MacOs & Mono instead of Windows (using Visual Studio or JetBrains Rider)

Mono goes a long way in running code written for .Net on Windows. It is all very much easier if you either start with cross-platform in mind, or if you move to .Net Core; but even for existing .Net Framework projects mono can run runs most things including Asp.Net.

Here's my checklist from a couple of years of opening .Net Framework solution files on a Mac and finding they don't build first time.

Most of these require you to edit the .csproj file to make it cross-platform, so a basic grasp of msbuild is very helpful.

  1. For AspNet: inside the PropertyGroup section near the top of the csproj file, add an element:

    <WebProjectOutputDir Condition="$(WebProjectOutputDir) == '' AND $(OS) == 'Unix' ">bin/</WebProjectOutputDir>

    Use this if you get a 'The “KillProcess” task was not given a value for the required parameter “ImagePath” (MSB4044)' error message; or if the build output shows you are trying to create files in an top-level absolute /bin/ path.

  2. For AspNet: Add Condition="'$OS'!='Unix'" to the reference to Microsoft.Web.Infrastructure.dll AND delete the file from the website bin directory.

    <Reference Condition="'$OS'!='Unix'" Include="Microsoft.Web.Infrastructure, Version=, Culture=neutral, PublicKeyToken=31bf3856ad364e35, processorArchitecture=MSIL">
  3. For all project types—but, only if you need to use the netCore dotnet build tooling to build an NetFramework project on unix. mono's msbuild does not need this. Add this section somewhere in the csproj file (I put it right at the bottom), to resolve NetFramework4 reference paths:

    <PropertyGroup Condition="$(TargetFramework.StartsWith('net4')) and '$(OS)' == 'Unix'">
    <!-- When compiling .NET SDK 2.0 projects targeting .NET 4.x on Mono using 'dotnet build' you -->
    <!-- have to teach MSBuild where the Mono copy of the reference asssemblies is -->
    <!-- Look in the standard install locations -->
    <BaseFrameworkPathOverrideForMono Condition="'$(BaseFrameworkPathOverrideForMono)' == '' AND EXISTS('/Library/Frameworks/Mono.framework/Versions/Current/lib/mono')">/Library/Frameworks/Mono.framework/Versions/Current/lib/mono</BaseFrameworkPathOverrideForMono>
    <BaseFrameworkPathOverrideForMono Condition="'$(BaseFrameworkPathOverrideForMono)' == '' AND EXISTS('/usr/lib/mono')">/usr/lib/mono</BaseFrameworkPathOverrideForMono>
    <BaseFrameworkPathOverrideForMono Condition="'$(BaseFrameworkPathOverrideForMono)' == '' AND EXISTS('/usr/local/lib/mono')">/usr/local/lib/mono</BaseFrameworkPathOverrideForMono>
    <!-- If we found Mono reference assemblies, then use them -->
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net40'">$(BaseFrameworkPathOverrideForMono)/4.0-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net45'">$(BaseFrameworkPathOverrideForMono)/4.5-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net451'">$(BaseFrameworkPathOverrideForMono)/4.5.1-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net452'">$(BaseFrameworkPathOverrideForMono)/4.5.2-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net46'">$(BaseFrameworkPathOverrideForMono)/4.6-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net461'">$(BaseFrameworkPathOverrideForMono)/4.6.1-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net462'">$(BaseFrameworkPathOverrideForMono)/4.6.2-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net47'">$(BaseFrameworkPathOverrideForMono)/4.7-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net471'">$(BaseFrameworkPathOverrideForMono)/4.7.1-api</FrameworkPathOverride>
    <FrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != '' AND '$(TargetFramework)' == 'net472'">$(BaseFrameworkPathOverrideForMono)/4.7.2-api</FrameworkPathOverride>
    <EnableFrameworkPathOverride Condition="'$(BaseFrameworkPathOverrideForMono)' != ''">true</EnableFrameworkPathOverride>
    <!-- Add the Facades directory.  Not sure how else to do this. Necessary at least for .NET 4.5 -->
    <AssemblySearchPaths Condition="'$(BaseFrameworkPathOverrideForMono)' != ''">$(FrameworkPathOverride)/Facades;$(AssemblySearchPaths)</AssemblySearchPaths>
  4. For projects that have lived through C# evolution from C# 5 to C# 7: You may need to remove duplicate references to e.g. System.ValueTuple. Add Condition="'$(OS)' != 'Unix'" to the reference. This applies to Types that MS put on NuGet.org during the evolution. idk why msbuild builds without complain on Windows but not on Unices.

    <Reference Condition="'$(OS)' != 'Unix'" Include="System.ValueTuple, Version=, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51, processorArchitecture=MSIL">
  5. For References to Microsoft.VisualStudio.TestTools.UnitTesting: Add a nuget reference to MSTEST V2 from nuget.org and make it conditional on the OS

    <ItemGroup Condition="'$(OS)' == 'Unix'">
    <Reference Include="MSTest.TestFramework" Version="2.1.1">
    <Reference Include="coverlet.collector" Version="1.3.0" >

    Note this will only get you to a successful build. To run the tests on unix you then have to download and build https://github.com/microsoft/vstest and run it with e.g.
    mono ~/Source/Repos/vstest/artifacts/Debug/net451/ubuntu.18.04-x64/vstest.console.exe --TestAdapterPath:~/Source/Repos/vstest/test/Microsoft.TestPlatform.Common.UnitTests/bin/Debug/net451/ MyTestUnitTestProjectName.dll.

  6. Case Sensitivity & mis-cased references
    Windows programmers are used to a case-insensitive filesystem. So if code or config contains references to files, you may need to correct mismatched casing. Usually a 'FileNotFoundException' will tell you if you have this problem.

  7. The Registry, and other Permissions
    See this post for more: https://www.cafe-encounter.net/p1510/asp-net-mvc4-net-framework-version-4-5-c-razor-template-for-mono-on-mac-and-linux

Using the command line

It is helpful to be somewhat familiar with microsoft docs on MSBuild Concepts since msbuild will be issuing most of your build errors. If you have installed mono then you can run msbuild from the command line with extra diagnostics e.g.

msbuild -v:d >> build.log

you can also run web applications from the command just by running


from the project directory.

Original Text from 2011

For reasons best not examined too closely I switch between between Mac and PC which, since I earn my crust largely with .Net development, means switching between Visual Studio and MS.Net and MonoDevelop with Mono.

Mono is very impressive, it is not at all a half hearted effort, and it does some stuff that MS haven't done. But when switching environments, there's always the occasional gotcha. Here are some that have got me, and some solutions.

  • Gotcha: Linq Expressions don't work on Mono?
    Solution: Add a reference to System.Core to your project.
  • Question: What version of NUnit is built in to mono?As of Feb 2011, it's nunit 2.4.8.

Dev Azure Pipeline Web Config Transform

The web.config transform appears at first glance to be somewhat orphaned in Azure DevOps. If you are deploying to a WebApp then the pipeline wizard will probably have given you this snippet for your Build step:

- task: [email protected]
solution: '$(solution)'
msbuildArgs: '/p:DeployOnBuild=true /p:WebPublishMethod=Package /p:PackageAsSingleFile=true /p:SkipInvalidConfigurations=true /p:DesktopBuildPackageLocation="$(build.artifactStagingDirectory)\WebApp.zip" /p:DeployIisAppPath="Default Web Site"'
platform: '$(buildPlatform)'
configuration: '$(buildConfiguration)'

To run config transforms you can add the additional parameter /p:TransformConfigFile=true to your msbuildArgs.

The replacement, of course, is the independent FileTransform task (which can also work within zip files). But once your site is packaged the Web.Release.Config is left behind; so you have to run the FileTransform task before, not after, the build step. (Similarly the WebAppDeployment task can't transform a Web.Release.config that isn't inside the package).

Slightly magically, the default parameter for the FileTransform is exactly what you typically want for web.Release.config transforms:

#xmlTransformationRules: '-transform **\*.Release.config -xml **\*.config-transform **\*.$(Release.EnvironmentName).config -xml **\*.config' # Optional

FileTransform can also do variable substitution, and you can have multiple FileTransform steps in your pipeline. I also like to see some diagnostic feedback so I include script step to show the xml transform result. But I put it before variable substitution, because the variables often include secrets:

- task: [email protected]
displayName: Transform Release.Config
folderPath: '$(System.DefaultWorkingDirectory)/Ui/'
enableXmlTransform: true
xmlTransformationRules: -transform **/*.Release.config -xml **/*.config

- task: [email protected]
displayName: "Confirm web.config transform"
targetType: 'inline'
script: 'cat $env:System_DefaultWorkingDirectory/Ui/web.config'
errorActionPreference: 'continue'

- task: [email protected]
displayName: Variable substitution *.config
folderPath: '$(System.DefaultWorkingDirectory)/Ui/'
fileType: 'xml'
targetFiles: '**/*.config'

- task: [email protected]


Default timeouts in .Net code. What are they if you don’t specify?

What are the default timeouts in .Net code if you don't specify one? I realised I didn't know, when I got timeouts for an HttpClient calling a WCF service calling a SQL query. The choices are all reasonable. But they're all different. So here's a list.


.Timeout Default 100 seconds
The entire time to wait for the request to complete.
https://docs.microsoft.com/en-us/dotnet/api/system.net.http.httpclient.timeout?view=netframework-4.5 (if your url requires a DNS call and you set timeout < 15 seconds, your timeout may be ineffective; it may still take up to 15 seconds to timeout.)

System.Data.SqlClient SqlConnection & SqlCommand

SqlConnection.ConnectionTimeout Default 15 seconds

The timeout to wait for a connection to open.

SqlCommand.CommandTimeout Default 30 seconds

The wait time before terminating the attempt to execute a command and generating an error.


Remarks & Notes

  • A value of 0 indicates no limit (an attempt to execute a command will wait indefinitely).
  • The CommandTimeout property will be ignored during asynchronous method calls such as BeginExecuteReader.
  • CommandTimeout has no effect when the command is executed against a context connection (a SqlConnection opened with "context connection=true" in the connection string).
  • This is the cumulative time-out (for all network packets that are read during the invocation of a method) for all network reads during command execution or processing of the results. A time-out can still occur after the first row is returned, and does not include user processing time, only network read time. For example, with a 30 second time out, if Read requires two network packets, then it has 30 seconds to read both network packets. If you call Read again, it will have another 30 seconds to read any data that it requires.



This interface does not, of course, set any default values, but it does define the meaning of the four main timeouts applicable to WCF.

System.ServiceModel.Channels.Binding Default values

Remember, timeouts in WCF apply at the level of the Binding used by the client or service. (Think about it. It makes sense).

So the Binding class defaults affect all your WCF operations unless a specific binding subclass changes it. Subclasses include: BasicHttpBinding, WebHttpBinding, WSDualHttpBinding, all other HttpBindings, all MsmqBindings, NetNamedPipeBinding, NetPeerTcpBinding, NetTcpBinding, UdpBinding, and CustomBindings.

The defaults are:
OpenTimeout 1 minute
CloseTimeout 1 minute
SendTimeout 1 minute
ReceiveTimeout 10 minutes

However whilst some bindings - basicHtp, netTcp– specify the same—1 min, 1min, 1min, 10 minutes—as Binding base class …

WCF Service Timeouts for webHttpBinding, wsDualHttpBinding and other bindings

The documentation for these bindings contradict (or should I say, override) the documentation for the framework classes and say that all four timeouts, including ReceiveTimeout, default to 1 minute. It could be a typo, I haven't tested. See all the various bindings at https://docs.microsoft.com/en-us/dotnet/framework/configure-apps/file-schema/wcf/bindings.

webHttpBinding vs basicHttpBinding Reminder:
webHttpBinding is for simple (so-called rest-style) HTTP requests as opposed to Soap. basicHttpBinding is for SOAP, i.e.conforming to the WS-I Basic Profile 1.1.

WCF Client Timeouts

A WCF client uses three of these Timeout settings. Since the default value is set by the Binding, what remains is to clarify the definitions.

  • SendTimeout : used to initialize the OperationTimeout, which governs the whole process of sending a message, including receiving a reply message for a request/reply service operation. This timeout also applies when sending reply messages from a callback contract method.
  • OpenTimeout – used when opening channels
  • CloseTimeout – used when closing channels
    ReceiveTimeout is meaningless for a client and is not used.


WCF Serverside Timeouts

A WCF service uses all four Timeout settings. Three have the same definition as a WCF Client. The fourth is:

WCF using a Binding with reliableSession

Some System.ServiceModel.Bindings allow the use of ReliableSession behaviour, which adds another timeout:

InactivityTimeout defaults to 10 minutes.



  • Activity on a channel is defined as receiving an application or infrastructure message. The inactivity timeout parameter controls the maximum amount of time to keep an inactive session alive. If more than InactivityTimeout time interval passes with no activity, the session is aborted by the infrastructure and the channel faults. The reliable session is torn down unilaterally.
  • If the sending application has no messages to send then the reliable session is normally not faulted because of inactivity; instead a keep-alive mechanism keeps the session active indefinitely. Note that the dispatcher can independently abort the reliable session if no application messages are sent or received. Thus, the inactivity timeout typically expires if network conditions are such that no messages are received or if there is a failure on the sender.


WCF Server using HttpBinding with reliableSession implemented as Connection: Keep-Alive HTTP header


BasicHttpBinding does not use any kind of session so receiveTimeout should be irrelevant.
BasicHttpBinding can use HTTP persistent connection. Persistance is provided by Connection: Keep-Alive HTTP header which allows sharing single TCP connection for many HTTP requests/responses. There appears to be no way to change the timeout associated with this header, and IIS appears to always timeout at 100 seconds of inactivity. IIS's keep-alive default timeout value is 120s, but changing this seems to have no effect on the WCF service.

The interesting thing is that closing proxy/channel on the client side does not close the TCP connection. The connection is still opened and prepared to be used by another proxy to the same service. The connection closes when 100s inactivity timeout expires or when application is terminated. Btw. there is RFC which defines that max. two such TCP connections can exists between client and single server (this is default behavior in windows but can be changed).

You can turn off HTTP persistent connection if you implement cutomBinding and set keepAliveEnabled="false" in httpTransport element. This will force client to create new TCP connection for each HTTP request.

IIS Timeouts


connectionTimeout: Default 2 minutes.

Specifies the time (in seconds) that IIS waits before it disconnects a connection that is considered inactive. Connections can be considered inactive for the following reasons:

  • The HTTP.sys Timer_ConnectionIdle timer expired. The connection expired and remains idle.
  • The HTTP.sys Timer_EntityBody timer expired. The connection expired before the request entity body arrived. When it is clear that a request has an entity body, the HTTP API turns on the Timer_EntityBody timer. Initially, the limit of this timer is set to the connectionTimeout value. Each time another data indication is received on this request, the HTTP API resets the timer to give the connection more minutes as specified in the connectionTimeout attribute.
  • The HTTP.sys Timer_AppPool timer expired. The connection expired because a request waited too long in an application pool queue for a server application to dequeue and process it. This time-out duration is connectionTimeout.

headerWaitTimeout : Default 0 seconds
ToDo: Does this mean none, or does it mean no timeout until the connectionTimeout is hit?

IIS Asp.Net HttpRuntime

executionTimeout: 110 seconds in .Net framework 2.0 & 4.x. In the .NET Framework 1.0 and 1.1, the default is 90 seconds

IIS WebSockets

pingInterval: default is 0 seconds.

IIS Classic Asp

queueTimeout : default value is 0.
The maximum period of time (hh:mm:ss) that an ASP request can wait in the request queue.

scriptTimeout : default value is 1 minute 30 seconds
The maximum period of time that ASP pages allow a script to run run before terminating the script and writing an event to the Windows Event Log.



activityTimeout: The default value in IIS 7.0 is 30seconds ; the default for IIS 7.5 is 70 seconds.
The maximum time, in seconds, that a FastCGI process can take to process.

idleTimeout: default 300 seconds.
The maximum amount of time, in seconds, that a FastCGI process can be idle before the process is shut down

requestTimeout: default 90 seconds
The maximum time, in seconds, that a FastCGI process request can take.

Http Server 408 Request Timeout


The 408 (Request Timeout) status code indicates that the server did not receive a complete request message within the time that it was prepared to wait. A server SHOULD send the "close" connection option (Section 6.1 of [RFC7230]) in the response, since 408 implies that the server has decided to close the connection rather than continue waiting. If the client has an outstanding request in transit, the client MAY repeat that request on a new connection.

See Also

Bash and PowerShell in a single script file

I'm not saying it's all dotnet’s fault, but it was when deploying dotnetcore services to a linux VM that I thought, “what I really, really want is both bash and powershell setup scripts in a single file”. Surely a working incantation can be crafted from such arcane systems of quoting and escaping as the two languages offer?

½ an evening later :

# This file has a bash section followed by a powershell section,
# and a shared section at the end.
echo @'
' > /dev/null
# Bash Start --------------------------------------------------

scriptdir="`dirname "${BASH_SOURCE[0]}"`";
echo BASH. Script is running from $scriptdir

# Bash End ----------------------------------------------------
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
echo > /dev/null <<"out-null" ###
'@ | out-null
# Powershell Start --------------------------------------------

"powershell. Script is running from $scriptdir"

# Powershell End ----------------------------------------------
# ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

echo "Some lines work in both bash and powershell. Calculating scriptdir=$scriptdir, requires separate sections."

It relies on herestring quoting being different for each platform, as is the escape character ( \ vs ` ). Readibility (ha!) is very much helped by

#comments begin with a hash 

being common to both, so I can do visible dividers between the sections.

My main goal was environment variable setup before launching dotnetcore services. Sadly the incompatible syntaxes for variables and environment:

#powershell syntax
#bash syntax
export variable2=value 

means very little shared code inside the file, but it really cut down errors a lot just by having them in the same file. Almost-a-single-source-of-truth turned out to be much more reliable than not-at-all a single source of truth.

Bash-then-powershell was simpler than Powershell-then-bash. My state-of-the art is powershell named and validated parameters, which allows tab-completion to work in powershell.

` # \
# PowerShell Param
# every line must end in #\ except last line must end in <#\
# And, you can't use backticks in this section        #\
param( [ValidateSet('A','B')]$tabCompletionWorksHere, #\
       [switch]$andHere                               #\
     )                                               <#\
#^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `

Repo: github.com/chrisfcarroll/PowerShell-Bash-Dual-Script-Templates

Raw: Powershell-or-bash-with-parameters .

Alternatively, do everything in powershell?

Of course, sensible people would do everything in a single scripting language. But it has been well-worth having the tools for both approaches. Especially for short bootstrap scripts.

For a powershell core everywhere approach, my main adaptation is the shebang header on all .ps1 files:

#! /usr/bin/env pwsh

which tells unix machines to what kind of script it is. Powershell itself ignores it as a comment. Finally, you must also chmod a+x *.ps1 to mark them as executable.