C# – the proper way for a Windows service to fail

cwindows-services

I have inherited a Windows service written in C#. Under rare conditions it fails badly. However, it isn't at all clear how to fail well. Ross Bennett states the problem elegantly at bytes.com. For the sake of simplicity I will just quote him here.

Ahoy, Folks!

I've been looking all over for this,
but I just can't seem to shake any
documentation out of the MSDN or from
Google. I've reviewed every .NET
article on developing Windows Services
in the MSDN I've located.

I'm developing a Windows Service
application. This service reads its
configuration data from the system
registry (HKLM) where it was deposited
by another "manager" application. No
problems there.

The service uses a worker thread to do
its work. The thread is created in the
OnStart() and signaled/joined/disposed
in the OnStop(). Again, no problems.

Everything works beautifully when:

The system administrator has set up everything properly, and

the foreign network resources are all reachable.

But of course, we as developers simply
can't rely on:

The system administrator having set up everything properly, or

the foreign network resources being reachable.

Really, what we need is for the
service application to have some way
of dying on its own. If a network
resource goes down, we need the
service to stop. But more to the
point, we need the SCM to know it has
stopped on its own accord. SCM needs
to know that the service has
"failed"…and hasn't just been shut
down by someone.

Calling "return" or throwing an
exception in the "OnStart()" method
isn't even helpful for services still
in the start-up process.. The SCM goes
merrily on and the process keeps
running in the Task Manager–though
it's not actually doing anything since
the worker thread was never created
and started.

Using a ServiceController instance
doesn't do it, either. That appears to
the SCM as a normal shutdown–not a
service failure. So none of the
recovery actions or restarts happen.
(Also, there is MSDNful documentation
warning about the perils of a
ServiceBase descendant using a
ServiceController to make things
happen with itself.)

I've read articles where people were
messing about with PInvoking calls to
the native code just to set the
"Stopped" status flag in the SCM. But
that doesn't shut down the process the
service is running within.

I'd really like to know the Intended
Way of:

Shutting down a service from within the service, where

The SCM is appropriatedly notified that the service has "Stopped", and

The process disappears from the Task Manager.

Solutions involving ServiceControllers
don't seem to be appropriate, if only
because 2 is not satisfied. (That the
Framework documentation specifically
contraindicates doing that carries a
good deal of weight, incidentally.)

I'd appreciate any recommendations,
pointers to documentation, or even
well-reasoned conjecture. 🙂 Oh! And
I'm perfectly happy to entertain that
I've missed the point.

Most cordially,

Ross Bennett

Best Answer

Best practice in native code is to call SetServiceStatus with a non-zero exit code to indicate 1) it's stopped and 2) something went wrong.

In managed code, you could achieve the same effect by obtaining the SCM handle through the ServiceBase.ServiceHandle Property and P/Invoke-ing the Win32 API.

I don't see why the SCM would treat this any differently than setting the ServiceBase.ExitCode property non-zero and then calling ServiceBase.Stop, actually. P/Invoke is a bit more direct perhaps, if the service is in panic mode.

As noted in the comments (also see https://serverfault.com/questions/72318/set-up-recovery-actions-to-take-place-when-a-service-fails) if a process calls SetServiceStatus(SERVICE_STOPPED) with a non-zero exit code, the Recovery Actions for the serice will only be done if the option "Enable Actions For Stops With Errors" (sc.exe failureflag) is ticked. -> System Event ID 7024

If a service process exits (Env.Exit()) or crashs without consulting the SCM, then the Recovery Actions will always be run. -> System Event ID 7031

This is the style that Microsoft tends to use in their examples.

It appears that the guidance in this area may have changed, as StyleCop now enforces the use of the C# specific aliases.

C# – What does the [Flags] Enum Attribute mean in C#

The [Flags] attribute should be used whenever the enumerable represents a collection of possible values, rather than a single value. Such collections are often used with bitwise operators, for example:

var allowedColors = MyColor.Red | MyColor.Green | MyColor.Blue;

Note that the [Flags] attribute doesn't enable this by itself - all it does is allow a nice representation by the .ToString() method:

enum Suits { Spades = 1, Clubs = 2, Diamonds = 4, Hearts = 8 }
[Flags] enum SuitsFlags { Spades = 1, Clubs = 2, Diamonds = 4, Hearts = 8 }

...

var str1 = (Suits.Spades | Suits.Diamonds).ToString();
           // "5"
var str2 = (SuitsFlags.Spades | SuitsFlags.Diamonds).ToString();
           // "Spades, Diamonds"

It is also important to note that [Flags] does not automatically make the enum values powers of two. If you omit the numeric values, the enum will not work as one might expect in bitwise operations, because by default the values start with 0 and increment.

Incorrect declaration:

[Flags]
public enum MyColors
{
    Yellow,  // 0
    Green,   // 1
    Red,     // 2
    Blue     // 3
}

The values, if declared this way, will be Yellow = 0, Green = 1, Red = 2, Blue = 3. This will render it useless as flags.

Here's an example of a correct declaration:

[Flags]
public enum MyColors
{
    Yellow = 1,
    Green = 2,
    Red = 4,
    Blue = 8
}

To retrieve the distinct values in your property, one can do this:

if (myProperties.AllowedColors.HasFlag(MyColor.Yellow))
{
    // Yellow is allowed...
}

or prior to .NET 4:

if((myProperties.AllowedColors & MyColor.Yellow) == MyColor.Yellow)
{
    // Yellow is allowed...
}

if((myProperties.AllowedColors & MyColor.Green) == MyColor.Green)
{
    // Green is allowed...
}

Under the covers

This works because you used powers of two in your enumeration. Under the covers, your enumeration values look like this in binary ones and zeros:

 Yellow: 00000001
 Green:  00000010
 Red:    00000100
 Blue:   00001000

Similarly, after you've set your property AllowedColors to Red, Green and Blue using the binary bitwise OR | operator, AllowedColors looks like this:

myProperties.AllowedColors: 00001110

So when you retrieve the value you are actually performing bitwise AND & on the values:

myProperties.AllowedColors: 00001110
             MyColor.Green: 00000010
             -----------------------
                            00000010 // Hey, this is the same as MyColor.Green!

The None = 0 value

And regarding the use of 0 in your enumeration, quoting from MSDN:

[Flags]
public enum MyColors
{
    None = 0,
    ....
}

Use None as the name of the flag enumerated constant whose value is zero. You cannot use the None enumerated constant in a bitwise AND operation to test for a flag because the result is always zero. However, you can perform a logical, not a bitwise, comparison between the numeric value and the None enumerated constant to determine whether any bits in the numeric value are set.

You can find more info about the flags attribute and its usage at msdn and designing flags at msdn

Best Answer

Related Solutions

C# – the difference between String and string in C#

This is the style that Microsoft tends to use in their examples.

C# – What does the [Flags] Enum Attribute mean in C#

Related Topic