C# Frequently Asked Questions

Microsoft "Roslyn" September 2012 CTP now available

CSharpFAQ — Mon, 17 Sep 2012 16:02:00 GMT

Following last Wednesday’s official launch of Visual Studio 2012, we’re excited to announce that the Roslyn September 2012 CTP is now available for download and provides support for VS 2012 RTM. Please note that Visual Studio 2010 is no longer supported by this CTP.

We’ve been hard at work since the first public release of Roslyn adding support for new language features and improving our APIs. In addition, we’ve also updated our NuGet packages to match the September 2012 CTP.

As always, your feedback is critical! Please get involved in the discussion on the Roslyn forum, file bugs on Connect, or just give us a shout-out on Twitter @ #RoslynCTP!

Enjoy!

Dustin Campbell

About the Author

Dustin Campbell is a Program Manager responsible for the C# and VB language experiences on the Roslyn project.

Understanding a Simple Async Program

CSharpFAQ — Tue, 26 Jun 2012 16:00:00 GMT

by Alan Berman

The Async feature in Visual Studio 2012 RC makes it easy to invoke asynchronous methods.

If you mark a method with or async modifier, you can use the await operator in the method. When control reaches an await expression in the async method, control returns to the caller, and progress in the method is suspended until the awaited task completes. When the task is complete, execution can resume in the method.

Using asynchronous methods instead of synchronous methods can provide benefits. Asynchrony makes UI applications more responsive because the UI thread that launches that operation can perform other work. Asynchrony also improves the scalability of server-based application by reducing the need for threads.

This blog provides a simple async example and describes what occurs when it runs. It also provides an example of exception handling for a call to an async method.

Running the Examples

To run the examples in this blog, you can do the following:

Install Visual Studio 2012 RC, which can be accessed from Visual Studio Asynchronous Programming.
Create WPF Application or Windows Forms Application.
In your project, add a reference to System.Net.Http. This allows you to use the HttpClient class in the first example,
Add a Button to the application. Modify the Button_Click event handler to add the async modifier. The Button_Click event handlers in the examples are from a WPF Application, however they can be modified for a Windows Form Application.
Include the following using statements.

    using System.Diagnostics;
    using System.Net.Http;
    using System.Threading.Tasks;

Example of async and await

The following example illustrates use of the async modifier and the await operator. An explanation is provided below. Note that startButton_Click is marked with the async modifier

    private async void startButton_Click(object sender, RoutedEventArgs e)
    {
        Task<string> getWebPageTask = GetWebPageAsync("http://msdn.microsoft.com");

        Debug.WriteLine("In startButton_Click before await");
        string webText = await getWebPageTask;
        Debug.WriteLine("Characters received: " + webText.Length.ToString());
    }

    private async Task<string> GetWebPageAsync(string url)
    {
        // Start an async task.
        Task<string> getStringTask = (new HttpClient()).GetStringAsync(url);

        // Await the task. This is what happens:
        // 1. Execution immediately returns to the calling method, returning a
        //    different task from the task created in the previous statement.
        //    Execution in this method is suspended.
        // 2. When the task created in the previous statement completes, the
        //    result from the GetStringAsync method is produced by the Await
        //    statement, and execution continues within this method.
        Debug.WriteLine("In GetWebPageAsync before await");
        string webText = await getStringTask;
        Debug.WriteLine("In GetWebPageAsync after await");

return webText;
}

    // Output:
    //   In GetWebPageAsync before await
    //   In startButton_Click before await
    //   In GetWebPageAsync after await
    //   Characters received: 44306

Control Flow in Example

In the above example, the startButton_Click method calls the GetWebPageAsync method. In the GetWebPageAsync method, the following occurs:

The GetWebPageAsync method calls the GetStringAsync method, which returns a task.
The “await getStringTask” expression causes the GetWebPageAsync method to immediately exit and return a different task. Execution in the GetWebPageAsync method is suspended.
When the awaited task (getStringTask) completes at a later time, processing resumes after the await statement in the GetWebPageAsync method.

The startButton_Click method also contains an await expression, which is “await getWebPageTask”. Because GetWebPageAsync is an async method, the task for the call to GetWebPageAsync needs to be awaited. startButton_Click needs to be defined with the async modifier because it has an await expression.

Return Types in Example

In the above example, the GetWebPageAsync method has a return statement that returns a string. Therefore, the method declaration of GetWebPageAsync has a return type of Task<string>. Because the return type is Task<string>, the evaluation of the await expression in startButton_Click produces a string, as the following statement demonstrates: string webText = await getWebPageTask; .

Similarly, the GetWebPageAsync method calls the GetStringAsync method, which is defined with a return type of Task<string>. The call to GetStringAsync returns a Task<string> and the evaluation of the await expression produces a string.

The startButton_Click method has a return type of void.

Note: An async method can have a return type of Task<TResult>, Task, or void. The void return type is used primarily to define event handlers, where a void return type is required. An async method that returns void can't be awaited, and the caller of a void-returning method can't catch exceptions that are thrown by the method.

Simplified Code

In the above example, the GetWebPageAsync method includes the following two statements:

Task<string> getStringTask = (new HttpClient()).GetStringAsync(url);
string webText = await getStringTask;

The above two statements can be condensed into one statement, as follows:

string webText = await (new HttpClient()).GetStringAsync(url);

The condensed statement also returns a task and awaits the task, however the task is not stored in a variable. While the condensed statement is more concise, the uncondensed code facilitates a greater understanding of the control flow of your code, and of the associated tasks.

Exception Handling

The following example illustrates exception handling for an async method. To catch an exception that applies to an async task, the await expression is in a try block, and the exception is caught in a catch block.

Uncomment the “throw new Exception” line in the example to demonstrate exception handling. The exception is caught in the catch block, and the task's IsFaulted property is set to true, and the task's Exception.InnerException property is set to the exception.

Uncomment the “throw new OperationCancelledException” line to demonstrate what happens when you cancel an asynchronous process. The exception is caught in the catch block and the task's IsCanceled property is set to true. Under some conditions that don't apply to this example, IsFaulted is set to true and IsCanceled is set to false.

    private async void testExceptionButton_Click(object sender, RoutedEventArgs e)
    {
        Task<string> theTask = DelayAsync();

        try
        {
            string result = await theTask;
            Debug.WriteLine("Result: " + result);
        }
        catch (Exception ex)
        {
            Debug.WriteLine("Exception Message: " + ex.Message);
        }
        Debug.WriteLine("Task IsCanceled: " + theTask.IsCanceled);
        Debug.WriteLine("Task IsFaulted: " + theTask.IsFaulted);
        if (theTask.Exception != null)
        {
            Debug.WriteLine("Task Exception Message: "
                + theTask.Exception.Message);
            Debug.WriteLine("Task Inner Exception Message: "
                + theTask.Exception.InnerException.Message);
        }
    }

    private async Task<string> DelayAsync()
    {
        await Task.Delay(100);

// Uncomment each of the following lines to
// demonstrate exception handling.

        //throw new OperationCanceledException("canceled");
        //throw new Exception("Something happened.");
        return "Done";
    }

    // Output when no exception is thrown in the awaited method:
    //   Result: Done
    //   Task IsCanceled: False
    //   Task IsFaulted: False

    // Output when an Exception is thrown in the awaited method:
    //   Exception Message: Something happened.
    //   Task IsCanceled: False
    //   Task IsFaulted: True
    //   Task Exception Message: One or more errors occurred.
    //   Task Inner Exception Message: Something happened.

    // Output when a OperationCanceledException or TaskCanceledException
    // is thrown in the awaited method:
    //   Exception Message: canceled
    //   Task IsCanceled: True
    //   Task IsFaulted: False

See Also

Resources

Announcing Microsoft “Roslyn” June 2012 CTP

CSharpFAQ — Tue, 05 Jun 2012 19:54:00 GMT

Today, we're excited to announce that the Roslyn June 2012 CTP is now available for download!

Since the first public release of Roslyn, we’ve been hard at work implementing new language features, addressing top customer feedback from the Oct CTP, iterating on our API design and improving performance across our IDE and compiler scenarios. With the recent release of Visual Studio 2012 RC, we have updated the Roslyn CTP to work with Visual Studio 2012 RC, in addition to Visual Studio 2010 SP1. There’s never been a better time to grab the VS 2012 RC and the Roslyn CTP and start exploring with the new Roslyn Interactive window!

You can find an in-depth look at what’s new in the Roslyn June 2012 CTP on Jason Zander’s blog and the Visual Studio blog. The CTP ships with a number of documents that provide an excellent way to get started – start with the overview document, and then move on to the walkthroughs. We also encourage you to check out our previous series on how to use the Roslyn APIs – the syntax visualizer is an invaluable tool, the Syntax API, the Symbol API, the Scripting API, and how to write a code action.

Feedback is a critical part of our design process! Because it’s early in the project, we’re most interested in feedback around the API and understanding what scenarios you’d like to accomplish. Please get involved in the discussion about Roslyn on our forums. You can also file bugs on our Connect site. Some of the team members are also on Twitter, and will be keeping an eye on the #RoslynCTP hashtag.

Happy Coding!

Karen Ng

About the Author

Karen Ng is the Lead Program Manager responsible for the compilers, IDEs, and Languages for C#, Visual Basic, and F# at Microsoft. Karen works on both the Visual Studio 2012 release and the Roslyn project.

Async Targeting Pack for Visual Studio 11 now available for .NET 4 and Silverlight 5

CSharpFAQ — Thu, 26 Apr 2012 20:39:00 GMT

If you’ve held off on trying Visual Studio 11 Beta because your .NET 4 or Silverlight 5 app uses the Async CTP, your wait is over! Today we’ve published the Async Targeting Pack for Visual Studio 11, a NuGet package that lets your Visual Studio 11 projects target .NET 4 and Silverlight 5 while taking advantage of C#’s new await keyword. While Visual Studio 11 provides built-in support for await in projects that target .NET 4.5 or .NET for Metro style apps, this targeting pack provides the API support to expand the set of target platforms to include .NET 4 and Silverlight 5 as well.

Check out our release notes for more details on how to install NuGet and add the package reference in Visual Studio 11 Beta.

Happy testing!

Alex Turner
Program Manager, VB/C# Compilers

Visual Studio 11 Beta Is Here!

CSharpFAQ — Wed, 29 Feb 2012 14:55:00 GMT

As you may have seen in Jason’s blog, Visual Studio 11 Beta is available for download today, including the Beta version of C# 5.0! If you’ve tried out the Visual Studio 11 Developer Preview, you already know that this is an exciting release, with two huge new features for C# developers: async methods and support for creating Windows 8 Metro style apps. However, with Beta comes even more goodness, with support for caller info attributes, as well as a host of async perf improvements and async unit-testing support.

The best way to see what’s new in Visual Studio 11 is to dive in and try it yourself. However, if you’re curious to know what you’re getting, read on!

Async methods (the await keyword)

As you migrate your desktop applications to mobile phones and tablets, you’re increasingly faced with the realities of network latency, especially given a reliance on cloud services running in distant datacenters. At the same time, your users expect far more responsiveness from these applications, with the bar set by smooth touch UIs that never drop a frame.

The way out of this conundrum up to now has been asynchronous programming and the use of callbacks. However, while callbacks can work for very simple methods, you quickly fall into the pit of despair for code that’s of any reasonable length or complexity, giving up the core control flow constructs you’ve trusted for years – chained callback methods and for loops don’t mix!

There has to be a way out of this mess, and there is – async methods in C# 5.0, powered by the await keyword:

public async Task<int?> SumPageSizesAsync(IList<Uri> uris) {
    try {
        int total = 0;
        var client = new HttpClient();
        client.MaxResponseContentBufferSize = 10000000;
        foreach (var uri in uris) {
            statusText.Text = string.Format("Found {0} bytes ...", total);
            var data = await client.GetByteArrayAsync(uri);
            total += data.Length;
        }
        statusText.Text = string.Format("Found {0} bytes total", total);
        return total;
    }
    catch (Exception) {
        statusText.Text = "Error!";
        return null;
    }
}

By marking your method with the async keyword, the C# compiler transforms it into a resumable async method that can pause execution whenever it sees the await keyword by returning control to the caller.

If this is a client app, control returns to your caller at each await, and then to its caller, and so on, until you’ve freed up the UI thread, which keeps your app responsive.
If you’re writing a server, returning to the caller frees up the thread handling the current request, ensuring that thread is available to process other requests and increasing your scalability.

In either case, once the operation you’re awaiting completes, your method wakes up, resuming execution right where it left off, even if you were within a foreach loop or a try-catch block. When execution is paused, you can even hit F10 to Step Over at the await, with the debugger returning you to the following line after the awaited operation completes.

This is just a brief peek at Async – if you’ve yet to try it, be sure to check out the Asynchronous Programming Developer Center for samples, videos and more to get started. However, if you have been using Async for a while now through our previous preview releases, you’ll be excited to see what’s new in Beta!

Since the Developer Preview, we’ve done work to further improve the perf of async methods, reducing allocations to ensure you can feel comfortable using async methods throughout your application, wherever you need them. However, such comfort also requires that you can trust your async methods to continue working as expected as you continue to make changes elsewhere in your app. To this end, MSTest and xUnit.net now support async methods directly, ensuring that the test runner waits for the async method to fully complete:

[TestMethod]
public async Task Test1() {
    var x = await Engine.GetSevenAsync();
    Assert.AreEqual(x, 6);
}

[Xunit.Fact]
public async Task Test2() {
    var y = await Engine.GetSevenAsync();
    Assert.AreEqual(x, 6);
}

Caller Info Attributes

One language feature that’s making its debut in Visual Studio 11 Beta is caller info attributes. These attributes let a method accept implicit optional parameters intended to receive a line number, a file path or a member name. Then, at the call site, the compiler will know to automatically fill in those argument values, based on the exact location where that method was called.

One great use for caller info attributes is for logging methods. The code below defines a LogMessage method that accepts 4 parameters to output a structured log message. However, when we call LogMessage within ProcessItem, we only need to specify one argument, message – the compiler will do the work for us to pass in the name of the method calling LogMessage, along with the file name and line number of that call site. Even better, if ProcessItem moves around in the file, changes files, or is renamed, the log message will be updated automatically.

public void LogMessage(string message = "",
                       [CallerMemberName] string member = "",
                       [CallerFilePath] string file = "",
                       [CallerLineNumber] int line = 0)
{
    var s = String.Format("{1} ({2}:{3}) - {0}", message, member, file, line);
    Debug.WriteLine(s);
}

public void ProcessItem(int index) {
    LogMessage(String.Format("Processing item {0}", index));

    DoSomeWork();
}

Another benefit is when you’re implementing INotifyPropertyChanged. Today, it’s common to write a helper method that invokes the PropertyChanged event, to which you pass the name of the property being set. However, you must then pass that property name as a string argument within each property setter. This adds risk when refactoring inside such classes – if you use VS to change the name of the property and all its references, you’ll have to manually update that string.

With caller info attributes, you can just call your NotifyPropertyChanged helper as below, without arguments. The compiler will pass in the name of the property for you, which will always be up to date, even if the property is renamed:

public class Widget : INotifyPropertyChanged
{
    private string statusText;
    public string StatusText
    {
        get { return statusText; }
        set { statusText = value; NotifyPropertyChanged(); }
    }

    public void NotifyPropertyChanged([CallerMemberName] string property = null)
    {
        if (PropertyChanged != null)
        {
            PropertyChanged(this, new PropertyChangedEventArgs(property));
        }
    }
    public event PropertyChangedEventHandler PropertyChanged;
}

Call to Action

If you’re excited to try out Metro style app development, async methods, caller info attributes and all the other performance and productivity improvements in Visual Studio 11 Beta, there’s a set of great resources available to explore:

Get the bits! The first step is to download Visual Studio 11 Beta – this page also has links to download Team Foundation Server 11 Beta and .NET Framework 4.5 Beta. You can install Visual Studio 11 Beta on Windows 7 to get up and running quickly, or set it up on top of the Windows 8 Consumer Preview to start writing Metro style apps.
Learn and explore! Check out Jason's blog post on Visual Studio 11 Beta and .NET Framework 4.5 Beta, and then dig deeper into what’s new in Visual Studio 11 Beta. To explore what’s new in Windows 8, first read the Building Windows 8 blog post announcing the Windows 8 Consumer Preview, and then browse the new Windows 8 app developer blog.
Share your feedback! As you build apps in Visual Studio 11 Beta, let us know what you think! Discuss what’s working well and what could be better on the Visual Studio and Windows 8 forums, and be sure to file any bugs you find through the Visual Studio, LightSwitch, and Blend Connect sites. Also, vote on the features you’d like to see in Visual Studio moving forward on our UserVoice site.

Most importantly, have fun with the Beta and build some awesome apps!

Alex Turner
Program Manager, VB/C# Compilers

Implementing a Code Action using Roslyn

CSharpFAQ — Mon, 06 Feb 2012 16:38:00 GMT

By Brian Rasmussen

The Roslyn Services API makes it easy to implement extensions that detect and fix code issues directly in Visual Studio. The Roslyn Services API is available as part of the Roslyn CTP.

In this post we implement a Visual Studio extension that identifies calls to the extension method Count() on Enumerable, where the result is compared to greater than zero, e.g. someSequence.Count() > 0. The problem, with that code construct, is that Count() may have to enumerate the entire sequence to evaluate the result. A much better approach in this case is to call Enumerable.Any() instead.

To address this we implement a CodeIssueProvider, which detects the problem and a CodeAction, which replaces the condition with a call to Enumerable.Any() as appropriate. E.g. our code action will change someSequence.Count() > 0 to someSequence.Any().

There are a couple additional scenarios, we want to handle as well: First of all, the expression could be reversed and written like 0 < someSequence.Count(). The other special case is that the comparison could be >= 1 instead of > 0, which is essentially the same comparison as before. We want the extension to be able to handle both of these cases.

Obviously we do not want to change calls to methods called Count() unless they bind to the IEnumerable<T> extension method defined on Enumerable.

Getting Started

The Roslyn CTP ships with a number of templates designed to make it easy to get started using the Roslyn APIs. To get started we create a new project and select Code Issue from the Roslyn templates under the Visual C# section. Let’s call the project ReplaceCountWithAny.

The template generates a small, working code issue provider that will highlight words with the letter “a”. To see the sample in action let’s build and run the project created by the template. This launches a new instance of Visual Studio with the extension enabled. From the newly launched Visual Studio we create a console application and notice how the namespace and class keywords and so on are underlined by our extension.

While the sample may not be very useful as an extension to Visual Studio, it neatly sets up everything we need to get started implementing our own extension. All we have to do is replace the contents of the generated GetIssues method. Notice that there are three overloads for GetIssues. We’ll implement the overload that takes a CommonSyntaxNode as input. The remaining two overloads can be left as they are in this case.

The generated CodeIssueProvider class implements ICodeIssueProvider and is decorated with the ExportSyntaxNodeCodeIssueProvider attribute. This allows Visual Studio to import this type as an extension, which will handle the contract established by the ICodeIssueProvider interface.

Implementing GetIssues

Our GetIssues method will be invoked for every syntax node, so the first thing we need to do is filter out all the nodes we don’t want to handle. Since we are looking for expressions like someSequence.Count() > 0, we’re only interested in nodes of the type BinaryExpressionSyntax. We can instruct Visual Studio to only invoke our provider for nodes of specific type(s) by providing a list of types through the ExportSyntaxNodeCodeIssueProvider attribute. Let’s update the attribute as follows:

[ExportSyntaxNodeCodeIssueProvider("ReplaceCountWithAny",

LanguageNames.CSharp, typeof(BinaryExpressionSyntax))]

class CodeIssueProvider : ICodeIssueProvider ...

This allows us to safely cast the provided CommonSyntaxNode to BinaryExpressionSyntax in GetIssues.

To identify the cases we want to handle we have to figure out if one part of the expression is a call to Enumerable.Count() and the other part is a relevant comparison. We’ll abstract those checks into a couple helper methods, so with that our implementation of GetIssues looks as follows.

public IEnumerable<CodeIssue> GetIssues(IDocument document, 
    CommonSyntaxNode node, CancellationToken cancellationToken)
{
    var binaryExpression = (BinaryExpressionSyntax)node;
    var left = binaryExpression.Left;
    var right = binaryExpression.Right;
    var kind = binaryExpression.Kind;
    if (IsCallToEnumerableCount(document, left, cancellationToken) && 
        IsRelevantRightSideComparison(document, right, kind, cancellationToken) ||
        IsCallToEnumerableCount(document, right, cancellationToken) && 
        IsRelevantLeftSideComparison(document, left, kind, cancellationToken))
    {
        yield return new CodeIssue(CodeIssue.Severity.Info, binaryExpression.Span,
            string.Format("Change {0} to use Any() instead of Count() to avoid " +
                          "possible enumeration of entire sequence.", 
                          binaryExpression));
    }
}

The instance of CodeIssue we return specifies a severity level, which can be Error, Warning or Info, a span, which is used to highlight the part of the source code the issue applies to, and a text describing the identified issue to the user.

Helper Methods

Let’s turn our attention to the helper methods used in GetIssues. IsCallToEnumerableCount returns true if the part of the expression we’re looking at is in fact a call to Count() on some sequence. Once again we’ll start by filtering the undesired expressions.

First of all the expression must be an invocation. If that’s the case, we’ll get the actual method call from the Expression property of the invocation. So if the expression we’re looking at is someSequence.Count() > 0 we now have the Count() part, but how do we figure out if this binds to the Enumerable type?

To answer questions like that we need to query the semantic model. Fortunately part of the input to GetIssues is an IDocument, which represents a single document in a project and solution. We can get the semantic model via the document and from there we can get the SymbolInfo we need.

With the SymbolInfo present we can check if our call binds to the desired method. Because Count() is an extension method we’ll need to handle it a bit differently. Recall that C# allows extension methods to be called as if they were part of the calling type. The semantic model represents this as a MethodSymbol with a ConstructedFrom property set to the original type. This could possibly be handled slightly better, so look out for changes in the API here.

All that remains is to figure out the declaring type for our constructed extension method. If that matches Enumerable we have found an invocation of Enumerable.Count().

The implementation looks like this:

private bool IsCallToEnumerableCount(IDocument document, 
    ExpressionSyntax expression, CancellationToken cancellationToken)
{
    var invocation = expression as InvocationExpressionSyntax;
    if (invocation == null)
    {
        return false;
    }
 
    var call = invocation.Expression as MemberAccessExpressionSyntax;
    if (call == null)
    {
        return false;
    }
 
    var semanticModel = document.GetSemanticModel(cancellationToken);
    var methodSymbol = semanticModel.GetSemanticInfo(call, cancellationToken).Symbol 
        as MethodSymbol;

    if (methodSymbol == null || 
        methodSymbol.Name != "Count" || 
        methodSymbol.ConstructedFrom == null)
    {
        return false;
    }

 
    var enumerable = semanticModel.Compilation.GetTypeByMetadataName(
        typeof(Enumerable).FullName);
 
    if (enumerable == null || 
        !methodSymbol.ConstructedFrom.ContainingType.Equals(enumerable))
    {
        return false;
    }
 
    return true;
}

With that settled the next thing we need to look for is a relevant comparison on the other side of the binary expression and that’s the job of our IsRelevantRightSideComparison and IsRelevantLeftSideComparison helper methods.

Here are the implementations for those:

private bool IsRelevantRightSideComparison(IDocument document, 
    ExpressionSyntax expression, SyntaxKind kind, 
    CancellationToken cancellationToken)
{
    var semanticInfo = document.GetSemanticModel(cancellationToken).
        GetSemanticInfo(expression);
 
    int? value;
    if (!semanticInfo.IsCompileTimeConstant || 
        (value = semanticInfo.ConstantValue as int?) == null)
    {
        return false;
    }
 
    if (kind == SyntaxKind.GreaterThanExpression && value == 0 ||
        kind == SyntaxKind.GreaterThanOrEqualExpression && value == 1)
    {
        return true;
    }
 
    return false;
}

private bool IsRelevantLeftSideComparison(IDocument document, 
    ExpressionSyntax expression, SyntaxKind kind, 
    CancellationToken cancellationToken)
{
    var semanticInfo = document.GetSemanticModel(cancellationToken).
        GetSemanticInfo(expression);
 
    int? value;
    if (!semanticInfo.IsCompileTimeConstant ||
        (value = semanticInfo.ConstantValue as int?) == null)
    {
        return false;
    }
 
    if (kind == SyntaxKind.LessThanExpression && value == 0 ||
        kind == SyntaxKind.LessThanOrEqualExpression && value == 1)
    {
        return true;
    }
 
    return false;
}

They are almost identical, but it is important that we get the both the comparison and the value correct so we don’t highlight something like Count() >= 0.

Testing the CodeIssueProvider

At this point our code issue provider can detect the issues we’re interested in handling. Compile and run the project to launch a new instance of Visual Studio with our extension enabled. Add some code and notice that calls to Enumerable.Count() are correctly underlined while method calls to other methods named Count() are not.

The next step is to provide a code action for our code issue.

CodeAction

To implement a code action we need a type which implements ICodeAction. ICodeAction is a simple interface that defines a description and an icon for the action and a single method called GetEdit, which returns an edit that will transform the current syntax tree. Let’s start by looking at the constructor for our CodeAction class.

public CodeAction(ICodeActionEditFactory editFactory, 
    IDocument document, BinaryExpressionSyntax binaryExpression)
{
    this.editFactory = editFactory;
    this.document = document;
    this.binaryExpression = binaryExpression;
}

An instance of CodeAction will be created for every code issue identified, so for convenience sake we just pass the arguments we need to implement the change to the constructor itself. We need an ICodeActionEditFactory to create a transformation for our newly created syntax tree. As syntax trees are immutable in Roslyn, returning a new tree is the only way we can make any changes. Fortunately, Roslyn will reuse as much of the original tree as possible and thus avoid creating unnecessary nodes.

Furthermore we need a document to let us access both the syntax tree and the project and solution for our source code and a reference to the syntax node we want to replace.

This brings us to the GetEdit method. This is where we create a transformation, which will replace the identified binary expression node with a newly created invocation node for the call to Any(). The creation of the new node is handled by a small helper method called GetNewNode. Both are listed below.

public ICodeActionEdit GetEdit(CancellationToken cancellationToken)
{
    var syntaxTree = (SyntaxTree)document.GetSyntaxTree(cancellationToken);
    var newExpression = GetNewNode(binaryExpression).
        WithLeadingTrivia(binaryExpression.GetLeadingTrivia()).
        WithTrailingTrivia(binaryExpression.GetTrailingTrivia());
    var newRoot = syntaxTree.Root.ReplaceNode(binaryExpression, newExpression);
 
    return editFactory.CreateTreeTransformEdit(
        document.Project.Solution,
        syntaxTree,
        newRoot,
        cancellationToken: cancellationToken);
}

 
private ExpressionSyntax GetNewNode(BinaryExpressionSyntax node)
{
    var invocation = node.DescendentNodes().
        OfType<InvocationExpressionSyntax>().Single();
    var caller = invocation.DescendentNodes().
        OfType<MemberAccessExpressionSyntax>().Single();
    return invocation.Update(
        caller.Update(caller.Expression, 
        caller.OperatorToken, 
        Syntax.IdentifierName("Any")),
        invocation.ArgumentList);
}

The Roslyn syntax tree maintains full fidelity with the original source code, so each node in the tree may have both leading and trailing trivia representing white space and comments. I.e. we need to preserve the trivia from the original node to maintain comments and layout of the code when we exchange the nodes. We call the WithLeadingTrivia and WithTrailingTrivia extension methods to handle that.

Also, notice that GetNewNode preserves the argument list from Count(), so if the extension method was invoked with a lambda to count specific items in the sequence so will Any().

Wrapping Up

To enable our code action we need to update GetIssues in our CodeIssueProvider to return a CodeAction with each CodeIssue. Each code issue may provide a number of code actions to let the user pick between different resolutions. In this case we will just return a single code action as outlined above.

The updated part of GetIssues looks like this:

yield return new CodeIssue(CodeIssue.Severity.Info, binaryExpression.Span,
    string.Format("Change {0} to use Any() instead of Count() to avoid " +
                  "possible enumeration of entire sequence.", binaryExpression),
    new CodeAction(editFactory, document, binaryExpression));

Rebuild and run the project to launch a new instance of Visual Studio with our extension loaded. Notice that the code issue now provides a drop down with the option to invoke our code action to fix the issue.

We have implemented an extension to Visual Studio that will help us improve our code.

About the author

Brian is a Senior SDET at Microsoft working on the C# and VB language services in Roslyn. Before joining Microsoft Brian was a Microsoft MVP for Visual C# for four years. Brian can be found on Twitter (@kodehoved).

Start Coding for the Kinect

CSharpFAQ — Mon, 06 Feb 2012 15:00:00 GMT

by Alan Berman

I'm intrigued by all the interesting industry apps being developed for the Kinect. I started wondering how easy it is to start programming the Kinect using Visual Studio on a PC. It is very easy to get started, especially since the Kinect SDK has sample applications with sample code.

Because I had bought a Kinect bundled with my Xbox and not a standalone Kinect, I needed to buy a Kinect Sensor Power Supply, which can be purchased online. This product has a cable with a USB connector that can be plugged into a PC.

I downloaded the Kinect SDK from the Kinect for Windows download site. After installation of the Kinect SDK, this appears in Start / All Programs.

When you choose "Kinect SDK Sample Browser", the following Sample Browser window appears. You can run the samples and download the associated C# projects from the window.

Here's what the Kinect Explorer looks like.

In the above window, the image at the left demonstrates skeletal tracking. The same image also shows Norm Estabrook as seen from the RGB camera. For the image at the right, depth camera data with the distance from the Kinect is translated into an image with different colors.

You can change settings by clicking the arrow at the lower left.

Here's what the Shape Game looks like. Norm is trying to change the direction of shapes falling from the sky. The app also supports vocal commands.

The Kinect Audio Demo looks like this. It shows the direction of the sound source and recognizes spoken colors.

The Kinect SDK includes the C# code for these sample apps, which will help you start coding.

Another important resource is the phenomenal Getting Started videos at the Kinect for Windows Quickstart Series. Happy coding!

Roslyn CTP Introduces Interactive Code for C#

CSharpFAQ — Tue, 31 Jan 2012 00:22:00 GMT

There's been a lot of posts on using the Roslyn CTP APIs for syntax trees, semantic binding, and IDE smart editor features. The Roslyn CTP also introduces a set of features for C# we refer to as "Interactive". These features won't be new to VB, but we plan to bring the same feature set to VB. Interactive features comprise three goals:

· Read-eval-print loop (long known as a REPL) -- to support exploring code, learning about APIs, and iterative development

· Keep simple programs simple -- just write some top-level variable declarations, statements, and function declarations, then run the code as a text-based asset without needing a solution, project, class, Main, etc.

· Roslyn Scripting APIs -- to support .NET apps hosting a C# engine to execute snippets or files of code to script the application

This post talks about the Interactive features in the Roslyn CTP, which is only supported for C# right now, but we are working on VB support for a future release.

Interactive code is a set of language and tooling features that enable customers to interactively explore and discover C# and VB readily. You do not have to create a solution, then a project, then a class, then a Main method and finally then get to write the few lines you care about. Users can open a tool window in VS and start typing code snippets to see what they do. You can build up execution context cumulatively by defining variables and functions, executing statement, defining types, and building up data structures. You can also seed the REPL's execution context from a project so that you can explore instantiating types from the project and trying out new snippets of code or develop a new function or integrity check on the data structures used in the project. This sort of development has been a hallmark of dynamic languages for decades and considered to be one of the most productive features related to dynamic languages.

Some getting started walkthroughs:

Executing Code in the Interactive Window

Seeding the Interactive Window from a WPF Project

For a quick example, using View->Other Windows->C# Interactive and starting to type a reference, you get completion:

After finishing the previous input and hitting enter to execute it, if you start to type MessageBox, you get a quick fix for inserting the 'using' and then completion to help with enter a call to Show().

When using the REPL to iteratively develop code, you may start with simple expression or statement snippets of code. You might be just checking how to call a .NET function correctly, or making a change to live code and data structures, then writing a snippet to check whether the change occurred as expected. You might build up helper functions that, for example, either help you recreate execution context for experimenting in another REPL session or help you repeat integrity checks as you experiment with an algorithm. You can save helper code away in .csx files or in your project for later evaluation and use in the REPL. Your code snippets might grow into a little program or utility that you want to run now and then, which you can save in a .csx file. You can #load .csx files in the REPL to re-execute the same code at a later time.

An important aspect of the Interactive feature set is enabling you to keep simple programs simple. If you have a quick, one-off task that just needs, say, 10-20 lines of code to open a file, manipulate some data, or test some code, you can open a .csx file and write the code you need. Then run the code with csi.exe. You do not have to jump through the VS ceremonial hoops to create a program, compile it, then execute the resulting .exe. By default, csi.exe uses the same references and 'using's that a console application uses, but you can use #r to add other references in your script file. A script file is a self-contained simple program that may have started as little snippets of code in the REPL. When you invoke csi.exe, you can pass multiple .csx files (and even .cs files) on the command line which is useful if you have a library of top-level functions you commonly use with different main scripts that use the library. The whole idea is to let you work in a simple way when simple text-based code assets are easy to manage or execute as part of a build script, file utility, etc.

Lastly, with the ability to execute snippets of code and cumulatively build up execution context, it is very natural to want to host the C# execution engine as a way to enable scripting of your .NET applications. You can then take snippets of code or files from users and execute them in a context where free identifiers are bound to public members on a host object model instance. The host application can decide what to expose to user script code for controlling the application, adding commands, or hooking events.

Scripting walkthroughs:

Introduction to Scripting

Scripting a Paint-like Application

You can download the “Roslyn” CTP and try it out today! The REPL installs as a new tool window in VS 2010.

Using Async for File Access

CSharpFAQ — Mon, 23 Jan 2012 17:00:00 GMT

by Alan Berman

The new Async feature in Visual Studio makes it easy to code asynchronous method calls. To make synchronous code asynchronous, you can simply call an asynchronous method instead of a synchronous method and add a few keywords to the code, as shown in the examples below. You no longer need to define continuations to capture what happens when the asynchronous operation finishes, which can otherwise complicate the code.

Even with the simplicity, why make file access calls asynchronous? Aren't they fast enough already? Here are reasons to consider:

Asynchrony makes UI applications more responsive. It allows the UI thread that launches the operation to be used for other things. If the UI thread is blocked by executing code that takes a long time (i.e. more than, say, 50 milliseconds), the UI may freeze until the I/O is complete and the UI thread is again able to process keyboard and mouse input and other events.
Asynchrony improves the scalability of ASP.NET and other server-based applications by reducing the need for threads. If file operations are synchronous and a hundred file access operations are happening at once, then a hundred threads are needed. Asynchronous operations often do not require use of a thread during the wait. They use the existing I/O completion thread briefly at the end.
Even though a file access operation has very low latency now, it's possible that latency may greatly increase in the future. For example, a file may later be moved to a server that's across the world.
The added overhead of using the Async feature is small.
Asynchronous tasks can easily be run in parallel.

Running the Examples

Note: The examples in this blog do not apply to Metro style apps, which are Windows 8 applications that are tailored for touch interaction and are full screen. For information on using Async for file access in Metro style apps, see .NET for Metro style apps overview and File and Stream I/O. For some good examples of Metro file I/O, you can download the File Access Sample provided on the Dev Center.

The examples below run in either Visual Studio 11 Developer Preview or the Async CTP for Visual Studio 2010 SP1. Both can be accessed from Visual Studio Asynchronous Programming. If you use the Async CTP for Visual Studio 2010, add a reference to AsyncCtpLibrary.dll, which is in My Documents\Microsoft Visual Studio Async CTP\Samples.

Include the following using statements in the console examples below.

using System;
using System.Collections.Generic;
using System.IO;
using System.Text;
using System.Threading.Tasks;

Use of the FileStream Class

The examples below use the FileStream class, which has an option that causes asynchronous I/O to occur at the operating system level. In many cases, this will avoid blocking a ThreadPool thread. To enable this option, you must specify the useAsync=true or options=FileOptions.Asynchronous argument in the constructor call.

StreamReader and StreamWriter do not have this option if you open them directly by specifying a file path. StreamReader/Writer do have this option if you provide them a Stream that was opened by the FileStream class. Note that asynchrony provides a responsiveness advantage in UI apps even if a thread pool thread is blocked, since the UI thread is not blocked during the wait.

Writing Text

The following example writes text to a file. At each await statement, the method immediately exits. When the file I/O is complete, the method resumes at the statement following the await statement. Note that the async modifier is in the definition of methods that use the await statement.

static void Main(string[] args)
{
    ProcessWrite().Wait();
    Console.Write("Done ");
    Console.ReadKey();
}

static Task ProcessWrite()
{
    string filePath = @"c:\temp2\temp2.txt";
    string text = "Hello World\r\n";

    return WriteTextAsync(filePath, text);
}

static async Task WriteTextAsync(string filePath, string text)
{
    byte[] encodedText = Encoding.Unicode.GetBytes(text);

    using (FileStream sourceStream = new FileStream(filePath,
        FileMode.Append, FileAccess.Write, FileShare.None,
        bufferSize: 4096, useAsync: true))
    {
        await sourceStream.WriteAsync(encodedText, 0, encodedText.Length);
    };
}

Reading Text

The following example reads text from a file. The text is buffered and, in this case, placed into a StringBuilder. Unlike in the previous example, the evaluation of the await produces a value. The ReadAsync method returns a Task<Int32>, so the evaluation of the await produces an Int32 value (numRead) that is returned after the operation completes..

static void Main(string[] args)
{
    ProcessRead().Wait();
    Console.Write("Done ");
    Console.ReadKey();
}

static async Task ProcessRead()
{
    string filePath = @"c:\temp2\temp2.txt";

    if (File.Exists(filePath) == false)
    {
        Console.WriteLine("file not found: " + filePath);
    }
    else {
        try {
            string text = await ReadTextAsync(filePath);
            Console.WriteLine(text);
        }
        catch (Exception ex)
        {
            Console.WriteLine(ex.Message);
        }
    }
}

static async Task<string> ReadTextAsync(string filePath)
{
    using (FileStream sourceStream = new FileStream(filePath,
        FileMode.Open, FileAccess.Read, FileShare.Read,
        bufferSize: 4096, useAsync: true))
    {
        StringBuilder sb = new StringBuilder();

        byte[] buffer = new byte[0x1000];
        int numRead;
        while ((numRead = await sourceStream.ReadAsync(buffer, 0, buffer.Length)) != 0)
        {
            string text = Encoding.Unicode.GetString(buffer, 0, numRead);
            sb.Append(text);
        }

        return sb.ToString();
    }
}

Control Flow

While it's easy to make method calls asynchronous, it helps to know what actually happens when the program reaches an await statement.

The original example had the statement "await sourceStream.WriteAsync...". That's a contraction of these two statements: "Task theTask = sourceStream.WriteAsync…" and "await theTask". The first statement causes a task to be returned and file processing to start. The second statement with the await causes the method to immediately exit (returning a different task). When the file processing later completes, execution returns to the statement following the await.

The following example does the same thing as the "Writing Text" example, however it splits the await statement into two statements and adds console output to assist in understanding the sequence.

static void Main(string[] args)
{
    ProcessWrite2().Wait();
    Console.Write("Done ");
    Console.ReadKey();
}

static Task ProcessWrite2()
{
    string filePath = @"c:\temp2\temp2.txt";
    string text = "Hello World\r\n";

    Task theTask = WriteTextAsync2(filePath, text);

    ShowInfo(theTask, "In ProcessWrite2 before wait");
    return theTask;
}

static async Task WriteTextAsync2(string filePath, string text)
{
    byte[] encodedText = Encoding.Unicode.GetBytes(text);

    using (FileStream sourceStream = new FileStream(filePath,
        FileMode.Append, FileAccess.Write, FileShare.None,
        bufferSize: 4096, useAsync: true))
    {
        Task theTask = sourceStream.WriteAsync(encodedText, 0, encodedText.Length);

        ShowInfo(theTask, "In WriteTextAsync2 before await");
        await theTask;
        ShowInfo(theTask, "In WriteTextAsync2 after await");
    };
}

static void ShowInfo(Task theTask, string message)
{
    Console.Write(message.PadRight(32) + " ");
    Console.Write("task " + theTask.Id.ToString() + " ");
    Console.Write("\n");
}

// Console output:
// In WriteTextAsync2 before await task 1
// In ProcessWrite2 before wait task 2
// In WriteTextAsync2 after await task 1
// Done

Parallel Asynchronous I/O

The following example demonstrates parallel processing by writing 10 text files. For each file, the WriteAsync method returns a task. Each task is added to a list of tasks. The "await Task.WhenAll(tasks)" statement exits the method and resumes within the method when file processing is complete for all of the tasks.

For the Visual Studio 2010 Async CTP, use TaskEx.WhenAll instead of Task.WhenAll.

The example closes all FileStream instances in a finally block after the tasks are complete. If each FileStream was instead created in a using statement, the FileStream might be disposed of before the task was complete.

Note that any speedup is almost entirely from the parallel processing and not the asynchronous processing. The advantages of asynchrony are that it does not tie up multiple threads, and that it does not tie up the user interface thread.

static void Main(string[] args)
{
    ProcessWriteMult().Wait();
    Console.Write("Done ");
    Console.ReadKey();
}

static async Task ProcessWriteMult()
{
    string folder = @"c:\temp2\";
    List<Task> tasks = new List<Task>();
    List<FileStream> sourceStreams = new List<FileStream>();

    try {
        for (int index = 1; index <= 10; index++)
        {
            string text = "In file " + index.ToString() + "\r\n";

            string fileName = "thefile" + index.ToString("00") + ".txt";
            string filePath = folder + fileName;

            byte[] encodedText = Encoding.Unicode.GetBytes(text);

            FileStream sourceStream = new FileStream(filePath,
                FileMode.Append, FileAccess.Write, FileShare.None,
                bufferSize: 4096, useAsync: true);

            Task theTask = sourceStream.WriteAsync(encodedText, 0, encodedText.Length);
            sourceStreams.Add(sourceStream);

            tasks.Add(theTask);
       }
    
        await Task.WhenAll(tasks);
    }

    finally {
        foreach (FileStream sourceStream in sourceStreams)
        {
            sourceStream.Close();
        }
    }
}

The WriteAsync and ReadAsync methods allow you to specify a CancellationToken, which can be used to cancel the operation mid-stream. The Simultaneous Async Tasks blog has an example of cancellation. Additional information is provided in the Cancellation topic.

Thanks to Stephen Toub for providing technical guidance.

See Also

Resources

Introduction to the Roslyn Scripting API

CSharpFAQ — Fri, 02 Dec 2011 20:56:00 GMT

by Brian Rasmussen

In this post we take a look at how the Roslyn Scripting API can enable applications to evaluate code at runtime. While this has been possible since the dawn of .NET through the use of Reflection, Lightweight Code Generation, CodeDom, etc., it has never been particularly easy. All of these mechanisms are either hard to use, require MSIL knowledge, or just have inherent limitations.

Roslyn not only makes dynamic code evaluation a lot easier, it also provides the necessary APIs to implement a fully featured scripting experience. This post covers the basics of the Scripting API in Roslyn. For an example of how Roslyn can be used to implement a rich environment for entering and executing code at runtime take a look at the C# Interactive window implemented in the Roslyn CTP. The C# Interactive window provides syntax highlighting, intellisense, and even refactoring for code supplied at runtime.

This post uses C# as an example because that is what Roslyn supports for scripting in this first CTP.

The Basics

Let’s start by looking at a very simple example. Let’s just execute some code dynamically. To do that all we need is an instance of the ScriptEngine class. Specifically we need the C# version defined in Roslyn.Scripting.CSharp. All we have to do is create an instance of ScriptEngine and call the Execute method with the code to be evaluated. The Roslyn scripting version of Hello World is as simple as:

using Roslyn.Scripting.CSharp;
 
namespace RoslynScriptingDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var engine = new ScriptEngine();
            engine.Execute(@"System.Console.WriteLine(""Hello Roslyn"");");
        }
    }
}

The solution needs references to Roslyn.Compilers and Roslyn.Compilers.CSharp.

Notice, we did not have to use APIs that take MSIL or that carefully build up a tree of code that then needs to be compiled and executed. We can simply send the ScriptEngine text snippets of the code we write all the time. The ScriptEngine takes care of the rest to execute it.

Execution Context

Unfortunately the code above does have a few limitations. The first of which is that there’s no cumulative execution context, so if we define a variable as part of one code snippet and then try to access the variable from another code snippet, we will get an exception. For example, if we change the body of Main to something like this:

var engine = new ScriptEngine();
 
engine.Execute(@"var a = 42;");
engine.Execute(@"System.Console.WriteLine(a);");

We will get a compilation error from the scripting engine as the statements are treated as separate compilations. Fortunately, the Scripting API provides the Session type that can be used as an execution context when calling Execute. A session stores the context of a series of submissions, so by providing a session we can execute the code above and get the expected result.

using Roslyn.Scripting.CSharp;
using Roslyn.Scripting;
 
namespace RoslynScriptingDemo
{
    class Program
    {
        static void Main(string[] args)
        {
            var engine = new ScriptEngine();
            var session = Session.Create();
 
            engine.Execute(@"var a = 42;", session);
            engine.Execute(@"System.Console.WriteLine(a);", session);
        }
    }
}

We can even define a new method, store it in the session, and then invoke it like this.

engine.Execute(@"void Foo() { System.Console.WriteLine(""Foo""); }", session);
engine.Execute(@"Foo();", session);

Interacting with the Host Application

However, we still cannot interact with the hosting application. Obviously scripting is of limited use if the user supplied code cannot interact with the application somehow. To address this we need to provide a host object to the session.

The code submissions will automatically have access to any public members of the host object. To supply a host object, we pass in an instance of any type we would like to use as an interface between the host application and the session. Furthermore, we have to make the ScriptEngine aware of this type as well. To do that we pass in a reference to the assembly defining our host object type. With that the setup code now looks as follows:

var hostObject = new HostObject();
var engine = new ScriptEngine(new[] { hostObject.GetType().Assembly.Location });
var session = Session.Create(hostObject);

The host object can be of any type. The ScriptEngine binds any free identifier to public members of the type, as if the type's member names were globally accessible from the script. For the sake of this demo, let’s just make it as simple as possible.

public class HostObject
{
    public int Value = 0;
}

With the code above, we can now access the Value field on our hostObject instance like this:

engine.Execute(@"Value = 42;", session);
engine.Execute(@"System.Console.WriteLine(Value);", session);

Notice how the instance's members are implicitly available within the session. We simply access any public member on the instance.

The examples we have been looking at so far are really simple, so let’s round off this introduction by adding some functionality that resembles what an application might do with the scripting API. Imagine we have a Report type like the one listed below.

// This will act as our host object
public class Report
{
    // Internal state
    private readonly List<int> values = new List<int>();
    private int result;
 
    // Encapsulate the internal data structure
    public void AddValue(int value)
    {
        values.Add(value);
    }
 
    // Allow read-only enumeration of values
    public IEnumerable<int> Values { get { return values; } }
 
    // User code will provide the implementation for these methods
    public Action GetValues;
    public Func<int> CalculateResult;
 
    // This method may be called by both the host application and the user code
    public void PrintResult()
    {
        var get = GetValues;
        if (get != null)
        {
            get();
        }
 
        var calc = CalculateResult;
        if (calc != null)
        {
            result = calc();
        }
 
        Console.WriteLine("The result of the calculation is {0}", result);
    }
}

The class stores an internal list of numbers and a result. It provides an AddValue method to populate the list and a read-only iterator. The result can be printed by calling the PrintResult method. User-supplied code determines how the list is actually populated and how the result is calculated.

The Report class exposes two delegate types, GetValues and CalculateResult for this purpose. When PrintResult is called it invokes the delegates to populate the list of values and calculate the result. Our simple application may look something like this:

static void Main(string[] args)
{
    var report = new Report();
    var engine = new ScriptEngine(new[] { 
        "System.Core", report.GetType().Assembly.Location });
    var session = Session.Create(report);
 
    engine.Execute(@"using System.Linq;", session);
    engine.Execute(
        @"GetValues = () => { for(int i = 1; i <= 3; i++) AddValue(i); };",
        session);
    engine.Execute(@"CalculateResult = () => Values.Sum();", session);
 
    report.PrintResult();
}

Admittedly this is still a simple example, but it does illustrate how script code can be used to customize our host application.

Notice how we can assign anonymous methods to the delegate members, and the host application can call them. Also, notice how we can access the LINQ extension method Sum in the user supplied code. To enable this we need to let ScriptEngine reference System.Core and import the System.Linq namespace.

That completes the overview of how to use Roslyn to add scripting support to an application. For more information on the Roslyn Scripting API please see the walkthroughs and The Roslyn Project Overview.

About the author

Using the Roslyn Symbol API

CSharpFAQ — Wed, 23 Nov 2011 23:10:38 GMT

by Kevin Pilch-Bisson

I’m back again, to move along to the next stage of the compiler pipeline, and take a look at working with Symbols in the using the Roslyn CTP.

The Roslyn CTP’s symbol API provides a top-down view of all the symbols available. Before we get to symbols though, we need to start looking at how to give the compiler enough context to tell us about symbols. While syntax trees are mostly context free and can stand on their own, in order to learn about symbols we need to have a collection of syntax trees, the references passed to the compiler, and any options in effect. In Roslyn, we use the Compilation type to group these things together. Conceptually, a Compilation represents one invocation of the csc.exe command line, or a single project in Visual Studio.

Let’s start by creating a compilation that includes something like the simple file we used last time when talking about syntax trees:

using System;
using System.IO;
using System.Linq;
using Roslyn.Compilers;
using Roslyn.Compilers.CSharp;

class Program
{
    static void Main(string[] args)
    {
        var syntaxTree = SyntaxTree.ParseCompilationUnit(@"
class C
{
    static void Main()
    {
        if (true)
            Console.WriteLine(""Hello, World!"");
    }
}");

        var compilation = Compilation.Create("test.dll",
            syntaxTrees: new[] { syntaxTree },
            references: new []
                {
                    new AssemblyFileReference(typeof(object).Assembly.Location),
                    new AssemblyFileReference(typeof(Enumerable).Assembly.Location),
                });
    }
}

Aside: You’ll find that many parts of the Roslyn APIs use optional arguments, and it’s convenient to call them with named parameters. The reason for this is that we’re exposing an immutable API, so we want to allow you to specify all the options right at creation time, but we don’t want to force you to type them all. In a mutable model, we’d probably leave many of these things out of the constructors/factory methods and allow you to set them via properties.

Now that we’ve got a Compilation, what are the interesting things to do with it? Well, there are a few.

“Change” it

Like SyntaxTrees and many other parts of the Roslyn API, Compilations are immutable, so we can’t really change them. However, there are methods like AddReferences() and RemoveSyntaxTrees(), that will return a new Compilation object with those changes (just like string.Append)

Find errors and warnings

The Compilation object makes it possible for us to programmatically determine what errors and warnings exist in a piece of code. There are two different APIs for this on the Compilation object. First of all you can call GetDiagnostics, which returns all of the errors for the Compilation. This requires doing a significant amount of work (almost as much as just compiling), so it can take a while.

In addition to GetDiagnostics, the Compilation has a method named “GetDeclarationDiagnostics”. This is meant to be a somewhat less expensive call, and one that doesn’t throw away the results of its work. You can think of the declaration diagnostics as all the errors that happen outside the curly braces of method bodies and property accessors. Finding them requires completely filling out the symbol table of the Compilation, but it doesn’t require looking at method bodies. In contrast, GetDiagnostics first calculates the declaration diagnostics, and then binds each method body in turn. Keeping the fully bound form of every method would take a lot of memory for a large Compilation, and so the bound information is released once the diagnostics have been collected.

var diagnostics = compilation.GetDiagnostics();
foreach (var d in diagnostics)
{
    var lineSpan = d.Location.GetLineSpan(usePreprocessorDirectives: true);
    var startLine = lineSpan.StartLinePosition.Line;
    Console.WriteLine("Line {0}: {1}", startLine, d.Info.GetMessage());
}

Compile it!

We can write out the bytes to an assembly using Emit(). In case we want to Emit if possible, and display diagnostics if not, the Emit call returns a result that includes the diagnostics. This means that we can skip a call to GetDiagnostics before trying Emit, which means that nothing has to look at each method body twice.

using (var file = new FileStream("test.dll", FileMode.Create))
{
    var result = compilation.Emit(file);
}

Examine the symbol table

One of the most interesting things we can do is look at the symbol table and examine the types and members inside of it, sort of the way you would do with Reflection.

To examine every type in the Compilation, you can start with the GlobalNamespace property of the Compilation. One thing to note is that the Compilation’s GlobalNamespace is what the compiler uses when doing lookups, so it includes everything defined in the Compilation and in its references. If you want to see only things that are actually defined in the Compilation, you can look at the “Assembly.GlobalNamespace” instead. Let’s look at an example where we find every member that contains the letter “a” in its name:

ReportMethods(compilation.Assembly.GlobalNamespace);

and

private static void ReportMethods(NamespaceSymbol namespaceSymbol)
{
    foreach (var type in namespaceSymbol.GetTypeMembers())
    {
        ReportMethods(type);
    }

    foreach (var childNs in namespaceSymbol.GetNamespaceMembers())
    {
        ReportMethods(childNs);
    }
}

private static void ReportMethods(NamedTypeSymbol type)
{
    foreach (var member in type.GetMembers())
    {
        if (member.CanBeReferencedByName &&
            member.Name.Contains("a"))
        {
            Console.WriteLine("Found {0}", member.ToDisplayString());
        }
    }

    foreach (var nested in type.GetTypeMembers())
    {
        ReportMethods(nested);
    }
}

Note the handy “CanBeReferencedByName” property, which saves us from including things like accessor methods for a property, that exist in the symbol table, but which users aren’t allowed to actually name. Also, take note of the “ToDisplayString()” extension method, which allows you to generate various forms of symbol names, including some human readable ones.

Alternatively, if there is a specific type you want to find, you can use the GetTypeByMetadataName method. We needed a way to represent fully qualified names type names that include generic arity and nestedness. Rather than define our own format, we decided to use the metadata format, which means that to use this API, you’ll need to use + to separate nested types, and encode the generic arity with `n where n is the number of type arguments. For example, to look up the nested Enumerator type in List<T>, we’d use a string like “System.Collections.Generic.List`1+Enumerator”.

One question we get is that if this model is similar to reflection, why isn’t it easier to get to the System.Type for a TypeSymbol? The reason is that the compiler may be targeting a different runtime than the one that your code is running on – consider a compilation for a Silverlight project for example. There is no way to load a System.Type for some type in the reference assembly to mscorlib.dll. At best you would find the corresponding System.Type in the desktop CLR, which may or may not be what you need.

Analyze specific parts of it

It may be interesting to pick a particular expression and see what method is going to be invoked, or similar semantic questions. We’ll look at this in more detail in the next post, but if you want to get a head start, take a look at the GetSemanticModel method on Compilation, and it’s resulting SemanticModel object.

Roslyn Syntax Visualizers

CSharpFAQ — Sat, 19 Nov 2011 02:20:00 GMT

Hi All! A few weeks ago, we announced the Microsoft "Roslyn" CTP. I hope many of you have had a chance to download the CTP and take it for a spin :) If you haven’t, do give it a try.

To recap – in the Roslyn CTP, we are previewing a powerful set of language services APIs that you can use within your apps to reason about C# and VB code. We are also previewing IDE extensibility points for C# and VB that will allow you to build rich code refactorings, quick fixes etc. that run inside Visual Studio.

In this post, I just wanted to point out a couple of tools that you may be interested in if you are working with the CTP – the Roslyn Syntax Visualizers. You can read more about these visualizers and how to install and use them on the following blog post – http://blogs.msdn.com/b/visualstudio/archive/2011/10/19/roslyn-syntax-visualizers.aspx

The visualizers ship as samples in the CTP and allow you to visually inspect and explore Roslyn Syntax Trees (below screenshot shows an example). You can use these visualizers as debugging aids when you develop your own applications / code refactorings using the Roslyn APIs.

Happy Coding! :)

Shyam Namboodiripad
Software Development Engineer in Test (Roslyn Compilers Team)

Using the Roslyn Syntax API

CSharpFAQ — Thu, 03 Nov 2011 21:51:42 GMT

By Kevin Pilch-Bisson

As promised back when we released the Roslyn CTP, here is the first of a series of blog posts that help explain the various parts of the Roslyn API. If you don’t have the Roslyn CTP, you can get it from our MSDN page, and install it on top of Visual Studio SP1 and the VSSDK. If you want to get into using the Roslyn CTP seriously, I highly recommend taking a look at the overview document, and the various walkthroughs that we’ve put together.

Properties

The Syntax API in Roslyn has three two key properties. First, it is a full-fidelity model. Every character of a source file is represented in the API, which means that it also round trips. You can parse a source file, call ToString on the resulting SyntaxTree and get the original file text back.

Key Types

The key types in the Syntax API of the Roslyn CTP are: SyntaxNode, SyntaxToken and SyntaxTrivia. SyntaxNode represents a non-terminal node in the language grammar, and is an immutable object. There are a variety of different derived types for different language elements, and also a Kind property that identifies what a particular SyntaxNode represents. SyntaxNodes are arranged into a tree, connected by the Parent and ChildNodes properties. Each type derived from SyntaxNode also includes named properties for element of that particular node type. For example, an IfStatementSyntax has properties for the IfToken, OpenParenToken, Condition, CloseParenToken, Statement, and ElseClauseOpt.

SyntaxToken objects represet the terminals of the language grammar. They never have children, but do have a Parent property that is always a SyntaxNode. For performance reasons, SyntaxToken is a struct type. You can use the Kind property to determine what sort of token something is.

Finally, things like whitespace and comments that can appear anywhere in a source file are represented as SyntaxTrivia. Each SyntaxTrivia is attached to a single token, as either LeadingTrivia or TrailingTrivia. SyntaxTrivia does not have a parent property, but it is possible to get the associated token via the Token property. Like SyntaxToken, SyntaxTrivia is a struct for performance reasons.

Parsing

Okay, enough talk, let’s see some code. First off, let’s see how we can get a hold of the SyntaxTree, and what it looks like. To start off with, you can parse some text using SyntaxTree.ParseCompilationUnit:

using System;
using System.Linq;
using Roslyn.Compilers;
using Roslyn.Compilers.CSharp;

class Program
{
    static void Main(string[] args)
    {
        var syntaxTree = SyntaxTree.ParseCompilationUnit(@"
using System;
class C
{
    static void M()
    {
        if (true)
            Console.WriteLine(""Hello, World!"");
    }
}");
        var ifStatement = (IfStatementSyntax)syntaxTree.
            Root.
            DescendentNodes().
            First(n => n.Kind == SyntaxKind.IfStatement);
        Console.WriteLine("Condition is '{0}'.", ifStatement.Statement);
    }
}

In this example, we parse some simple text and look at the resulting SyntaxTree. In this case, we search through the syntax tree looking for IfStatements and grab the first one we find. We cast that the the more strongly typed IfStatementSyntax type, and then we can look at the properties specific to if statements. In this case, we looked at “Statement” which is a SyntaxNode that represents the statement to execute if the condition is true.

Construction

Sometimes you don’t want to parse existing source code to build up a SyntaxTree. Instead you want to create brand new SyntaxNodes. The most common case for this is that you want to add or change some existing syntax, and you need the new things to transform to. With the Roslyn CTP, the way you create new SyntaxNode objects is through the set of factory methods on the “Syntax” class.

var newStatement = Syntax.ExpressionStatement(
    Syntax.InvocationExpression(
        Syntax.MemberAccessExpression(
            SyntaxKind.MemberAccessExpression,
            Syntax.IdentifierName("Console"),
            name: Syntax.IdentifierName("WriteLine")),
        Syntax.ArgumentList(
            arguments: Syntax.SeparatedList<ArgumentSyntax>(
                Syntax.Argument(
                    expression: Syntax.LiteralExpression(
                        SyntaxKind.StringLiteralExpression,
                        Syntax.Literal(
                            text: @"""Goodbye everyone!""",
                            value: "Goodbye everyone!")))))));

Here, we’re constructing a new statement to represent a call to “Console.WriteLine("Goodbye everyone!");”. As you can see, this involves specifying quite a lot of detail. That’s one of the drawbacks of a full-fidelity model, it also means that you need specify all of those details when you create things. If you look closely, you can also see that in some places I’m using C# 4.0’s named arguments. The reason for this is that many parameters in the Syntax construction APIs are defined to be optional. The reason for optional parameters is that when possible, you don’t need to specify a detail. For example, many tokens are always exactly the same (like keywords, punctuation, etc). If you omit an argument for them, a default version will be constructed for you. If you’d like, you CAN specify every token, including triva for each one.

One thing you can do to reduce the verbosity is to sneak in calls to the various Syntax.Parse?? methods for elements of structure you are building up. This way, you can inline the code you want to have in a string instead of specifying the entire structure.

Rewriting

The next major piece of functionality in the Syntax API is re-writing, or modifying syntax trees. There are two approaches to this. The simplest is to just use one of the Replace APIs on SyntaxNode. The idea is that you get back a new tree, but with one of the descendants replaced.

var newTree = syntaxTree.Root.ReplaceNode(
    ifStatement.Statement,
    newStatement).Format();

Console.WriteLine(newTree);

We’ve successfully replace the body of the if statement. Because the trees are immutable, the original “SyntaxTree.Root” is completely unaffected. The newTree variable really is a brand new tree, but under the covers we actually re-use a lot of the data in an invisible fashion to be more efficient both in time and memory. Of note in the sample is the call to “Format()” on the new tree, which will apply a default formatting, and ensure that there is whitespace where there needs to be for the tree to round trip.

In some cases where you want to re-write multiple nodes, you might want more control over how the tree gets changed. To support this, the Roslyn CTP includes an abstract SyntaxRewriter class. I’ll give you a simple example that rewrites the tree above so that “M” is named “Main”, but there are obviously more interesting things that can be done here:

class Rewriter: SyntaxRewriter
{
    protected override SyntaxToken VisitToken(SyntaxToken token)
    {
        if (token.Kind != SyntaxKind.IdentifierToken ||
            token.GetText() != "M")
        {
            return token;
        }

        return Syntax.Identifier("Main");
    }
}

And you can use it like this:

var rewriter = new Rewriter();
newTree = rewriter.Visit(newTree);
Console.WriteLine(newTree);

In this example, I’ve only used “VisitToken”, but there are actually a TON of “Visit” methods that you can override to rewrite specific types of nodes in a tree.

Closing

We’ve taken a brief look at some of the key concepts and types of the Syntax portion of the API in the Roslyn CTP, including parsing, constructing node from scratch, and rewriting existing nodes. Next time, we’ll move to the next stage of the compilation pipeline, and take a look at how Symbols are exposed in Roslyn.

Introducing the Microsoft “Roslyn” CTP

CSharpFAQ — Wed, 19 Oct 2011 21:00:00 GMT

By Kevin Pilch-Bisson

As Soma mentioned earlier, today we’ve made a Community Technology Preview (CTP) available for download! The Roslyn project is a forward looking effort to make the wealth of language understanding that the compiler generates available to developers in other scenarios. A number of us have been working hard on getting enough of these pieces put together to have something to share with you, and we’re thrilled to be able to do that today.

The foundation of this work is a new C# compiler, written in C# (and a new VB compiler written in VB too, see the VB Team blog for details). This compiler is written as a library that exposes a rich public API. Next up is a new language service written purely using that public API and exposing its own extensibility points to allow 3^rd parties to do amazing things inside Visual Studio with that language understanding.

Resources

The Visual Studio blog gives a good overview of the various pieces that the CTP installs, but I thought I’d use this space to look at a little more code that uses the API.

The Roslyn MSDN page contains pointers to an overview document that explains the basic concepts in the Roslyn API in greater detail. There are also several guided walkthroughs that each dive deeper into a particular area of the API. Finally if you install the CTP, there are numerous samples installed to the “My Documents” folder that you can build, run and experiment with.

Watch this space in the next few weeks for a series of posts that will each explore one bit of the API.

Feedback

We’re very interested in your feedback about the Roslyn project! Because it’s early in the project we’re most interested in feedback about the API and general direction. Please get involved in the discussion about Roslyn on our forums. You can also file bugs on our Connect site. Finally, some of the team members are also on Twitter, and will be keeping an eye on the #RoslynCTP hashtag if that is more convenient for you.

Disclaimer

Please note: This is a technology preview and there are known limitations. While the shape of the public API surface is complete, only a subset of the C# and Visual Basic languages have been implemented at this time in the current CTP.

About the author

Kevin is a Development lead at Microsoft responsible for the C# and VB language services in Roslyn. He’s been at Microsoft for 9 years, and has spent all of it working in the language and IDE space. Kevin is a graduate of the University of Waterloo. He used to blog at http://blogs.msdn.com/b/kevinpilchbisson, but has been spending more time on Twitter (@Pilchie) and on getting Roslyn into your hands lately.

C# 2010 Soup to Nuts Series

CSharpFAQ — Thu, 01 Sep 2011 00:02:00 GMT

By Emily Gibson

New! C# 2010 Soup to Nuts Series

Explore this webcast series on Visual C# 2010 presented by Developer Evangelist, Bill Steele. Learn about class libraries, operator basics, branching and looping, and more as Bill dives deep into this fantastic language.

Part 1: Introduction

WMV Download | Zune | WMA | MP3

Watch this Entire Series:

Part 1: Introduction
Part 2: Visual C# Express
Part 3: Class Libraries
Part 4: Visual C# Program Structure
Part 5: Language Fundamentals
Part 6: Branching and Looping
Part 7: Classes and Objects
Part 8: Operator Basics
Part 9: Basic Debugging
Part 10: Arrays and Collections

New Async Programming Videos

CSharpFAQ — Mon, 15 Aug 2011 18:36:04 GMT

Some great new video's on MSDN showing how to do async programming using the Async CTP.

http://msdn.microsoft.com/en-us/vstudio/hh378091.aspx

There are different versions of video's for both VB and C#. This is a great opportunity to see the power of the new Async languages featuresand follow through a series of examples showing how easy it is to use the new feature.

Also, the MSDN forums have one specifically dedicated to the Async CTP which compilers team member are monitoring to help answer any questions.

http://social.msdn.microsoft.com/Forums/en-US/async/threads

Spotty

Async CTP (SP1 Refresh)

CSharpFAQ — Wed, 13 Apr 2011 16:13:00 GMT

By Jeremy Meng

Visual Studio Async CTP (SP1 Refresh) is available now! You are welcome to download and try it out!

Thanks to the new Async feature coming in Visual Basic and C# it has never been so easy to write asynchronous code. With the newly introduced async and await keywords you can make asynchronous calls without having to create callback functions, sign them up to some ****Completed events, retrieve results from EventArgs by yourself. Visual Basic and C# compiler will do the plumbing work for you.

I hope that the following example can help you get basic ideas on how the Async feature makes writing responsive applications easier.

Here is a simple WPF application to get you started with Async in C#. This WPF app has a label, a button, and a checkbox on its UI. When the button is clicked, the application will perform a query over the network (for example, downloading files from the internet, querying data from a database, etc.) After the query is done, the label will be updated to show the length of the returned string data.

The event handler for button click:

private void button1_Click(object sender, RoutedEventArgs e)

{

UpdateLabel();

}

async void UpdateLabel()

{

NetworkClass nc = new NetworkClass();

int i = 0;

i = await nc.MethodQueryingNetworkAsync();

label1.Content = "Length: " + i;

}

The code for MethodQueryingNetworkAsync() is like below:

async public Task<int> MethodQueryingNetworkAsync()

{

// Querying a slow website with network latency so that

// the result comes back after a certain amount of time

WebClient wc = new WebClient();

string content = await wc.DownloadStringTaskAsync(
new Uri("http://some.slow.website/"));

return content.Length;

}

Run the application and click on the button, you will still be able to toggle the checkbox on UI while the network query is executing. When the downloading is finished, the label will be updated to show the length of the query result. During the query execution, the UI is completely responsive.

What’s new in Visual Studio Async CTP SP1 Refresh?

It is compatible with Visual Studio 2010 SP1 and Windows Phone 7. The previous Async CTP only works for Visual Studio 2010 RTM.
More efficient Async methods!

We changed the old pattern of GetAwaiter/BeginAwait/EndAwait with the new pattern of GetAwaiter/IsCompleted/OnCompleted/GetResult. This provides better performance especially if the task we are awaiting had already completed. We also make exception behaviors uniform in void-returning async methods (Async Subs in Visual Basic).

Many bug fixes since the release of the previous Async CTP. Thanks for the feedbacks from the community! Please let us know what you think!

For more details, read on Lucian’s blog. Welcome to Async and happy asynchronous coding!

How to programmatically launch Debugger in a remote machine

CSharpFAQ — Mon, 28 Mar 2011 18:37:39 GMT

This blog post explains how to kick off a debugger in a remote machine, programmatically. We are going to use WMI interfaces to achieve this. Use WMI, to start the debuggee process and attach a registered debugger to it using WMI. I have given a sample code below.

This Code assumes that we have the ConsoleApplication1 process running in the Machine1(debuggee Machine). On executing this code , the registered Debugger instance will be attached to “ConsoleApplication1” process. If you have multiple debuggers registered in the debuggee machine, then “Select Debugger” dialog would come up. We can use this method to attach Debugger to any kind of processes/services.

ConnectionOptions options = new ConnectionOptions();

ManagementScope scope = new ManagementScope("\\\\machine1\\root\\cimv2", options);

scope.Connect();

ObjectQuery oQuery = new ObjectQuery("Select * from Win32_Process where Name Like 'ConsoleApp%'");

//Execute the query

ManagementObjectSearcher objSearcher = new ManagementObjectSearcher(scope,oQuery);

//Get the results

ManagementObjectCollection objReturnCollection = objSearcher.Get();

foreach (ManagementObject oReturn in objReturnCollection)

{

if (oReturn["Name"].ToString().Equals("ConsoleApplication1.exe"))

{

object outparams = oReturn.InvokeMethod("AttachDebugger", null);

}

This code reads through the active processes in the remote machine using WMI, and there is a build method of invoking the process while attaching a debugger to it. To learn more about using WMI, here.

Visual Studio is Hiring

CSharpFAQ — Wed, 09 Feb 2011 00:55:00 GMT

Do you want to work on a product used by millions of developers around the world? I do! Come join me to deliver Visual Studio, the set of developer tools used across Microsoft and around the world. We have open positions available across Test, Dev and PM at varying levels on many projects across Visual Studio Professional. We’re looking for the most talented folks around to help us deliver the core parts of Visual Studio, from the Shell & IDE, languages (VB/C#/F#), packaging & setup, to our future investments in C# & VB.

Here are a list of our open positions. We love referrals, let your friends know they can work on Visual Studio too! To get more information, please submit your resume.

Visual Studio IDE/Platform Team

Team	Position
IDE/Platform	Software Development Engineer in Test 2
IDE/Platform	Software Development Engineer in Test 2
IDE/Platform	Software Development Engineer 2
IDE/Platform	Program Manager 2

Visual Studio Pro Experience

Team	Position
Pro Experience	Software Development Engineer in Test 2
Pro Experience	Software Development Engineer 2
Pro Experience	Program Manager 2
Pro Experience	Senior Program Manager
Pro Experience	Senior Software Development Engineer

Codename Roslyn (compiler as a service)

Team	Position
Roslyn	Software Development Engineer in Test Lead
Roslyn	Software Development Engineer 2

Visual Studio Project, Build & Windows focus

Team	Position
Visual Studio Tools	Software Development Engineer in Test 2

In case you’re not familiar with these core engineering roles at Microsoft, you can find more information out on the Microsoft Career Site. Here are short descriptions of the roles:

Program Managers (PMs) transform visions into elegant designs that ultimately turn into products and solutions. Or, put more simply, we anticipate what customers want and translate that into what they get. Working closely with development, test, user experience, and marketing professionals, we identify requirements, set priorities, manage feature sets across product lifecycles, and author technical specifications and customer scenarios.
Testers (Software Development Engineers in Test –SDETs) “build it to break it.” We push products to their limit, making sure they perform to customer expectations and conform to the highest quality standards. In partnership with developers and program managers, and using C, C++, C#, and VB.NET, we write test cases and plan, design, develop, and maintain automation tools that isolate and debug problems.
Developers (Software Development Engineers – SDEs) write the code—C, C++, C#, and other programming languages—that turns concepts into new technologies and services. We are experts in feature design and feasibility, and we collaborate with program managers and test engineers to define features and ensure quality.

I hope to hear from you soon!

Peter Hauge [MSFT]

Microsoft Help Viewer 1.1 - Updates Planned for Visual Studio 2010 SP1

Kathleen McGrath - MSFT — Mon, 08 Nov 2010 18:16:54 GMT

Learn about the upcoming changes to the Help Viewer planned for Visual Studio 2010 SP1. Paul O’Rear, a Program Manager on the Library Experience team, describes the changes planned and demonstrates the new functionality of the viewer in an early build of Help Viewer 1.1.

See Microsoft Help Viewer – Updates Planned for Visual Studio 2010 SP1

You can learn more in The Story of Help in Visual Studio 2010

--Kathleen

What’s Next in C#? Get Ready for Async!

Alexandra Rusina — Thu, 28 Oct 2010 17:19:00 GMT

Today we announced the Visual Studio Async CTP, which shows one of the major features we plan to include in a future release of C# and Visual Basic. This feature makes development of asynchronous applications--which include everything from desktop applications with responsive UI to sophisticated web applications--much easier.

The future release will introduce two new keywords to the C# language: await and async. The await keyword is used to mark asynchronous calls, so that you don’t need to create callback functions anymore and can write code in the same way as if it were synchronous. The compiler will do all of the heavy lifting for you. The async keyword must be presented in the signature of the method that makes asynchronous calls. Briefly, you can use the await keyword only if the async keyword is in the method signature. The same is true for lambda expressions.

This post presents just a short description of the feature. I strongly recommend that you visit the Visual Studio Async CTP page to learn more of the details and get tons of useful resources, including the language spec and cool samples.

Although we have plenty of examples and resources available, it’s never enough. So I’m giving you one more demonstration of how much easier it might be to create asynchronous programs with a future version of the C# and Visual Basic languages.

First, some preparatory steps to make the example work:

Download the Visual Studio Async CTP and install it.
Open Visual Studio 2010 and create a new Silverlight 4 project (To make things easier later, name it FacebookAsync.)
Add a reference to AsyncCtpLibrary_Silverlight.dll. It should be in My Documents/Microsoft Visual Studio Async CTP/Samples.
Add a reference to the System.Json library, because it’s used in the example. This is a standard Silverlight library.
Go to the properties of the web project and, on the Web page, check what port it uses for the Visual Studio Development Server. My sample application uses the port 50750, so it might be easier for you to use the same one.
Register your application on Facebook. You will get an application ID (which is the same as a client ID) and a secret key.

The FacebookAsync application I want to show you downloads a list of friends from Facebook and displays their names and Facebook IDs. It has a button and a DataGrid control that autogenerates columns. Here is its XAML.

<UserControl x:Class="FacebookAsync.MainPage"
     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
     xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
     xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
     mc:Ignorable="d"
     d:DesignHeight="445" d:DesignWidth="514" xmlns:sdk="http://schemas.microsoft.com/winfx/2006/xaml/presentation/sdk">
 
     <Grid x:Name="LayoutRoot" Background="White">
         <sdk:DataGrid AutoGenerateColumns="True" Height="282" HorizontalAlignment="Left" Margin="20,69,0,0" Name="searchResultsGrid" VerticalAlignment="Top" Width="390" />
         <Button Content="Get list of friends from Facebook" Height="23" HorizontalAlignment="Left" Margin="25,21,0,0" Name="button1" VerticalAlignment="Top" Width="206" Click="button1_Click" />
     </Grid>
 </UserControl>

To get a list of friends, an application needs to perform several steps (according to Facebook Graph API), including making two asynchronous calls:

You need to redirect from the application page to the Facebook authorization page and provide a client ID, a secret key, and a return URL as parameters of the URL. The user should authorize the application. (In debugging mode the user is probably you, so you should have your own Facebook account.)
If the user authorizes the application, the Facebook API redirects to a return URL, which your application provides. Facebook also adds an authorization code into its redirect URL as a parameter. No asynchronous calls are made yet, because this is done by simply navigating between pages.
The application should exchange the authorization code to an access token by using the GET request. Remember that Silverlight doesn’t have a synchronous API, so you have to make an asynchronous call.
After the application gets a token, it makes a new GET request to the Facebook API to get a list of friends for the current user. Once again, this call should be asynchronous.
The application parses the response from Facebook and displays it on the page.

The full code of the version that doesn’t use the new async feature might look like this.

public partial class MainPage : UserControl
 {
     // Remember to change to your application URL.
     string redirect_uri = @"http://localhost:50750/FacebookAsyncTestPage.aspx";
 
     // Get these values by authorizing your application on Facebook.
     string client_id = "Your Application ID";
     string client_secret = "Your Secret Key";
 
     // This collection will contain the list of friends.
     ObservableCollection<FacebookFriend> searchResults =
         new ObservableCollection<FacebookFriend>();
 
     public MainPage()
     {
         InitializeComponent();
         searchResultsGrid.ItemsSource = searchResults;
 
         // Check whether it was a redirect from the Facebook authorization page.
         if (HtmlPage.Document.DocumentUri.Query.Contains("?code="))
         {
             GetFriends();
         }
     }
 
     private void button1_Click(object sender, RoutedEventArgs e)
     {
         // Navigating to a Facebook authorization page. 
         // No asynchronous calls are necessary.
         var facebookAuthUri =
             new StringBuilder(@"https://graph.facebook.com/oauth/authorize?");
         facebookAuthUri.Append("client_id=").Append(client_id)
             .Append(@"&redirect_uri=").Append(redirect_uri);
         HtmlPage.Window.Navigate(new Uri(facebookAuthUri.ToString()));
     }
 
     public void GetFriends()
     {
         var code = HtmlPage.Document.DocumentUri.Query.TrimStart('?');
         var facebookUri =
             new StringBuilder(@"https://graph.facebook.com/oauth/access_token?");
         facebookUri.Append("client_id=").Append(client_id)
             .Append(@"&redirect_uri=").Append(redirect_uri)
             .Append(@"&client_secret=").Append(client_secret)
             .Append('&').Append(code);
 
         // First asynchronous call, to get an access token.
         WebClient proxy = new WebClient();
         proxy.DownloadStringCompleted +=
             new DownloadStringCompletedEventHandler(OnDownloadCompleted_Token);
         proxy.DownloadStringAsync(new Uri(facebookUri.ToString()));
     }
 
     // Processing results of the first asynchronous call.
     void OnDownloadCompleted_Token(
         object sender, DownloadStringCompletedEventArgs e)
     {
         // Second asynchronous call, to get a list of friends.
         WebClient proxy = new WebClient();
         proxy.DownloadStringCompleted +=
             new DownloadStringCompletedEventHandler(OnDownloadCompleted_Friends);
         var facebookFriendsUri = new StringBuilder(
      @"https://graph.facebook.com/me/friends?fields=id,name&");
         facebookFriendsUri.Append((String)e.Result);
         proxy.DownloadStringAsync(new Uri(facebookFriendsUri.ToString()));
     }
 
     // Processing results of the second asynchronous call.
     void OnDownloadCompleted_Friends(
         object sender, DownloadStringCompletedEventArgs e)
     {
         JsonObject jsonObject = (JsonObject)JsonValue.Parse((String)e.Result);
         JsonArray jsonArray = (JsonArray)jsonObject["data"];
         foreach (var friend in jsonArray)
         {
             searchResults.Add(
                 new FacebookFriend() { 
                     Name = friend["name"], ID = friend["id"] });
         }
     }
 }
 
 // Items displayed in the data grid.
 public class FacebookFriend
 {
     public string Name { get; set; }
     public string ID { get; set; }
 }

This is what you typically see when you have to deal with asynchronous applications: lots of callbacks, and overall the code is rather hard to read, although I spent some time on beautifying it. Now, let’s see how much easier it might be with the new async feature.

XAML will not change. The same is true for the FacebookFriend class, the button’s event handler, and all the properties in the MainPage class.

The changes start, unsurprisingly, in the GetFriends method. I’m going to make asynchronous calls by using the await keyword. But to enable this, I have to add the async keyword to the method signature.

public async void GetFriends()

Now I can start changing the code within the method. Let’s take a look at the existing code:

// First asynchronous call, to get an access token.
 WebClient proxy = new WebClient();
 proxy.DownloadStringCompleted +=
     new DownloadStringCompletedEventHandler(OnDownloadCompleted_Token);
 proxy.DownloadStringAsync(new Uri(facebookUri.ToString()));

Instead of making a callback, you can get the result string by using the await keyword.

// First asynchronous call, to get an access token.
 WebClient proxy = new WebClient();
 String token = await proxy.DownloadStringTaskAsync(
     new Uri(facebookUri.ToString()));

Note that I used a different method here: DownloadStringTaskAsync. This method doesn’t exist in Silverlight today; it’s a part of the CTP release only. In addition to new keywords in the C# and Visual Basic languages, future versions of the .NET Framework and Silverlight need to implement the Task-based Asynchronous Pattern (TAP). The details about this pattern are also included into the CTP release; look for “The Task-based Asynchronous Pattern” document.

According to this pattern, asynchronous methods should follow a certain naming convention: They should have the “Async” postfix (or “TaskAsync” if a method with the “Async” postfix already exists in the given API, as with the WebClient class). Such methods return instances of the Task or Task<TResult> class from the Task Parallel Library. But once again, the compiler does some work for you when you use the await keyword. In my example, the type of the token variable is not Task<String>, but just String; no extra work such as conversion or type casting is necessary.

And now you can simply continue writing your application logic in the same method! Everything I had in the OnDownloadCompleted_Token method can be moved to the GetFriends method. I don’t even need to create a new WebClient, since I already have one.

So, the code

// Second asynchronous call, to get a list of friends.
 WebClient proxy = new WebClient();
 proxy.DownloadStringCompleted +=
     new DownloadStringCompletedEventHandler(OnDownloadCompleted_Friends);
 var facebookFriendsUri = new StringBuilder(
     @"https://graph.facebook.com/me/friends?fields=id,name&");
 facebookFriendsUri.Append((String)e.Result);
 proxy.DownloadStringAsync(new Uri(facebookFriendsUri.ToString()));

from the OnDownloadCompleted_Token() method can be replaced with the following code (once again, using the new await keyword) and moved to the GetFriends method.

// Second asynchronous call, to get a list of friends.
 var facebookFriendsUri = new StringBuilder(
     @"https://graph.facebook.com/me/friends?fields=id,name&");
 facebookFriendsUri.Append(token);
 String friends = await proxy.DownloadStringTaskAsync(
     new Uri(facebookFriendsUri.ToString()));

After that I can simply delete the OnDownloadCompleted_Token method. In fact, I can make everything even shorter. I don’t need to create the token variable, because I can use the await keyword right in the method call, like this:

var facebookFriendsUri = new StringBuilder(
     @"https://graph.facebook.com/me/friends?fields=id,name&");
 WebClient proxy = new WebClient();
 // First asynchronous call, to get an access token.
 facebookFriendsUri.Append(await proxy.DownloadStringTaskAsync(
     new Uri(facebookUri.ToString())));
 // Second asynchronous call, to get a list of friends.
 String friends = await proxy.DownloadStringTaskAsync(
     new Uri(facebookFriendsUri.ToString()));

The last step is to simply move the code from the OnDownloadCompleted_Friends method to the GetFriends method and delete the OnDownloadCompleted_Friends method.

Here’s what the final version of the GetFriends method looks like:

public async void GetFriends()
 {
     var code = HtmlPage.Document.DocumentUri.Query.TrimStart('?');
     var facebookUri = new StringBuilder(
         @"https://graph.facebook.com/oauth/access_token?");
     facebookUri.Append("client_id=").Append(client_id)
         .Append(@"&redirect_uri=").Append(redirect_uri)
         .Append(@"&client_secret=").Append(client_secret)
         .Append('&').Append(code);
 
     var facebookFriendsUri = new StringBuilder(
         @"https://graph.facebook.com/me/friends?fields=id,name&");
 
     WebClient proxy = new WebClient();
 
     // First asynchronous call, to get an access token.
     facebookFriendsUri.Append(await proxy.DownloadStringTaskAsync(
         new Uri(facebookUri.ToString())));
 
     // Second asynchronous call, to get a list of friends.
     String friends = await proxy.DownloadStringTaskAsync(
         new Uri(facebookFriendsUri.ToString()));
 
     JsonObject jsonObject = (JsonObject)JsonValue.Parse(friends);
     JsonArray jsonArray = (JsonArray)jsonObject["data"];
 
     foreach (var friend in jsonArray)
     {
         searchResults.Add(new FacebookFriend() { 
             Name = friend["name"], ID = friend["id"] });
     }
 }

Instead of three methods I have just one, and it’s much more straightforward and easier to read. It simply has less code to begin with. I hope that I gave you just enough information to encourage you to explore more on your own and read more about the Visual Studio Async CTP.

Converting a VBA Macro to C# 4.0

Alexandra Rusina — Tue, 28 Sep 2010 00:30:37 GMT

I've talked a lot about improved COM interop in C# 4.0 and how much easier it is now to work with Office applications. This time I want to share some tips and tricks on how you can convert Visual Basic for Applications (VBA) macros to C# 4.0 by using Office 2010 and Visual Studio 2010.

You can either watch a video or read this post: it’s the same scenario and the same code, only I tried a different medium this time. If you for some reason decide to take a look at both, let me know which one you liked more and why.

One common scenario for people working on Office applications is to record a macro in Office and then use the results in their code. It's often much faster and easier than looking up all the methods and properties.

To try this out, record a macro in Excel 2010: create a new workbook, fill a column with numbers from 1 to 10 by using the Auto Fill feature, change the color of the column, and then create a simple graph.

Here's the VBA macro you'll get as a result:

Sub Macro1()

ActiveCell.FormulaR1C1 = "1"

Range("A2").Select

ActiveCell.FormulaR1C1 = "2"

Range("A1:A2").Select

Selection.AutoFill Destination:=Range("A1:A10"), Type:=xlFillDefault

Range("A1:A10").Select

With Selection.Interior

.Pattern = xlSolid

.PatternColorIndex = xlAutomatic

.ThemeColor = xlThemeColorAccent1

.TintAndShade = 0.399945066682943

.PatternTintAndShade = 0

End With

Range("A1:A10").Select

ActiveSheet.Shapes.AddChart.Select

ActiveChart.ChartType = xlConeColStacked

ActiveChart.SetSourceData Source:=Range("Sheet1!$A$1:$A$10")

End Sub

Now open Visual Studio 2010, create a new project, and add this reference to the project: Microsoft.Office.Interop.Excel. Then copy the VBA script inside the following code:

using Excel = Microsoft.Office.Interop.Excel;
 
 class Program
 {
     static void Main(string[] args)
     {
         var excelApp = new Excel.Application();
         excelApp.Workbooks.Add();
 
         // Insert VBA code here.
 
         excelApp.Visible = true;
     }
 }

Of course, the VBA code is all highlighted as an error. Here are the steps that you can use to convert that code into C# code:

In this macro, all the objects are in fact properties of the Excel application object. Basically, you need to add excelApp to the beginning of each line.
Press ALT and select an area at the start of the lines, as shown here:

Now type excelApp. and notice that it appears at the start of all the lines at once.
You can use the same trick to add Selection.Interior to all the lines in the With block. Then delete the first and the last elements of the block (With and End With).
For all the Range objects, you need to replace the parentheses with square brackets. This is because in C# you need to use indexed properties, and their syntax requires, well, square brackets. In this piece of code all of the parentheses should become square brackets, so you can use the Find and Replace feature. (The keyboard shortcut for this is Ctrl + H.)
The next step is to replace the syntax for the named parameters. VBA uses the ":=" operator, while in C# 4.0 it's simply ":". Once again, simple find and replace can help.
Now you need to add semicolons to each line, and add parentheses after each method call. You could probably find a converter that would do this for you, but here you have such a small piece of code that you can do it manually.

Update:
You can use the multi-line editing for adding semicolons as well. You can select a column in a so-called “virtual space”, where no characters were typed in.

So, you can type several semicolons at once and then reformat the document. Thanks to Jan B and David Nelson for the tip.
Let’s take a look at the code once again.
The last thing to fix is the constants. Press Ctrl+Alt+J to open the Object Browser, and then search for each constant. You should find a class that contains this enumeration:

All you need to do is to add the name of the class to the beginning of the constant.

excelApp.Selection.AutoFill(
Destination: excelApp.Range["A1:A10"],
Type: Excel.XlAutoFillType.xlFillDefault);

That’s it. Now you can compile and run the program and get exactly the same picture that you saw at the beginning of this post. Here's the final version of this little program.

using Excel = Microsoft.Office.Interop.Excel;
 
 class Program
 {
     static void Main(string[] args)
     {
         var excelApp = new Excel.Application();
         excelApp.Workbooks.Add();
 
         excelApp.ActiveCell.FormulaR1C1 = "1";
         excelApp.Range["A2"].Select();
         excelApp.ActiveCell.FormulaR1C1 = "2";
         excelApp.Range["A1:A2"].Select();
         excelApp.Selection.AutoFill(
             Destination: excelApp.Range["A1:A10"], 
             Type: Excel.XlAutoFillType.xlFillDefault);
         excelApp.Range["A1:A10"].Select();
 
         excelApp.Selection.Interior.Pattern = Excel.Constants.xlSolid;
         excelApp.Selection.Interior.PatternColorIndex = Excel.Constants.xlAutomatic;
         excelApp.Selection.Interior.ThemeColor = Excel.XlThemeColor.xlThemeColorAccent1;
         excelApp.Selection.Interior.TintAndShade = 0.399945066682943;
         excelApp.Selection.Interior.PatternTintAndShade = 0;
 
         excelApp.Range["A1:A10"].Select();
         excelApp.ActiveSheet.Shapes.AddChart.Select();
         excelApp.ActiveChart.ChartType = Excel.XlChartType.xlConeColStacked;
         excelApp.ActiveChart.SetSourceData(Source: excelApp.Range["Sheet1!$A$1:$A$10"]);
 
         excelApp.Visible = true;
     }
 }

If you've read all that and still feel like you missed some steps, watch the video: How Do I: Convert Visual Basic for Applications Macro to C# 4.0

P.S.

Thanks to Mads Torgersen and Alex Turner for reviewing this and providing helpful comments, to Mick Alberts for editing.

Blocking Collection and the Producer-Consumer Problem

Alexandra Rusina — Wed, 11 Aug 2010 23:18:48 GMT

This time I want to discuss features that belong to the new System.Collections.Concurrent namespace in the.NET Framework 4. When you design parallel applications, you often need thread-safe data storage as well as some mechanism of sending messages between tasks. Once again, this post will touch on just the basics and the most common problems a beginner might encounter, but I’ll provide links for further reading.

This is the fourth post in the parallel programming series. Here’s a list of all the posts:

Getting Started
Task Schedulers and Synchronization Context
Task Cancellation
Blocking Collection and the Producer-Consumer Problem (this post)

To keep things short, I’ll start with the code that I have at the end of the Task Schedulers and Synchronization Context post. This is a small parallel WPF application with a responsive UI that has one Start button and displays the results of long-running operations in a text box.

public partial class MainWindow : Window
 {
     public MainWindow()
     {
         InitializeComponent();
     }
 
     public static double SumRootN(int root)
     {
         double result = 0;
         for (int i = 1; i < 10000000; i++)
         {
             result += Math.Exp(Math.Log(i) / root);
         }
         return result;
     }
 
     private void start_Click(object sender, RoutedEventArgs e)
     {
         textBlock1.Text = "";
         label1.Content = "Milliseconds: ";
 
         var watch = Stopwatch.StartNew();
         List<Task> tasks = new List<Task>();
         var ui = TaskScheduler.FromCurrentSynchronizationContext();
         for (int i = 2; i < 20; i++)
         {
             int j = i;
             var compute = Task.Factory.StartNew(() =>
             {
                 return SumRootN(j);
             });
             tasks.Add(compute);
 
             var display = compute.ContinueWith(resultTask =>
                             textBlock1.Text += "root " + j.ToString() + " " +
                                                compute.Result.ToString() +
                                                Environment.NewLine,
                                 ui);
         }
 
         Task.Factory.ContinueWhenAll(tasks.ToArray(),
             result =>
             {
                 var time = watch.ElapsedMilliseconds;
                 label1.Content += time.ToString();
             }, CancellationToken.None, TaskContinuationOptions.None, ui);
     }
 }

But imagine that I’m designing a larger application and I need to store the results of the long-running parallel operations somewhere. (I don’t do this in the current version at all.)

Until .NET Framework 4, this task was challenging for C# developers: the collections in the System.Collections and System.Collections.Generic namespaces do not guarantee thread safety, and developers needed to design the locking and synchronization mechanisms themselves. But now generic thread-safe collections are a part of the .NET Framework. So, let me introduce the new namespace: System.Collections.Concurrent.

I’m going to use the BlockingCollection<T> class. This class can help you implement the well-known producer-consumer pattern, where items are produced and consumed by different operations at different rates. I will update my application to imitate the producer-consumer scenario, so that the compute task will become a producer, and the display task will become a consumer.

var results = new BlockingCollection<double>();

I’ll also update the compute task, so that instead of returning the result, it will add it to the results collection.

var compute = Task.Factory.StartNew(() =>
 {
     results.Add(SumRootN(j));
 });

When all the results are ready, I’ll set the collection to the “completed” state, so the consumer will know that this collection won’t be updated anymore. For this purpose, I’ll call the CompleteAdding method, which will set the IsCompleted property of the results collection to true. The good place to perform this operation is the task that calculates the total time: it waits for all other tasks to finish, which is exactly what I need.

Task.Factory.ContinueWhenAll(tasks.ToArray(),
     result =>
     {
         results.CompleteAdding();
         var time = watch.ElapsedMilliseconds;
         label1.Content += time.ToString();
     }, CancellationToken.None, TaskContinuationOptions.None, ui);

As you can see, the producer part is easy: all tasks can safely write to the results collection, and all locking and synchronization issues are managed by the .NET Framework and TPL.

Now let’s move to the consumer side. I’ll do a small refactoring: I’ll convert the display task into a consume task that will run the display method:

var consume = Task.Factory.StartNew(() => display(results));

I want to start the consume task before I start any of the compute tasks so that the consumer can wait for the producer and I can see the real-time results. That’s why I put the above line right before the main for loop in the button’s event handler.

This is what the naïve first version of the display method might look like. (Don’t forget to convert the ui task scheduler into a field. It’s a local variable in the original code.)

public void display(BlockingCollection<double> results)
 {
     double item;
     while (!results.IsCompleted)
     {
         while (!results.TryTake(out item));
         double currentItem = item;
         Task.Factory.StartNew(new Action(() =>
                   textBlock1.Text += currentItem.ToString() + Environment.NewLine),
              CancellationToken.None, TaskCreationOptions.None, ui);
     }
 }

This method checks for new elements in the collection, until it’s notified that the collection is completed, which means that it has finished adding new items. If it gets a new element from the collection, it immediately removes the item and prints the value into the UI threads. Did you notice that I copied item to currentItem? It’s all about closure again: you’ll get a list of zero’s otherwise.

This version works and you won’t get any exceptions. But if you run it on a dual-core computer like I did, you’ll discover that it takes twice as long as the version that doesn’t use the collection. In fact, it runs as if the application weren’t parallelized at all! This is just one of the problems that you might run into, so don’t forget to always measure the performance of your parallel applications: it’s easy to cancel out the benefits of parallelization.

Of course, the problem is in this line:

while (!results.TryTake(out item));

An empty loop is rarely a good idea. This was an attempt to implement some kind of messaging between the threads – the consumer is constantly checking the collection and starts working only if it can retrieve a value from it. And it does this over and over again, so one of my processors is fully occupied with this work and can’t compute the values anymore.

One simple trick is to make this loop to consume less processing power. It can be as easy as this (however, this is not a recommended way, but rather an illustration of the principle):

while (!results.TryTake(out item)) Thread.Sleep(200);

Now after each attempt the task simply waits for 200 milliseconds before trying again. And during those 200 milliseconds the processor can compute the results this task is actually waiting for. You can compile and run the code to make sure that the performance indeed improved.

However, it might be tricky to find the perfect wait time. Ideally, I need some kind of message from the collection notifying me that the value was added.

In a blocking collection, you can do this by using a foreach loop. The BlockingCollection class has the GetConsumingEnumerable method that can be used to enumerate through the blocking collection and consume its elements until the collection is completed. It might look like this:

public void display(BlockingCollection<double> results)
 {
     foreach (var item in results.GetConsumingEnumerable())
     {
         double currentItem = item;
         Task.Factory.StartNew(new Action(() =>
              textBlock1.Text += currentItem.ToString() + Environment.NewLine),
         CancellationToken.None, TaskCreationOptions.None, ui);
     }
 }

Now the display method checks whether there is an item in the results collection and, if there is, consumes the item. When the collection is completed and empty, execution exits the loop. All the locking, synchronization, and messaging between the tasks are managed by the TPL.

The resulting application will probably still be a little slower than the version that didn’t use the collection at all, but of course writing to and reading from thread-safe data storage added some overhead.

If you got lost in all the changes, here’s the full code:

public partial class MainWindow : Window
 {
     TaskScheduler ui = TaskScheduler.FromCurrentSynchronizationContext();
 
     public MainWindow()
     {
         InitializeComponent();
     }
 
     public static double SumRootN(int root)
     {
         double result = 0;
         for (int i = 1; i < 10000000; i++)
         {
             result += Math.Exp(Math.Log(i) / root);
         }
         return result;
     }
 
     private void start_Click(object sender, RoutedEventArgs e)
     {
         textBlock1.Text = "";
         label1.Content = "Milliseconds: ";
 
         var results = new BlockingCollection<double>();
         var watch = Stopwatch.StartNew();
         List<Task> tasks = new List<Task>();
 
         var consume = Task.Factory.StartNew(() => display(results));
 
         for (int i = 2; i < 20; i++)
         {
             int j = i;
             var compute = Task.Factory.StartNew(() =>
             {
                 results.Add(SumRootN(j));
             });
             tasks.Add(compute);
         }
 
         Task.Factory.ContinueWhenAll(tasks.ToArray(),
             result =>
             {
                 results.CompleteAdding();
                 var time = watch.ElapsedMilliseconds;
                 label1.Content += time.ToString();
             }, CancellationToken.None, TaskContinuationOptions.None, ui);
     }
 
     public void display(BlockingCollection<double> results)
     {
         foreach (var item in results.GetConsumingEnumerable())
         {
             double currentItem = item;
             Task.Factory.StartNew(new Action(() =>
                  textBlock1.Text += currentItem.ToString() + Environment.NewLine),
             CancellationToken.None, TaskCreationOptions.None, ui);
         }
     }
 }

For now, this is the last post in my parallel programming series. I hope that I’ve provided enough information and examples and bumped into and recovered from enough problems to enable even beginners to continue on their own. (At least I asked fewer questions while writing this post than I did for the first one!)

If you want to learn more about blocking collections, check out BlockingCollection Overview in the MSDN Library and BlockingCollection Extensions on the Parallel Programming with .NET blog.

I could not cover all the features provided by the TPL. If you want to see what else is available, here are some links:

Data Structures for Parallel Programming. This MSDN topic lists .NET 4 classes that are useful for parallel programming, such as thread-safe collections, synchronization primitives, and lazy initialization classes.
Introduction to PLINQ. Parallel Language Integrated Query, or PLINQ, enables quick and easy parallelization of LINQ queries.

Two more links that I used a lot in this series are Parallel Programming in the .NET Framework on MSDN and the Parallel Programming with .NET team blog.

P.S.

Thanks to Dmitry Lomov, Michael Blome, and Danny Shih for reviewing this and providing helpful comments, to Mick Alberts for editing.

C# 4.0 PowerPoint Presentations

CSharpFAQ — Tue, 27 Jul 2010 22:57:49 GMT

Alexandru Ghiondea from the C# team created an excellent deck of slides that he used at Microsoft Days 2010 in Bulgaria. The C# team reused the deck several times for User Groups' presentations and talks. If you are planning a talk at your User Group, feel free to download. And even if you are not, it’s still might be useful to take a look – it’s a nice overview of the new C# 4.0 and Visual Studio 2010 features.

There are three presentations included: Introduction to C# 4.0, Increased Productivity with Visual C# IDE, and Dynamic Deep Dive.

Parallel Programming: Task Cancellation

Alexandra Rusina — Mon, 19 Jul 2010 17:40:25 GMT

In this post, which is the third one in my parallel programming introduction series, I want to show how you can cancel parallel operations when working with the Task Parallel Library (TPL). I’m going to modify the program that I started in the previous posts. By the way, here’s the full list of posts in this series:

Getting Started
Task Schedulers and Synchronization Context
Task Cancellation (this post)
Blocking Collection and the Producer-Consumer Problem

At the end of the last post, I had a small parallel application with responsive UI that could be easily used in both WPF and Windows Forms UI programming models. I’m going to stick with the WPF version and add a Cancel button to the application.

This is the code I’m going to work with:

public partial class MainWindow : Window
 {
     public MainWindow()
     {
         InitializeComponent();
     }
     public static double SumRootN(int root)
     {
         double result = 0;
         for (int i = 1; i < 10000000; i++)
         {
             result += Math.Exp(Math.Log(i) / root);
         }
         return result;
     }
     private void start_Click(object sender, RoutedEventArgs e)
     {
         textBlock1.Text = "";
         label1.Content = "Milliseconds: ";
 
         var watch = Stopwatch.StartNew();
         List<Task> tasks = new List<Task>();
         var ui = TaskScheduler.FromCurrentSynchronizationContext();
         for (int i = 2; i < 20; i++)
         {
             int j = i;
             var compute = Task.Factory.StartNew(() =>
             {
                 return SumRootN(j);
             });
             tasks.Add(compute);
 
             var display = compute.ContinueWith(resultTask =>
                               textBlock1.Text += "root " + j.ToString() + " " +
                                                   compute.Result.ToString() +
                                                   Environment.NewLine,
                               ui);
         }
 
         Task.Factory.ContinueWhenAll(tasks.ToArray(),
             result =>
             {
                 var time = watch.ElapsedMilliseconds;
                 label1.Content += time.ToString();
             }, CancellationToken.None, TaskContinuationOptions.None, ui);
     }
 
     private void cancel_Click(object sender, RoutedEventArgs e)
     {
 
     }

Now let’s refer to the Task Cancellation topic on MSDN. It tells me that to cancel a task I need to pass a special cancellation token to the task factory. By the way, the cancellation model is one of the new features in .NET Framework 4, so if you haven’t heard about it yet, take a look at Cancellation on MSDN and the .NET 4 Cancellation Framework post from Mike Liddell.

I have several tasks created in a loop. I’m going to use just one cancellation token so I can cancel them all at once.

I’ll add the following field to the MainWindow class:

CancellationTokenSource tokenSource = new CancellationTokenSource();

The tasks I want to cancel are the ones that compute the results (and I don’t want to cancel the tasks that display the results). So here’s the next change. The code

var compute = Task.Factory.StartNew(() =>
 {
     return SumRootN(j);
 });

becomes

var compute = Task.Factory.StartNew(() =>
 {
     return SumRootN(j);
 }, tokenSource.Token);

Finally, I’ll add code to the event handler for the Cancel button. I’ll simply call the Cancel method for the cancellation token and all tasks created with this token are notified about the cancellation. I also want to print “Cancel” into the text block.

private void cancel_Click(object sender, RoutedEventArgs e)
 {
     tokenSource.Cancel();
     textBlock1.Text += "Cancel" + Environment.NewLine;
 }

Let’s press F5 to compile and run the code. Now I can click Start, then click Cancel, and get an exception. (Aren’t you getting used to it?) AggregateException is the exception that tasks throw if something goes wrong. True to its name, it aggregates all the task failures into a single exception.

In my case, the tasks that calculate the results were canceled successfully, but the ones that display the results to the UI failed. This is reasonable: there were no results to display.

Let’s take a short pause here. Basically, to cancel a task, it’s enough to just pass a cancellation token to the task and then call the Cancel method on the token, as I did above. But in the real world, even in a small application like this one, you have to deal with the consequences of task cancellation.

In my example, there are several options for handling this exception. First is the standard try-catch block. The exception is thrown by the delegate within the ContinueWith method, so I need to add the try-catch block right into the lambda expression. I may get more than one exception aggregated, so I need to iterate through the collection of inner exceptions to see the exceptions’ messages.

var display = compute.ContinueWith(resultTask =>
 {
     try
     {
         textBlock1.Text += "root " + j.ToString() + " " +
                             compute.Result.ToString() +
                             Environment.NewLine;
     }
     catch (AggregateException ae)
     {
         foreach (var inner in ae.InnerExceptions)
             textBlock1.Text += "root " + j.ToString() + " "
                 + inner.Message + Environment.NewLine;
     }
 }, ui);

This works fine. (You can compile and check, if you want to.) But once again, TPL provides a more elegant way of dealing with this type of issue: I can analyze what happened with the compute task and use its status to decide whether I want to start the display task.

var displayResults = compute.ContinueWith(resultTask =>
                      textBlock1.Text += "root " + j.ToString() + " " +
                                             compute.Result.ToString() +
                                             Environment.NewLine,
                          CancellationToken.None,
                          TaskContinuationOptions.OnlyOnRanToCompletion,
                          ui);

Now I’m passing two more parameters to the ContinueWith method. The first is the cancellation token. I don’t want the display task to be dependent on the cancellation token, so I’m passing CancellationToken.None. But I want this task to run only if the compute task returns some result. For this purpose I need to choose one of the TaskContinuationOptions. In my case the best solution is simply not to run the display task if the compute task was canceled. I can use the NotOnCanceled option that does just that.

But tasks may fail for some other reason, not just because of cancellation. I don’t want to display results of any failed task, so I’m choosing the OnlyOnRanToCompletion option. I’ll explain the “ran to completion” concept more a little bit later in this post.

However, the previous version with the try-catch block could also inform me that the tasks were indeed canceled. (Each task either printed the result or reported a cancellation by printing the exception message.) How to do the same in this version? Well, I can create a new task that will run only if the task is canceled. I’m going to convert the display task into two different tasks:

var displayResults = compute.ContinueWith(resultTask =>
                      textBlock1.Text += "root " + j.ToString() + " " +
                                             compute.Result.ToString() +
                                             Environment.NewLine,
                          CancellationToken.None,
                          TaskContinuationOptions.OnlyOnRanToCompletion,
                          ui);
 
 var displayCancelledTasks = compute.ContinueWith(resultTask =>
                                textBlock1.Text += "root " + j.ToString() +
                                                   " canceled" +
                                                   Environment.NewLine,
                                CancellationToken.None,
                                TaskContinuationOptions.OnlyOnCanceled, ui);

Now I get the same results as I did with the try-catch block, and I don’t have to deal with exceptions at all. Let me emphasize that this is a more natural way of working with TPL and tasks, and I’d recommend that you to use this approach whenever possible.

By the way, if you click the Cancel button and then click the Start button in my application, all you will see is a list of canceled tasks and no results at all. The cancellation token got into the canceled state, and there is no way to turn it back to “not canceled.” You have to create a new token each time. But in my case it’s easy. I simply add the following line at the beginning of the event handler for the Start button:

tokenSource = new CancellationTokenSource();

Now let’s take a look at the output of my little program. (I clicked Cancel right after I saw the results of the 5^th root.)

You can see that after I canceled the operation some roots were calculated nonetheless. This is a good illustration of the task cancellation concept in .NET. After I called the Cancel method for the task cancellation token, tasks that were already running switched into the “run to completion” mode, so I got the results even after I canceled the tasks. The tasks that were still waiting in the queue were indeed canceled.

What if I don’t want to waste resources and want to stop all computations immediately after I click Cancel? In this case, I have to periodically check for the status of the cancellation token somewhere within the method that performs the long-running operation. Since I declared the cancellation token as a field, I can simply use it within the method.

public double SumRootN(int root)
 {
     double result = 0;
     for (int i = 1; i < 10000000; i++)
     {
         tokenSource.Token.ThrowIfCancellationRequested();
         result += Math.Exp(Math.Log(i) / root);
     }
     return result;
 }

I made two changes: I removed the static keyword from the method declaration to enable field access, and I added a line that checks for the status of the cancellation token. The ThrowIfCancellationRequested method indicates so-called “cooperative cancellation,” which means that the task throws an exception to show that it accepted the cancellation request and will stop working.

In this case, the thrown exception is handled by the TPL, which transitions the task to the canceled state. You cannot and should not handle this exception in your code. However, Visual Studio checks for all unhandled exceptions and shows them when in debug mode. So, if you now press F5, you’re going to see this exception. Basically, you need to ignore it: You can simply press F5 several times to continue or run the program by using Ctrl+F5 to avoid debug mode.

Another possibility is to switch off the checking of these “unhandled by the user code” exceptions in Visual Studio: Go to Tools -> Options -> Debugging -> General, and clear the Just My Code check box. This makes Visual Studio “swallow” this exception. However, this may cause side effects in your debugging routine, so check the MSDN documentation to make sure it’s the right option for you.

Well, that’s all what I wanted to show you this time. Here is the final code of my still surprisingly small program.

public partial class MainWindow : Window
 {
     CancellationTokenSource tokenSource = new CancellationTokenSource();
     public MainWindow()
     {
         InitializeComponent();
     }
     public double SumRootN(int root)
     {
         double result = 0;
         for (int i = 1; i < 10000000; i++)
         {
             tokenSource.Token.ThrowIfCancellationRequested();
             result += Math.Exp(Math.Log(i) / root);
         }
         return result;
     }
 
     private void start_Click(object sender, RoutedEventArgs e)
     {
         tokenSource = new CancellationTokenSource();
         
         textBlock1.Text = "";
         label1.Content = "Milliseconds: ";
 
         var watch = Stopwatch.StartNew();
         List<Task> tasks = new List<Task>();
         var ui = TaskScheduler.FromCurrentSynchronizationContext();
         for (int i = 2; i < 20; i++)
         {
             int j = i;
             var compute = Task.Factory.StartNew(() =>
             {
                 return SumRootN(j);
             }, tokenSource.Token);
 
             tasks.Add(compute);
 
             var displayResults = compute.ContinueWith(resultTask =>
                                  textBlock1.Text += "root " + j.ToString() + " " +
                                                         compute.Result.ToString() +
                                                         Environment.NewLine,
                                      CancellationToken.None,
                                      TaskContinuationOptions.OnlyOnRanToCompletion,
                                      ui);
 
             var displayCancelledTasks = compute.ContinueWith(resultTask =>
                                            textBlock1.Text += "root " + j.ToString() +
                                                               " canceled" +
                                                               Environment.NewLine,
                                            CancellationToken.None,
                                            TaskContinuationOptions.OnlyOnCanceled, ui);
         }
 
         Task.Factory.ContinueWhenAll(tasks.ToArray(),
             result =>
             {
                 var time = watch.ElapsedMilliseconds;
                 label1.Content += time.ToString();
             }, CancellationToken.None, TaskContinuationOptions.None, ui);
     }
 
     private void cancel_Click(object sender, RoutedEventArgs e)
     {
         tokenSource.Cancel();
         textBlock1.Text += "Cancel" + Environment.NewLine;
     }
 
 }

As usual, here are some links for further reading if you want to know more about task cancellation:

Documentation about the new .NET 4 cancellation model in general and task cancellation in particular on MSDN.
The .NET 4 Cancellation Framework and Cancellation in Parallel Extensions from the Parallel Programming with .NET blog.
The Debugger does not correctly handle Task exceptions? from the Parallel Programming with .NET blog.

P.S.

Thanks to Dmitry Lomov, Michael Blome, and Danny Shih for reviewing this and providing helpful comments, to Mick Alberts for editing.