DiveDeeper's blog

EF Code First Cookbook — Recipe #5: Reading Master-Detail Information

2011-07-20T06:00:00Z

In the previous post (Recipe #4), you learned that Entity Framework Code First provides a simple way to create relationship between two entities. You have used the following definitions to describe the structure of Order and OrderDetail entities:

[Table("Order")]
public class Order
{
    public int Id { get; set; }
 
    [MaxLength(128)]
    public string Customer { get; set; }
 
    public DateTime OrderDate { get; set; }
    public decimal Total { get; set; }
 
    [MaxLength(5)]
    [Column(TypeName = "varchar")]
    public string Status { get; set; }
 
    public IEnumerable<OrderDetail> Details { get; set; }
}
 
[Table("OrderDetail")]
public class OrderDetail
{
    public int Id { get; set; }
    public Order Order { get; set; }
 
    [MaxLength(64)]
    public string Product { get; set; }
    public int Amount { get; set; }
    public decimal UnitPrice { get; set; }
}

The relationship between these entities are described by the Details property of the Order class, and the Order property of OrderDetail class. Analyzing them, EF infers that there is a one-to-many relationship between Order and OrderDetail. The Details property is used as a navigation property to access the “many” OrderDetail instances belonging to an Order. Similarly, the Order property of OrderDetail is a navigation property to access the “one” Order instance owning an OrderDetail instance. In Recipe #4 you also learned that with a simple code snippet you can add orders with corresponding details:

static void Main(string[] args)
{
    using (var context = new OrderDatabaseContext())
    {
        for (int i = 0; i < 5; i++)
        {
            var order = new Order
                            {
                                Customer = "Customer " + i,
                                OrderDate = DateTime.Now,
                                Total = 10*i,
                                Status = "NEW",
                            };
            context.Orders.Add(order);
            for (int j = 0; j < 3; j++)
            {
                var detail = new OrderDetail
                                 {
                                     Amount = 10*j + i,
                                     Product = "Product" + j,
                                     UnitPrice = 10 + j,
                                     Order = order
                                 };
                context.Details.Add(detail);
            }
        }
        context.SaveChanges();
    }
}

Here, setting the Order property of the detail instance provides the link used by EF to establish the physical relationship.

Recipe #5: Reading Orders with Related Details

It the last post you used SQL Server Management Studio to check that all orders and their details were correctly inserted into the database. This time you will use EF to display the orders added to the database.

Ingredients

LINQ queries
Property and constructor declarations
The Include method
Virtual Details property

Preparations

Download the source code and open the solution within the Start folder. It contains the same sample code as in Recipe #4, but the Recipe04 namespace of the original sample is reamed to Recipe05.

Instead of cooking the food at once, you will make experiments and try several techniques. At the end you will be able to find out which technique matches your gust.

How To Cook — First Experiment: Retrieving Details Manually

To display the newly added orders, follow these steps:

Add the following code snippet at the beginning of the Main method:
1. using (var context = new OrderDatabaseContext())
2. {
3. foreach (var detail in context.Details)
4. {
5. context.Details.Remove(detail);
6. }
8. foreach (var order in context.Orders)
9. {
10. context.Orders.Remove(order);
11. }
12. context.SaveChanges();
13. }
This code snippet removes all existing orders with their details, cleaning up the database for us. In a future recipe you will learn deleting entities from a database in details, right now simply accept that the code above — though it is not really elegant — does what it is supposed to do.
Add the following code to the end of the Main method:
1. // --- Read orders and the corresponding details
2. using (var context = new OrderDatabaseContext())
3. {
4. foreach (var order in context.Orders)
5. {
6. order.Details = from detail in context.Details
7. where detail.Order.Id == order.Id
8. select detail;
9. Console.WriteLine("Order with ID #{0} contains {1} details",
10. order.Id, order.Details.Count());
11. }
12. }
As you can see, this code iterates through the orders in the database and queries the details belonging to orders using LINQ.

Taste It (First Experiment)

Run the application with Ctrl + F5. The result is exactly what you expect, as shown in Figure 1.

Figure 1: The results of the first experiment

Well, you can see the five orders inserted in the database, and each of them has three details, as expected. But wait for a moment! If EF is smart enough to infer the one-to-many relationship between Order and OrderDetail, why I need to write a LINQ query to retrieve the order details? Why doesn’t EF help me and does not retrieve details automatically?

As you may guess, EF can do it for you. There are several ways, and you can instruct EF about your intention.

How To Cook — Second Experiment: Retrieving Details Automatically

You do not need to add the LINQ query to retrieve order details. Entity Framework can do if for you by declaring your intention. To try it, change a few code details:

Modify the definition of the Details property in the Order class to use IList instead of IEnumerable:
1. public IList<OrderDetail> Details { get; set; }
Add a default constructor to Order which initializes the Details collection:
1. public Order()
2. {
3. Details = new List<OrderDetail>();
4. }
Now, your Order class should look like this:
1. [Table("Order")]
2. public class Order
3. {
4. public Order()
5. {
6. Details = new List<OrderDetail>();
7. }
9. public int Id { get; set; }
11. [MaxLength(128)]
12. public string Customer { get; set; }
14. public DateTime OrderDate { get; set; }
15. public decimal Total { get; set; }
17. [MaxLength(5)]
18. [Column(TypeName = "varchar")]
19. public string Status { get; set; }
21. public IList<OrderDetail> Details { get; set; }
22. }
Remove the code querying order details from the Main method, now the code snippet displaying orders should look like this:
1. // --- Read orders and the corresponding details
2. using (var context = new OrderDatabaseContext())
3. {
4. foreach (var order in context.Orders)
5. {
6. Console.WriteLine("Order with ID #{0} contains {1} details",
7. order.Id, order.Details.Count());
8. }
9. }
Now run the application with Ctlr + F5. As shown in Figure 2, no details are read for any orders, due to the removal of the detail query code.

Figure 2: No detail records are read
Close the running application and add the following Include method call to the definition of the foreach statement:
1. // --- Read orders and the corresponding details
2. using (var context = new OrderDatabaseContext())
3. {
4. foreach (var order in context.Orders.Include("Details"))
5. {
6. Console.WriteLine("Order with ID #{0} contains {1} details",
7. order.Id, order.Details.Count());
8. }
9. }

Taste It (Second Experiment)

Now, start you application with Ctrl + F5, and check how the single Include method changed its behavior. As shown in Figure 3, this time all details are read again, just like in the first experiment.

Figure 3: All order details are read due to the Include method

The Include method instructed Entity Framework that you want to read an Order instance with the corresponding details in a single operation. Entity Framework is smart enough to emit a query to the SQL Server and obtain orders with related details in one SQL SELECT statement.

How To Cook — Third Experiment: Lazy Loading

The behavior you have seen in the second experiment is great, but in certain situations may not be optimal. First, you must use the Include method when you want to obtain order details, second, although you transfer those details over the network, you may not use them. In situations, when you do not know in advance whether you will need the order detail information, lazy loading is a great solution. Lazy loading means that you read the details of an order exactly when you need to touch them.

Entity Framework supports lazy loading. To try how easy it is, follow these steps:

Add the virtual modified to the Details property of the Order class:
1. public virtual IList<OrderDetail> Details { get; set; }
Remove the Include invocation from the code snippet listing the details:
1. // --- Read orders and the corresponding details
2. using (var context = new OrderDatabaseContext())
3. {
4. foreach (var order in context.Orders)
5. {
6. Console.WriteLine("Order with ID #{0} contains {1} details",
7. order.Id, order.Details.Count());
8. }
9. }

Taste It (Third Experiment)

Run your application again. It will display the same result as the second experiment (shown in Figure 3). Remember, the same code at the first attempt in the second experiment resulted in no detail record read. The key of the lazy loading behavior is the virtual keyword, as you will learn.

How It Works

In the first experiment you manually implemented the mechanism reading order details. However, you do not need to do it manually, because Entity Framework can do it for you.

In the second experiment the Include clause added to the Orders property of the data context instructed EF that you want to include details when reading orders. The SQL SELECT statements going to the database are generated so that orders and related details are retrieved with a single query. Using AnjLab profiler, you can observe the corresponding SELECT statement:

SELECT 
[Project1].[Id] AS [Id], 
[Project1].[Customer] AS [Customer], 
[Project1].[OrderDate] AS [OrderDate], 
[Project1].[Total] AS [Total], 
[Project1].[Status] AS [Status], 
[Project1].[C1] AS [C1], 
[Project1].[Id1] AS [Id1], 
[Project1].[Product] AS [Product], 
[Project1].[Amount] AS [Amount], 
[Project1].[UnitPrice] AS [UnitPrice], 
[Project1].[Order_Id] AS [Order_Id]
FROM ( SELECT 
    [Extent1].[Id] AS [Id], 
    [Extent1].[Customer] AS [Customer], 
    [Extent1].[OrderDate] AS [OrderDate], 
    [Extent1].[Total] AS [Total], 
    [Extent1].[Status] AS [Status], 
    [Extent2].[Id] AS [Id1], 
    [Extent2].[Product] AS [Product], 
    [Extent2].[Amount] AS [Amount], 
    [Extent2].[UnitPrice] AS [UnitPrice], 
    [Extent2].[Order_Id] AS [Order_Id], 
    CASE WHEN ([Extent2].[Id] IS NULL) THEN CAST(NULL AS int) ELSE 1 END AS [C1]
    FROM  [dbo].[Order] AS [Extent1]
    LEFT OUTER JOIN [dbo].[OrderDetail] AS [Extent2] ON [Extent1].[Id] = [Extent2].[Order_Id]
  )AS [Project1]
ORDER BY [Project1].[Id] ASC, [Project1].[C1] ASC

In the third experiment you added the virtual modifier to the definition of the Details property in the Order class. This single modifier opens new horizons for EF. Instead of using the Order class, EF creates a proxy class wrapping around Order on the fly. In this proxy an overridden Details property is used. The getter method implementation of Details checks whether its content is already read from the database, and if not, it automatically reads it before returning the collection of details.

With AnjLab you can catch that in this case Orders are read without details, and when you’re about counting the details, a second SELECT statement reads them from the database:

-- Statement reading orders
SELECT 
[Extent1].[Id] AS [Id], 
[Extent1].[Customer] AS [Customer], 
[Extent1].[OrderDate] AS [OrderDate], 
[Extent1].[Total] AS [Total], 
[Extent1].[Status] AS [Status]
FROM [dbo].[Order] AS [Extent1]
 
-- Statement reading the details of a specific order
exec sp_executesql N'SELECT 
[Extent1].[Id] AS [Id], 
[Extent1].[Product] AS [Product], 
[Extent1].[Amount] AS [Amount], 
[Extent1].[UnitPrice] AS [UnitPrice], 
[Extent1].[Order_Id] AS [Order_Id]
FROM [dbo].[OrderDetail] AS [Extent1]
WHERE ([Extent1].[Order_Id] IS NOT NULL) AND ([Extent1].[Order_Id] = @EntityKeyValue1)',
N'@EntityKeyValue1 int',
@EntityKeyValue1=96

Going On

By now, you have learned a lot about reading entities from the database. The next recipes help you understand how you can modify information.

EF Code First Cookbook — Recipe #4: Adding Details to a Master Entity

2011-07-18T04:00:00Z

It is very seldom that your applications work only with a single entity represented by a single database table. Almost all applications use several entities with relationships among them — and these relationships are reflected in the database structure as well.

In this post you will extend Recipe #2 into an application that manages not only simple orders, but also order details.

Recipe #4: Creating Relationship between Orders and Order Details

In Recipe #2 you used the following definition to describe the Order entity:

    [Table("Order")]
    public class Order
    {
        public int Id { get; set; }
 
        [MaxLength(128)]
        public string Customer { get; set; }
 
        public DateTime OrderDate { get; set; }
        public decimal Total { get; set; }
        [MaxLength(5)]
        [Column(TypeName = "varchar")]
        public string Status { get; set; }
    }

To implement a scenario closer to the real world, you must represent order details as well. You also must establish a relationship between orders and their corresponding details.

Ingredients

OrderDetail entity class
Reference to OrderDetail form Order
Reference from Order to OrderDetail
New order detail instances assigned to appropriate orders

Preparations

Download the source code and open the solution within the Start folder. It contains the same sample code as in Recipe #2, but the Recipe02 namespace of the original sample is reamed to Recipe04.

How to Cook

In order to complete this recipe, follow these steps:

Open the Recipe04 solution, and add a new class file to the Recipe04 project, name it OrderDetail.cs. Copy the following code into this new file:
1. using System.ComponentModel.DataAnnotations;
3. namespace Recipe04
4. {
5. [Table("OrderDetail")]
6. public class OrderDetail
7. {
8. public int Id { get; set; }
9. public Order Order { get; set; }
11. [MaxLength(64)]
12. public string Product { get; set; }
13. public int Amount { get; set; }
14. public decimal UnitPrice { get; set; }
15. }
16. }
As you learned in Recipe #2, the MaxLenght annotation on the Product property constraints the maximum size of the string that can be put into the database. The Table attribute decorating the class is required to avoid the default OrderDetails plural table name assigned by EF Code First to the entity by default.

The Order property references the order this detail belongs to. Using this property you will be able to navigate from a detail to the order owning it.
Open the Order.cs file and add the following property definition right after the Status property:
1. public IEnumerable<OrderDetail> Details { get; set; }
This property represents a set of order detail items belonging to the Order instance. Now, the definition of the Order class is the following:
1. [Table("Order")]
2. public class Order
3. {
4. public int Id { get; set; }
6. [MaxLength(128)]
7. public string Customer { get; set; }
9. public DateTime OrderDate { get; set; }
10. public decimal Total { get; set; }
12. [MaxLength(5)]
13. [Column(TypeName = "varchar")]
14. public string Status { get; set; }
16. public IEnumerable<OrderDetail> Details { get; set; }
17. }
Open the OpenDatabaseContext.cs file and add the following property to the class:
1. public DbSet<OrderDetail> Details { get; set; }
Now, the context definition looks like this:
1. public class OrderDatabaseContext: DbContext
2. {
3. public DbSet<Order> Orders { get; set; }
4. public DbSet<OrderDetail> Details { get; set; }
5. }
You’re ready with the refactoring of your entities. With the Order property added to the OrderDetail class, and Details property added to the Order class you have established the relationship among them.
Copy the following code snippet into the Main method of the Program.cs file:
1. using (var context = new OrderDatabaseContext())
2. {
3. for (int i = 0; i < 5; i++)
4. {
5. var order = new Order
6. {
7. Customer = "Customer " + i,
8. OrderDate = DateTime.Now,
9. Total = 10*i,
10. Status = "NEW",
11. };
12. context.Orders.Add(order);
13. for (int j = 0; j < 3; j++)
14. {
15. var detail = new OrderDetail
16. {
17. Amount = 10*j + i,
18. Product = "Product" + j,
19. UnitPrice = 10 + j,
20. Order = order
21. };
22. context.Details.Add(detail);
23. }
24. }
25. context.SaveChanges();
26. }
This code snippet creates five orders and adds three details to each of them. Observe, the relationship between orders and corresponding details is created by setting the Order property of the new OrderDetail instance. Orders are addet to the Orders collection of the context, whilst order details to the Details collection. EF takes care of setting up the relationships when SaveChanges is called.

Taste It

Now, this recipe is ready to taste. To let its gust melt in your mouth, follow these steps:

Run the application with Ctrl + F5. It completes in a few seconds, then close it by pressing a key.
Launch SQL Server Management Studio. (In Recipe #3 you could learn installing it.)
Expand the Databases node, then expand Recipe04.OrderDatabaseContext.
Query the content of the dbo.Order and dbo.OrderDetail tables by right-clicking the corresponding node and running the Select Top 1000 Rows command. You can see the five order records and the related fifteen order details records as shown in Figure 1 and Figure 2.

Figure 1: The content of the Order table

Figure 2: The content of the OrderDetail table

You can observe that the OrderDetail table has an Order_Id field that points to the identifier of the appropriate Order record.

How It Works

Entity Framework recognizes your intention from the definition of entities, as the following code snippet illustrates:

public class Order
{
    // ...
    public IEnumerable<OrderDetail> Details { get; set; }
}
 
public class OrderDetail
{
    // ...
    public Order Order { get; set; }
    // ...
}
 
public class OrderDatabaseContext : DbContext
{
    public DbSet<Order> Orders { get; set; }
    public DbSet<OrderDetail> Details { get; set; }
}

From the OrderDatabaseContext definition EF infers that corresponding tables should be created for the Order and OrderDetail entities. According to the Details property in Order and the Order property in OrderDetail, it infers that there is a one-to-many relationship between Order and OrderDetail. EF automatically creates this relationship and adds an Order_Id foreign key field to the OrderDetail table pointing to the appropriate Order identifier.

In the Main method you have used the following pattern to insert orders and related details:

using (var context = new OrderDatabaseContext())
{
    for (int i = 0; i < 5; i++)
    {
        var order = new Order // ...
        context.Orders.Add(order);
        for (int j = 0; j < 3; j++)
        {
            var detail = new OrderDetail
                             {
                                 // ...
                                 Order = order
                             };
        }
    }
    context.SaveChanges();
}

The SaveChanges operation recognizes that five new Order and fifteen new OrderDetail entities have been added to the context. Each OrderDetail explicitly references the Order record it belong to (by setting its Order property to the order instance). EF translates is to an SQL INSERT operation that sets the Order_Id field of the OrderDetail table when inserting the entities into the table. Using AnjLab (as you learned in Recipe #3) you can catch how an OrderDetail record is inserted by EF, as an example is shown in the following code snippet:

exec sp_executesql N'insert [dbo].[OrderDetail]([Product], [Amount], [UnitPrice], [Order_Id])
values (@0, @1, @2, @3)
select [Id]
from [dbo].[OrderDetail]
where @@ROWCOUNT > 0 and [Id] = scope_identity()',N'@0 nvarchar(64),@1 int,@2 decimal(18,2),@3 int',
@0=N'Product0',@1=1,@2=10.00,@3=2

Going On

Of course, it’s easy to retrieve entities from the database using the same straightforward style you have used when inserting new entities. Also, entity modification can be even more natural with a few changes. In the next recipe you will learn these features.

EF Code First Cookbook — Recipe #3: Installing Tools to Manage and Trace SQL Server

2011-07-15T04:00:00Z

As you progress and cook applications from new EF Code First recipes, you will need to view and manage databases. While Visual Studio’s Server Explorer is great tool to have a look at the structure of your databases, it is definitely not the best to manage them. Also, an appropriate SQL profiler helps you understand how EF Code First things go on behind the scenes.

A good cook knows the most useful tools if she wants to create quality feast. Before going on with more advanced recipes, in this post you will learn how to obtain the tools that help you cook more delicious goodies.

Recipe #3: Install the Toolset to Manage and Trace Databases

There are several tools you can utilize to manage your SQL Server databases. In this recipe you will install the two most important ones.

Ingredients

SQL Server 2008 R2 Express with Tools
AnjLab SQL Profiler

Preparations

Generally, when you install Visual Studio 2010, SQL Server 2008 Express is also installed on your machine, unless you manually exclude it from the setup options. If you were able to cook Recipe #1 and #2, it means that SQL Server Express is already working on your machine.

Installing SQL Server 2008 R2 Express with Tools

Even if you installed SQL Server 2008 Express with Visual Studio 2010, the set of management tools is still missing from your machine. Without it you can manage SQL databases only from command line tools. This is great, but not as easy as with using SQL Management Studio. On this page you’ll find links to download SQL Management Studio according to your machines operating system (32 or 64-bit versions), as shown in Figure 1.

Figure 1: Links to download SQL Server 2008 R2 Express with database tools

Click the appropriate link and download the installation kit executable.
When the download completes, start the executable (SQLEXPRWT_x86.exe or SQLEXPRWT_x64.exe). After the install kit extracts itself (and you allow it to run when asked), select the New installation or add features to existing installation task link, as shown in Figure 2.

Figure 2: SQL Server Installation Center welcome screen
In about half a minute the installation is prepared and the Licence Terms screen is displayed. Check the ‘I accept the licence terms’ check box and click Next.
In the Feature Selection page, the Database Engine Services and SQL Server Replication check boxes are set by default. If you have SQL Server Express already installed (together with Visual Studio 2010), uncheck these options. Check the Management Tools - Basic option, as shown in Figure 3. In the unlikely event you have not installed SQL Server Express, check the Database Engine Services option as well. Click Next.

Figure 3: Setting options on the Feature Selection page
In a few seconds the wizard displays the Error Reporting page, click Next again. The installation process starts and in a couple of minutes the Management tools are installed on your machine. The Complete page is displayed. Click Close to exit the wizard.
Close the SQL Server installation Center.
In the Start menu navigate to All Programs >> Microsoft SQL Server 2008 R2 and click SQL Server Management Studio. When the application is started, check whether you can connect to the SQLEXPRESS instance with the settings, as shown in Figure 4.

Figure 4: SQL Management Studio connection dialog
When your successfully connect to the SQLEXPRESS instance, the Object Browser window is displayed, as shown in Figure 5.

Figure 5: The Object Browser window

Installing AnjLab SQL Server Profiler

The standard SQL Server Profiler that comes together with non-express SQL Server versions does not work with SQL Server Express — and it is not free. Having an SQL Server Profiler is very useful when you want to peek SQL statements sent by Entity Framework to the database server. The AnjLab SQL Server profiler for SQL Server 2005/2008 is a simple and great open source tool. You can find the download link at the bottom of the page, as shown in Figure 6.

Figure 6: The download link of AnjLab binaries

Download the zip file and decompress it with your favorite tool. Start the SqlExpressProfiler.msi file, and use the ‘Next, Next, Next’ approach to install it — you can optionally change the default installation options.

Tasting SQL Server Management Studio

It’s time to check how you can manage your SQL Server databases. If you have used SQL Server Management Studio before, you can skip this section, if not, the following steps — where you will delete a database — give you a basic feeling:

Open either the Recipe01 or Recipe02 solution in Visual Studio. You can download the source code from here and here, respectively. Build and run the application, it will create a sample database in your SQLEXPRESS instance.
Launch SQL Server Management Studio and connect to the SQLEXPRESS database Engine instance.
Expand the Databases node, and you can see the either Recipe01.OrderDatabaseContext or Recipe02.OrderDatabaseContext nodes, or maybe both, as shown in Figure 7.

Figure 7: The list of databases in SQL Server Management Studio
Right-click the database node representing any database coming from the recipes, and select Delete from the context menu. Set the Close existing connections check box, as shown in Figure 8, and click OK. If you can see both databases, repeat these steps to delete the other database, too.

Figure 8: Deleting a database with SQL Management Studio
Keep the solution open in Visual Studio.

Tasting AnjLab SQL Profiler

AnjLab Profiler can be used to catch and view operations that have been executed on SQL Server Express. The information you obtain with the profiler tool can be utilized to understand what Entity Framework does in the background. It is useful both for getting acquainted with EF internals and solving performance issues. To grasp the basics of the profiler, follow these steps:

Launch the profiler from the Start menu (Start >> AnjLab >> AnjLab.SqlProfiler)
Create a new trace with File >> New Trace (Ctrl + N).
On the General tab of the Trace Properties dialog, set Authentication to Windows Authentication, as shown in Figure 9.

Figure 9: General trace properties in AnjLab
On the Events tab set the check boxes in the All column of the RPCCompleted and SQLBatchCompleted events, as shown in Figure 10, and click Run. AnjLab is now listening to calls that arrive to SQL Express.

Figure 10: Setting event trace properties in AnjLab
Go back to Visual Studio, and Run the solution with Ctrl + F5. If you have closed the solution, open it again.
Turn back to Anjab, and you can see the SQL Statements executed, as shown in Figure 11.

Figure 11: SQL Statements caught by AnjLab

Going On

Now, you have a basic understanding of creating simple database-aware objects with Entity Framework Code First. You also have some experinece with the SQL Server Management Studio and AnjLab tools that may help you in managing your databases and monitor the communication between the framework and the underlying SQL Server, repectively. It is time to learn new features through new recipes.

EF Code First Cookbook — Recipe #2: Add Some Spice to the Entity Definition

2011-07-13T04:00:00Z

In the previous post you created a single-table application that defined an Order class. Entity Framework used this class and created a database with an Orders table according to the structure of the Order class, and the application used this table through the OrderDatabaseContext class.

The name, “Code First” comes from the behavior of Entity Framework: instead of creating a database model first, or connecting to an existing database, you can immediately write code that represents your data entities.

The previous recipe’s application created an Orders table according to the following entity definition:

public class Order
{
    public int Id { get; set; }
    public string Customer { get; set; }
    public DateTime OrderDate { get; set; }
    public decimal Total { get; set; }
    public string Status { get; set; }
}

But what is the exact structure of the Orders table? Using the Server Explorer to connect to the database, you can take a look at the table structure, as shown in Figure 1.

Figure 1: The structure of the Orders table

The mappings between Order class properties and Orders table fields are pretty straightforward. The Entity Framework even recognized that the Id property is to be used as the primary key, moreover, it automatically added an identity field specification to it, so the value of this field is automatically generated at the SQL Server side. The handling of Id is an example of the ‘convention over configuration’ behavior of Entity Framework. Even if you do not tell, it handles Id as the primary key of the table, because of its name.

You can also see in Figure 1 that the Customer and Status properties are mapped the nvarchar(MAX) fields, and so they can hold large (up to 2GB in size) texts represented with Unicode characters. Well, it seems that you can use more appropriate field types to create the Orders table than Entity Framework did.

Instead of nvarchar(MAX) columns, I would definitely use nvarchar(n) or varchar(n), where n is a ‘realistic’ number representing the maximum length of Customer and Status properties. I do not like that my Order entity’s name is represented in its plural form in the database, because my company’s convention say we must use the singular forms.

Well, Entity Framework Code First provide you full control over the database model to be created from your entity definitions, as you will learn from this recipe.

Recipe #2: Basic Customization of the Data Structure Mappings

With this recipe you will use your own field types for the Customer and Status fields, and instruct Entity Framework to use the singular Order name instead of Orders when creating the database table from the Order class.

Ingredients

The clone of the Recipe01 project you created in the previous post
Table attribute
MaxLength attribute
Column attribute

Preparations

Download the source code and open the solution within the Start folder. It contains the same sample code as in Recipe #1, but the Recipe01 namespace of the original sample is reamed to Recipe02.

How to Cook

Now, you will set up the Order class to use the ‘Order’ table name insead of ‘Orders’, and change the field type of the Customer property to nvarchar(128) and the type of Status field to varchar(5). To carry out the changes, follow these steps:

Add the following using clause to the beginning of the Order.cs file:
1. using System.ComponentModel.DataAnnotations;
This namespace — as the term “data annotations” suggests — contains attribute types that can be used to decorate types representing entities. You are going to use a few attributes from this namespace to change field types.
Add the Table attribute to the Order class and decorate the Customer and Status properties, as shown in the following code snippet:
1. using System;
2. using System.ComponentModel.DataAnnotations;
4. namespace Recipe02
5. {
6. [Table("Order")]
7. public class Order
8. {
9. public int Id { get; set; }
11. [MaxLength(128)]
12. public string Customer { get; set; }
14. public DateTime OrderDate { get; set; }
15. public decimal Total { get; set; }
17. [MaxLength(5)]
18. [Column(TypeName = "varchar")]
19. public string Status { get; set; }
20. }
21. }

Taste It

Now, everything is ready to try, so taste what you’ve cooked:

Run the application with Ctrl+F5. This time the application creates a new database, Recipe02.OrderDatabaseContext. In the Server Explorer create a new data connection to access this new database (connect to the .\SQLEXPRESS server and select the Recipe02.OrderDatabaseContext database).
Expand the Tables node and select the Open Table Definition command from the context menu of the Order table. Now, the original table definition (Figure 1) has been changed, as shown in Figure 2. You can also recognize that the Orders table name in Figure 1 changed to Order in Figure 2.

Figure 2: The new definition of the Orders table

How It Works

The few attributes you’ve added to the Order class instructed the Entity Framework to initialize the database with your settings, overriding the default ones. The Table attribute attached to the Order class declares that instead of using the default table name, ‘Order’ should be used. By default, Entity Framework uses the pluralized form of the entity class name. That is why the corresponding table was named Orders in Recipe #1.

The MaxLength attribute can be attached to string properties, in order to define the maximum length they can take. In the code snipped above you’ve adorned the Customer and Status properties with this attribute.

The Column attribute can be used to set up various table column properties. By setting TypeName to ‘varchar’, you’ve declared that you’d like to see the Status property as a varchar field in the database.

There are many other attributes in the System.ComponentModel.DataAnnotations namespace, in the forthcoming recipes you will learn about them.

Going On

You rarely work with single-table databases, so it’s time to create something more complex. However, before going to this direction, it is worth to learn about a few tools that may help you managing databases and tracing what’s going behind the scenes.

EF Code First Cookbook — Recipe #1: Creating a Simple Code First Application

2011-07-10T23:00:00Z

In this new series of posts about Entity Framework I’d like to help those software developers who intend to use Entity Framework Code First in their projects — either coding for business or fun. I assume no special prerequisites, but a basic experience with Visual Studio and the C# programming language.

A good chef uses only quality ingredients. In this series you’re going to use only ingredients that provide delicious result, by means of simple, clear-cut and working sample applications.

A great cooking book contains not only recipes, but also teaches you a few technique. So do the posts in this series. Beside concrete recipes you’ll learn several basic techniques. Unlike traditional gastronomy books, this one intends to explain you what’s going on during the cooking process during the background — in other words, you’ll learn about how things work in Entity Framework.

Obtaining Quality Ingredients

Before starting to deal with the first recipe, let’s set up our kitchen equipment. To work with Entity Framework Code First, you need the following tools:

Visual Studio 2010 with Service Pack 1 — You can also use Visual C# Express 2010, however, if you can afford it, use Visual Studio 2010 Professional edition (or higher). The instructions and figures in this series assume you’re using Visual Studio 2010 Professional.
NuGet — This ingredient is a great package manager for Visual Studio, and you’ll use it to add prefabricated components to your projects.
Entity Framework — This package is the key ingredient you’re going to use in all recipes. You’ll add this component to your projects using NuGet.

To prepare the ingredients, follow these steps:

Start Visual Studio 2010.
With the Tools >> Extension Manager command, open the Extension Manager dialog, and click the Online Gallery tab, as it is shown in Figure 1.

Figure 1: The Extension Manager dialog
Type NuGet into the search box to filter extensions. Select the NuGet Package Manager item in the list, as shown in Figure 2, and click Download.

Figure 2: Selecting the NuGet extension
The Extension Manager downloads NuGet and launches the Visual Studio Extension Installer, as shown in Figure 3. Click Install to go on with NuGet setup. In a few seconds NuGet is installed. Click the Close button to exit the setup utility.

Figure 3: The Visual Studio Extension Installer utility
In order to complete the installation of NuGet, click Restart Now at the bottom of Extension Manager.
When Visual Studio is restarted, you can check in Extension Manager that NuGet is installed, as shown in Figure 4.

Figure 4: NuGet is now installed in Visual Studio

Entity Framework is a package managed by NuGet. You need a project Entity Framework components can be added to, so let’s create it.

Recipe #1: Creating a Single-Table Application with Code First

This recipe is your entry to learn Code First. You will create an application that manages a single table or order records.

Ingredients

A class describing an entity (Order)
A class describing a data context (OrderDatabaseContext)
A few lines of simple code to store a single entity into the database

How to Cook

To cook this recipe, follow these steps:

Use the File >> New >> Project command and select the Console Application template under Visual C#. Set the name of the project to Recipe01. Click OK.
Add a new class file to the project, name it Order.cs. Type or copy the following code into this new file:
1. using System;
3. namespace Recipe01
4. {
5. public class Order
6. {
7. public int Id { get; set; }
8. public string Customer { get; set; }
9. public DateTime OrderDate { get; set; }
10. public decimal Total { get; set; }
11. public string Status { get; set; }
12. }
13. }
The Order class represents a table in the database managing purchase orders. Each Order instance will be one data row in the data table, when saved to the database.
To turn the Order class into more powerful than its declaration tells, it’s time to add the power of Entity Framework Code First to the project. Right-click the References node under the Recipe01 project and select the Manage NuGet Packages command from the context menu.
The Manage NuGet Packages dialog appears. It looks very similar as Extension Manager. Select the Online tab, and type Entity in the search box. In a few seconds the list is populated with packages matching the Entity search term. Select EntityFramework from the list, as shown in Figure 5, and click Install.

Figure 5: Selecting the EntityFramework package
Accept the licence terms when asked. In a few seconds the EntityFramework package is installed and added to your project. Click Close to exit the NuGet Package Manager. The EntityFramework assembly is now a part of your project in pair with the packages.config file – this file contains information about packages added with NuGet to your project – as shown in Figure 6.

Figure 6: The EntityFramework assembly and the packages.config file
Add a new class file to the project, name it OrderDatabaseContext.cs. Copy the following code into this new file:
1. using System.Data.Entity;
3. namespace Recipe01
4. {
5. public class OrderDatabaseContext : DbContext
6. {
7. public DbSet<Order> Orders { get; set; }
8. }
9. }
The OrderDatabaseContext class can be used to access to your database entities. The declaration of Orders property (due to the DbSet<Order> type) allows you using this context to access and modify Order entities.
Believe or not, the core of your simple application is completed. You need to create a few code lines to try how it works. Open the Program.cs file, and change the Main method’s body to the code indicated in the following listing:
1. using System;
2. using System.Linq;
4. namespace Recipe01
5. {
6. class Program
7. {
8. static void Main(string[] args)
9. {
10. using (var context = new OrderDatabaseContext())
11. {
12. var newOrder = new Order
13. {
14. Customer = "IntelliGrail Co.",
15. OrderDate = DateTime.Now,
16. Status = "NEW",
17. Total = 100
18. };
19. context.Orders.Add(newOrder);
20. context.SaveChanges();
21. }
23. using (var context = new OrderDatabaseContext())
24. {
25. var order = context.Orders.FirstOrDefault();
26. Console.WriteLine("{0}: {1}, {2}, {3}",
27. order.Customer, order.OrderDate, order.Status,
28. order.Total);
29. }
30. }
31. }
32. }

Taste It

Now your first recipe is ready to taste. To check what’s out of oven, follow these steps:

Use Ctrl+F5 (Debug >> Start Without Debugging) to run the application. After you start it, it seems for a few seconds that it does not do anything, and then the result appears on the screen as shown in Figure 7. The simple code in Program.cs inserts a new data record into a database and then reads it from there and displays it.

Figure 7: The result of Recipe01
Use the Server Explorer window (View >> Server Explorer) to create a new Data connection (right-click the Data Connections node and select Add Connection). If you have never done it before, select Microsoft SQL Server in the Choose Data Source dialog, as shown in Figure 8, and click Continue.

Figure 8: Selecting Microsoft SQL Server as Data Source
In the Add Connection dialog type .\SQLEXPRESS as the Server name (very important: do not forget about the dot preceding the backslash) , and select the Recipe01.OrderDatabaseContext item from the combo box beneath the Select or enter a database name option, as shown in Figure 9. Click OK and your new connection is created.

Figure 9: Specifying the server and the database
Expand the new data connection node and then its Tables node. You can see two tables there, EdmMetadata and Orders. Right-click Orders and select the Show Table Data command. The content of the Orders table is displayed, as shown in Figure 10, with the order data your program inserted into the database.

Figure 10: The data in the Orders table

How It Works

It is amazing how many tasks this short program undertook! The code you’ve written created a database behind the scenes, and took care of inserting a record and then reading it back. But how is the whole magic done? Who is the sorcerer behind this?

This jugglery is brought to you by Entity Framework Code First. This smart component is responsible for the simplicity of this recipe. The whole story begins with the following code snippet in Program.cs:

using (var context = new OrderDatabaseContext())
{
    var newOrder = new Order
                       {
                           Customer = "IntelliGrail Co.",
                           OrderDate = DateTime.Now,
                           Status = "NEW",
                           Total = 100
                       };
    context.Orders.Add(newOrder);
    context.SaveChanges();
}

The instance of OrderDatabaseContext held in context starts the cogs of Entity Framework moving. The declaration of newOrder creates an instance of an Order entity you add to the Orders property of context in the next line. In this moment Entity Framework switches to first gear. It checkes whether the database implicitly defined by the OrderDatabaseContext exists. Because it does not found the database, it creates it (this is its default behavior). By convention, it uses the .\SQLEXPRESS instance and named the database according to the full type name of the context class.

The declaration of OrderDatabaseContext was the following:

public class OrderDatabaseContext : DbContext
{
    public DbSet<Order> Orders { get; set; }
}

From this declaration Entity Framework inferres that a table should be created to store Order instances, and uses the properties of the Order class to guess out the structure of the table.

The last operation of the first using statement is the invocation of the SaveChanges method. This operation collects all changes in the database context since it was created, and recognizes that you’ve added a single Order instance to it. It translates this addition to an INSERT database operation and places the new Order instance into the database with the INSERT statement.

Closing the using statement releases the resources held by the context instance.

The next using blocksimply reads back the inserted record from the database:

using (var context = new OrderDatabaseContext())
{
    var order = context.Orders.FirstOrDefault();
    Console.WriteLine("{0}: {1}, {2}, {3}",
        order.Customer, order.OrderDate, order.Status, 
        order.Total);
}

This time the data context class recognizes that the database already exists, and it do not want to create it. It simply translates the FirstOrDefault operation to a SQL SELECT statement to obtain the order entity you’ve inserted.

Going On

Hopefully you appreciated this recipe, because it took only a few ingredients and a short time to cook. In the next recipe you will add a little spice to this small application to make it more delicious.

Visual Studio LightSwitch 2011 RTM Launch Event on July 26 — With My New LightSwitch Book

2011-07-10T08:02:02Z

For a long time, it was officially not announced, when we can expect Visual Studio LightSwitch to be released. In a few days ago, Microsoft announced that the product is launching on July 26. In this announcement the new offical name of the product is mentioned as Visual Studio LightSwitch 2011.

In a few weeks ago I completed my book ‘Beginning Microsoft Visual Studio LightSwitch Development’, and it will be published by Wrox. The book will be available by the LightSwitch launch event (even if the link above says, it is issued on August 2, 2011), and it will be printed in full color.

There is no information when the product can be downloaded, and how it is priced. I assume, MSDN subscribers will be able to download it by the launch time, or even a few days before.

Beginning Visual Studio 2010 LightSwitch Development

2011-05-21T05:20:07Z

Since last September I work with Wiley (Wrox) on a new book titled Beginning Visual Studio 2010 LightSwitch Development. The job was interesting, because I managed to learn a lot of important details about LightSwitch. Of course, as the title of the book suggests, I focused on beginners, who do not have a deep programming background necessarily. Here is an extract from the Introduction to let you have an overview about the book.

How This Book Is Structured

This book is divided into three sections that will help you understand the concepts behind LightSwitch and become familiar with this great tool. The first part provides a quick overview that establishes the context of business application development, which will help you understand how LightSwitch responds to real-world challenges.

In the second part, the numerous hands-on exercises will enable you to learn the main concepts as you create the sample application, while the third part introduces a few advanced topics that are also important parts of the LightSwitch application development.

Most chapters first establish a context and treat the most important concepts, and then you learn how to use them through exercises. Each exercise concludes with a “How it Works” section that explains how(including all important details) the exercise achieves its objective.

Part I: An Introduction to Visual Studio LightSwitch

This section provides a context for Visual Studio LightSwitch and its approach to LOB application development—what it is and why it is an important addition to the Visual Studio family. It also provides an overview of the technologies that enable you to build a LightSwitch application.

Chapter 1: “Prototyping and Rapid Application Development”—This chapter provides an overview of application prototyping and rapid application development (RAD) techniques. Here you will learn how these techniques can answer LOB software development challenges, and learn how Visual Studio LightSwitch does it.
Chapter 2: “Getting Started with Visual Studio LightSwitch”—This hands-on chapter enables you to form your first impressions of Visual Studio LightSwitch. By the time you finish this chapter, you will have installed LightSwitch and created your very first application with it—all without writing a single line of code.
Chapter 3: “Technologies Behind a LightSwitch Application”— This chapter provides an overview of the foundational technologies behind a LightSwitch application. It will help you understand the main concepts of the technologies, as well as the roles they play in LightSwitch applications.
Chapter 4: “Customizing LightSwitch Applications”—The architectural and technological constraints provided by LightSwitch may seem too rigid. However, they actually help you to be productive, because the template-driven framework enables you to focus on your solutions, rather than the underlying design pattern. In addition, LightSwitch provides a full-featured set of customization features, which this chapter describes and demonstrates through examples.

Part II: Creating Applications with Visual Studio LightSwitch

The second section of the book treats the most important aspects of creating a fully functional LightSwitch application from scratch. Using the fictitious ConsulArt Company, you build a business application that helps the company control its projects.

Chapter 5: “Preparing to Develop a LightSwitch Application”—To understand the functionality of the LightSwitch integrated development environment (IDE) and its development approach, you will create a new sample application from scratch. This chapter describes the application and prepares you for implementing it.
Chapter 6: “Working with Simple Data Screens”—In this chapter, you will learn about the basics of creating tables and screens. Although you start with very simple tasks, they will help you understand LightSwitch’s flexible and extensible approach, and the useful tools that it provides.
Chapter 7: “Working with Master-Detail Data Screens”—Real applications contain data tables that have relationships between them. In this chapter, you will learn how to manage tables with relationships, and how you can build master-detail screens with them.
Chapter 8: “Using Existing SQL Server Data”—When you develop LOB applications, you often must access and use data stored in existing back-end systems. Visual Studio LightSwitch has been designed with this functionality in mind. In this chapter, you learn how to use data stored in existing SQL Server databases.
Chapter 9: “Building and Customizing Screens”—There are many opportunities in LightSwitch to build application screens. In this chapter, you learn the most important concepts and the basic architecture of screens. The step-by-step exercises will give you a clear understanding of each important element used to build and customize your screens.
Chapter 10: “Validation and Business Rules”—All LOB applications must have associated rules that characterize the business. In this chapter, you will learn about the concept of data validation, and learn about the tools LightSwitch provides for creating compound business operations.
Chapter 11: “Authentication and Access Control”—A real LOB application includes the capability of authenticating users and restricting them to using only functions they are permitted to carry out. In this chapter, you will learn the authentication and access control concepts of LightSwitch, and, of course, how to use them in your applications.
Chapter 12: “Microsoft Office Integration”—Visual Studio LightSwitch has been designed with Microsoft Office integration in mind. The automation features of Office applications make it easy to use Word, Excel, Outlook, or even PowerPoint from LightSwitch, as you learn in this chapter.

Part III: Advanced LightSwitch Application Development

The last portion of the book is dedicated to two advanced topics. It helps you understand the options LightSwitch offers for deploying an application, and teaches you about information stored in SharePoint 2010 lists.

Chapter 13: “Deploying LightSwitch Applications”—In general, application deployment is easy, but occasionally it can be a nightmare because of difficulties that result from creating setup kits and installation manuals. With LightSwitch, the whole process is straightforward. In this chapter, you learn about the options provided by the LightSwitch IDE, and you are guided through several deployment types.
Chapter 14: “Using SharePoint 2010 Lists”—LightSwitch enables you to utilize the information stored in SharePoint 2010. In this chapter, you learn how to access SharePoint 2010 lists and use them in your applications—with the same ease that you experience while building SQL Server–based solutions.

The book was written using Visual Studio LigthSwitch Beta 2, but before publishing, it will be reviewed according to the RTM version of LightSwitch. Hopefuly, we do not have to wait too long for the final release of LightSwitch RTM, and of course, for the book.

Visual Studio 2010 and .NET 4 Six-In-One Book is available to purchase

2010-10-05T04:55:18Z

Originally our book was scheduled to be published only in November, but now, it is available to purchase at Amazon:

http://www.amazon.com/Visual-Studio-2010-NET-Six/dp/0470499486

Hopefully, you can buy this book not only here but in other Web book stores and in shops soon.

Preparing a Book about Visual Studio LightSwitch

2010-09-10T08:52:44Z

Visual Studio LightSwitch was announced about five weeks ago and now the Beta 1 is available. I have read many opinions, feedbacks about what the community thinks (believes) about Visual StudioLightSwitch, and also have played with the product. I like the product and see its role in the LOB application development projects (at least in the context of my customers). After completing the Visual Studio 2010 and .NET 4 Six-In-One book, Wrox asked me to create a proposal about a “Beginning Visual Studio LightSwitch” book. Now, I have an idea what this book should contain.

Regularly, I plan to share you with some details from the book – and of course my experiences related to LightSwitch. Here let me share you a few impressions I have collected in since I started to play with Beta 1.

What is Visual Studio LightSwitch?

Visual Studio LightSwitch is a new member of the Visual Studio family. It is a Rapid Application Development (RAD) tool that aims to help writing data-centric line-of-business (LOB) applications. In contrast to the existing Visual Studio products, LightSwitch puts the emphasis on minimizing the amount of code to be explicitly written in order to develop an application.

Simply speaking, LightSwitch provides you a few intuitive and easy-to-use GUI designers to design data structures and the UI interacting with those data; explicit coding is rarely required.

Business Code versus Plumbing Code

LOB applications generally follow the three-tier application pattern where the three layers of an application (data, business logic and presentation layers) are clearly separated from each other.

When developers create LOB applications, their everyday activities can be separated into two groups:

Activities focusing on writing business code (code that delivers explicit business functions to the user), for example, the checkout process in a web shop.
Activities to create the plumbing code that bind tiers and components together in order to establish the flow from the user interface to the data back-end and vice versa. This plumbing code includes creating interfaces the layers use to communicate, handling transactions, forwarding error messages from the data back-end to the UI, etc.

In many LOB development projects the efforts spent on plumbing code may exceed the amount of man-hours spent on real business functions. Visual Studio LightSwitch decreases the time spent on creating plumbing code with order of magnitudes. Actually, LightSwitch developers do not have to deal with plumbing code at all, they can focus on delivering business functionality.

Besides eliminating the need for writing plumbing code manually, LightSwitch helps you being more productive when developing business functions. The lion’s share of the work — data and presentation tiers — can be done with the GUI designers in the IDE and you need explicit coding only for activities — such as writing business rules and other operation logic — where coding is probably the best to express your intention.

LOB Applications and LightSwitch

Microsoft positions Visual Studio LightSwitch as “the simplest way to create business applications for the desktop or the cloud”. While this sentence has a clear message, it does not give you too much munitions of guessing out in which situations can you use LightSwitch as a great tool and when do you need some other tool instead.

Because LightSwitch is a very new product, there are not enough case studies and concrete experiences that could help you make a decision about using it or not in your LOB projects. From the perspective of LightSwitch applicability you can group your LOB projects into three zones:

White zone: LightSwitch is a great tool for these kinds of projects.
Black zone: LightSwitch cannot be used as the main tool for projects in this zone.
Grey zone: Certain parts (or phases) of you LOB projects can be implemented with LightSwitch, but you definitely need other tools to complete your project.

Table 1 describes a few project stereotypes in each zone. Consider this list as one that is complete by no means.

Table 1: Applicability of Visual Studio LightSwitch

Zone	Examples
White Zone	Your business application is implemented as a set of Excel sheets right now, but you would like to have something more professional and less sensible for user errors. Your application has a small amount of data (let’s say measurable in several thousands of records) and simple structure (simple by your experience). Most operations create, edit, remove and list data. You have an existing application and you have to create a few new functions for a set of users, for example, administering data dictionaries of a large system. These kinds of applications are good candidates to be created with LightSwitch.
Black Zone	Your project handles a massive amount of data (millions of entries), and by your experience the same data have already challenged other projects. These kinds of applications may require architecture tuned especially for handling the specific performance issues, and so LightSwitch cannot help you. You have already a database and you need to create primarily listings and reports. This is not the functionality LightSwitch is tuned for. Use other products that are especially strong in reporting, for example, Microsoft Access or SQL Server Reporting Services. You have some technology requirements that cannot be matched with LightSwitch. (In Chapter 3 you can learn more about the technologies behind LightSwitch.) For example, if you have to create applications with Windows Forms user interface, LightSwitch won’t be your tool.
Grey Zone	Your application handles a large amount of data, but the structure is simple, and the number of users is relatively small (up to a one or two dozens). Your application has a relatively small amount of data, but a lot of users use that data concurrently. Your application’s business functions are complex and most of them cannot be described as simple read, list, insert, modify, or remove operations.

Use this table only as a starting point when analyzing whether your task or your project can be helped by LightSwitch. Copy this table and add your experiences to it later.

Check situations this table puts (or you put) into the grey zone. Grey zone does not mean that you cannot use LightSwitch, it means, you have to be careful and make some examination to guess out whether you can use LightSwitch and you do not step outside from its reasonable usability.

Even if you are sure that LightSwitch cannot be the ultimate tool for an entire project, you have a good change to use it as a rapid prototyping tool. In most cases creating a good prototype that can be used to communicate with business stakeholders can save you a lot of time and money in your projects, even if you have to rebuild the final application from scratch. You’ll save efforts by having a clear — and communicated — view of what the project is about, and so you can avoid a lot of rework that otherwise would come from a fuzzy view.

Visual Studio 2010 and .NET 4 Six-In-One book is close to the finish

2010-08-26T07:24:30Z

It the last 12 months we’ve been working hard to write our book titled “Visual Studio 2010" and .NET 4 Six-In-One”. The original idea came from Mitch Sellers who wanted to create a book that embraces six main topics and technologies related to the title of the book: Visual Studio 2010, .NET framework 4, ASP.NET 4, and of course the flagship .NET languages, Visual Basic, C# and F#. The authoring team is a real international one including authors from Argentina, Hungary, India and from US.

With this post I proudly announce that the book is close to the finish, Wrox will publish it by November 1, 2010.

Where can you buy the book?

The authoring team (in the order of appearance on the front cover):

István Novák (“DeepDiver” of Dotneteers.net)
András Velvárt (“VBandi” of Dotneteers.net)
Ádám Gránicz
György Balássy
Attila Hajdrik
Mitchel Sellers
Gaston C. Hillar
Ágnes Molnár (“Aghy” of Dotneteers.net)
Joydip Kanjilal

Summary of Contents:

Part I: Visual Studio

This section is dedicated to the discussion of the Visual Studio 2010 Integrated Development
Environment (IDE), and the enhancements and features available to developers.

Chapter 1: “History of Visual Studio” — This chapter provides an important introduction
to the history of how the Visual Studio product has evolved from the foundation to the
current product it is today. Major milestones and supported languages are discussed, along
with major enhancements included in each release.
Chapter 2: “Visual Studio UI Enhancements” — This chapter focuses on the major User
Interface (UI) changes between the Visual Studio 2008 and Visual Studio 2010 products.
The conversion of Visual Studio to use Windows Presentation Foundation (WPF) provided
an incredible amount of new UI features and functionality, which are all discussed in this
chapter.
Chapter 3: “Visual Studio Code Snippets” — From a developer productivity standpoint,
Visual Studio ’ s Code Snippets functionality is one of the biggest timesavers when it comes
down to reducing total keystrokes. This chapter is dedicated to discussing how to use and
create code snippets to improve productivity.
Chapter 4: “Visual Studio Templates” — In addition to code snippets, Visual Studio
provides a robust template system that allows for templates to be created for projects or
specifi c items. This chapter focuses on introducing the various template types, and how they
can be used to improve the development process.
Chapter 5: “Getting the Most Out of the IDE” — The feature set included in Visual Studio
2010 is massive, and the number of confi guration items can be mind - boggling, even to those
who have been using Visual Studio for a long time. This chapter focuses on ways to get the
most out of the IDE, including customization, window management, shortcuts, and the
gallery.
Chapter 6: “Visual Studio Extensibility” — In addition to the robust confi guration and
other features included with Visual Studio, there is additional support for extensibility in
the form of plug - ins, macros, and the like. This chapter illustrates how Visual Studio is set
up to allow for extension by developers.

Part II: .NET 4

The second portion of the book is dedicated to functionality provided by the 4.0 version of the
.NET Framework. Each of these chapters dives into new functionality that has been added across
the various technology sections of the .NET Framework.

Chapter 7: “.NET Framework Version History” — Before individual enhancements can
be discussed, it is important to understand the history of the .NET Framework. With
such rapid change in .NET over the past few years, this chapter helps to level - set the
times, versions, and release cycles that introduced new or improved functionality to the
framework.
Chapter 8: “Modern UI Frameworks (WPF and Silverlight)” — Recent releases of Visual
Studio have added two new UI frameworks. This chapter provides a quick overview to
answer the three most important questions when looking at new frameworks: when it
should be used, why it should be used, and how it should be used.
Chapter 9: “Windows Communication Framework (WCF)” — This chapter is dedicated to
WCF as it functions within the .NET 4 and Visual Studio 2010 environment.
Chapter 10: “Enhancements to the .NET Core Framework” — This chapter is examines
the new functionality added to the framework that can support development using various
other framework portions. You will learn about changes to the Common Language
Runtime (CLR), the addition of parallel computing, code contracts, and the Managed
Extensibility Framework (MEF).
Chapter 11: “Enhancements to the .NET Workfl ow Framework” — Windows Workfl ow
is another of the .NET framework pieces that has seen a large number of changes with past
releases of Visual Studio. This chapter is dedicated to discussing the major changes that
have been introduced in the .NET 4 release.
Chapter 12: “Enhancements to the .NET Data Framework” — Microsoft has been
dedicated to providing object relational mapping (ORM) style tools for developers and,
as such, items such as the entity framework and the like have seen a number of massive
changes in recent releases. This chapter is dedicated to the enhancements included within
the Data portions of the framework.
Chapter 13: “Enhancements to the .NET Communications Framework” — This chapter
about communications discusses the enhancements and changes that have been introduced
with .NET 4. This chapter is most helpful for readers who are moving forward from older
versions of WCF.
Chapter 14: “.NET Charting Components” — Although available as part of .NET 3.5
Service Pack 1 (SP1), the .NET charting components are a very powerful and recent
addition to the .NET Framework. This chapter examines the usage and benefi ts provided by
the built - in charting components that are available with .NET 4.

Part III: ASP.NET 4.0

The third portion of this book focuses on ASP.NET 4.0 and related items. For web application
developers, this section pulls together all of the new features and enhancements into one location,
making it easy to fi nd the items specifi c to web functionality.

Chapter 15: “ASP.NET Version History” — Similar in nature to the .NET Framework as
a whole, it is important to remember major milestones with regard to the previous releases
of ASP.NET to ensure that you are aware of new or changed functionality that has been
introduced. This chapter provides that needed foundation.
Chapter 16: “ASP.NET Charting Controls” — This chapter examines .NET Charting
components in a general manner. Here you will learn about the controls within the context
of an ASP.NET application, and the steps necessary to properly leverage the controls.
Chapter 17: “ ASP.NET Dynamic Data ” — Microsoft recently added support for dynamic
data, and this chapter is dedicated to discussing the features, benefi ts, and options available
when using dynamic data.
Chapter 18: “ASP.NET Model View Controller (MVC)” — Microsoft has added a new
project template type that supports web application development using the well - known
MVC design pattern. The introduction of MVC to the ASP.NET feature set has added a
number of items that can be used by developers of both MVC and Web Forms applications,
and this chapter is dedicated to those discussions.
Chapter 19: “ASP.NET Ajax Improvements” — ASP.NET Ajax is the foundational
component for creating a rich user experience with an ASP.NET application. A number of
enhancements were added to ASP.NET Ajax implementation, and this chapter is dedicated
to outlining all new features.
Chapter 20: “Ajax Control Toolkit, jQuery, and More” — In addition to the base ASP.NET
Ajax offering, Microsoft maintains a secondary download of the Ajax Control Toolkit, which
provides a robust set of additional controls. Microsoft has also embraced and added support
for the jQuery Open Source JavaScript library. This chapter discusses these items and how they
can relate within your applications.

Part IV: VB.NET

This section of the book is dedicated to discussing new features and enhancements that have been
added to the Visual Basic language. This is a short section because of the limited changes that
impact the Visual Basic language only.

Chapter 21: “History of Visual Basic” — To help get an understanding of the changes to
the Visual Basic language, it is important to understand the history of the language, and
when certain features were added. This chapter provides the needed introduction.
Chapter 22: “Visual Basic 10 Language Enhancements” — This chapter focuses on additions
and enhancements to the Visual Basic language as provided by Visual Studio 2010.

Part V: C#

This section of the book is dedicated to discussing new features and enhancements that have been
added to the C# Language. This is a short section because of the limited changes that impact the
C# language only.

Chapter 23: “History of C#” — To help get an understanding of the changes to C#
included with Visual Studio 2010, this chapter has been provided to set up the history of the
language with a short summary of major enhancements provided in past releases.
Chapter 24: “C# 4.0 Language Enhancements” — This chapter examines the new language
features that have been added to C# for version 4.0. Items such as covariance and other
language enhancements are discussed with examples.

Part VI: F# and Other .NET Languages

The final section of this book discusses the F# language and other .NET languages such as
IronRuby and IronPython. This section contains Chapter 25, which is the fi nal chapter of the book.
This extensive chapter introduces the F# language with detailed examples and explanations that
will allow you to quickly get up and running with F#. The chapter fi nishes with information on
IronRuby and IronPython.

Stay tuned, more details are coming in the next few weeks.

Microsoft Visual Studio LightSwitch Beta 1 is available for MSDN Subscribers

2010-08-19T06:01:00Z

If you are an MSDN subscriber, you do not have to wait by August 23, you can immediately download Visual Studio LightSwitch from MSDN. Click the Downloads and Product Keys link and select New Downloads | Visual Studio 2010. At the top of the list you will find LightSwitch Beta 1 (Both ISO and Web install). Happy downloading!

Joe Albahari about Threading in C#

2010-08-15T12:42:27Z

Joe recently published a free articles on the details of PLINQ + Task Parallel Library that is an extract from his book “C# 4.0 in a Nutshell”. You can find the article here. You can also download the full article in PDF format.

Joe, congratulations to this great article!

LearnVSXNow! Part #45: Embedding Visual Studio 2010 Editor into a Tool Window

2010-07-28T09:14:00Z

It was a long time ago when I posted the last article of the LearnVSXNow! series, because I was busy with several projects including two books. In the recent days I have spent a lot of time examining the new Visual Studio 2010 editor from extensibility point of view. I needed to embed an editor into a tool window so that I can try how several components work there.

I started from the EditorToolWindow sample posted by Chris Granger who is a PM in the Visual Studio Editor Team.

This sample is great but did not show several things such as turning on or off read-only mode or creating a tool window where the editor is accompanied by several other controls. In this blog post I show you how you can solve these things.

The editor window is designed so that it can be embedded into tool windows. Visual Studio itself uses the editor in several tool windows, for example, in the Output window and in Find Result windows. You can easily create your own tool windows embedding the editor, but it is not as trivial as creating a tool window embedding your own WPF user controls. The CodeEditorInToolWindow sample demonstrates how you can reuse the editor.

This sample is a Visual Studio package that implements two tool windows and adds related display commands to the View ð Other Windows menu:

ToolWindowWithEditor places the editor so that it uses the full client area of the tool window.
ToolWindowWithCompoundEditor creates a grid and puts the editor into one of the grid cells. It also defines a checkbox you can use to turn on or off read-only mode.

Package Type Definition

Listing 1 shows the definition of the class representing the Visual Studio package hosting the tool windows.

Listing 1: CodeEditorInToolWindowPackage.cs

using System;
using System.Runtime.InteropServices;
using System.ComponentModel.Design;
using Microsoft.VisualStudio;
using Microsoft.VisualStudio.Shell.Interop;
using Microsoft.VisualStudio.Shell;
 
namespace DiveDeeper.CodeEditorInToolWindow
{
  [PackageRegistration(UseManagedResourcesOnly = true)]
  [InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
  [ProvideMenuResource("Menus.ctmenu", 1)]
  [ProvideToolWindow(typeof(ToolWindowWithEditor))]
  [ProvideToolWindow(typeof(ToolWindowWithCompoundEditor))]
  [Guid(GuidList.guidCodeEditorInToolWindowPkgString)]
  public sealed class CodeEditorInToolWindowPackage : Package
  {
    protected override void Initialize()
    {
      base.Initialize();
 
      var mcs = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;
      if (null == mcs) return;
      var toolwndCommandID = new CommandID(GuidList.guidCodeEditorInToolWindowCmdSet,
                                           (int)PkgCmdIDList.cmdidShowCodeEditor);
      var menuToolWin = new MenuCommand(ShowToolWindowWithEditor, toolwndCommandID);
      mcs.AddCommand(menuToolWin);
      toolwndCommandID = new CommandID(GuidList.guidCodeEditorInToolWindowCmdSet,
                                       (int)PkgCmdIDList.cmdidShowCompoundCodeEditor);
      menuToolWin = new MenuCommand(ShowToolWindowWithCompoundEditor, toolwndCommandID);
      mcs.AddCommand(menuToolWin);
    }
 
    private void ShowToolWindowWithEditor(object sender, EventArgs e)
    {
      ShowToolWindow(typeof(ToolWindowWithEditor));
    }
 
    private void ShowToolWindowWithCompoundEditor(object sender, EventArgs e)
    {
      ShowToolWindow(typeof(ToolWindowWithCompoundEditor));
    }
 
    private void ShowToolWindow(Type toolWindowType)
    {
      var window = FindToolWindow(toolWindowType, 0, true);
      if ((null == window) || (null == window.Frame))
      {
        throw new NotSupportedException(Resources.CanNotCreateWindow);
      }
      var windowFrame = (IVsWindowFrame)window.Frame;
      ErrorHandler.ThrowOnFailure(windowFrame.Show());
    }
  }
}

This code does not contain any special thing; it initializes the commands popping up tool windows using the standard Visual Studio SDK pattern. However, the definition of the tool window pane is much more complex than the standard pattern.

Tool Window Pane Embedding an Editor

Listing 2 shows the source code of ToolWindowWithEditor class.

Listing 2: ToolWindowWithEditor.cs

using System;
using System.Runtime.InteropServices;
using System.Windows.Forms;
using Microsoft.VisualStudio.ComponentModelHost;
using Microsoft.VisualStudio.Editor;
using Microsoft.VisualStudio.OLE.Interop;
using Microsoft.VisualStudio.Shell.Interop;
using Microsoft.VisualStudio.Shell;
using Microsoft.VisualStudio.Text;
using Microsoft.VisualStudio.Text.Editor;
using Microsoft.VisualStudio.TextManager.Interop;
using IOleServiceProvider = Microsoft.VisualStudio.OLE.Interop.IServiceProvider;
 
namespace DiveDeeper.CodeEditorInToolWindow
{
  [Guid("de51a9b1-6595-42ef-bd69-ca3457f28ab8")]
  public class ToolWindowWithEditor : ToolWindowPane, IOleCommandTarget
  {
    IVsTextView _ViewAdapter;
    IVsTextBuffer _BufferAdapter;
    IVsEditorAdaptersFactoryService _EditorAdapterFactory;
    IOleServiceProvider _OleServiceProvider;
    ITextBufferFactoryService _BufferFactory;
    IWpfTextViewHost _TextViewHost;
 
    public ToolWindowWithEditor()
      : base(null)
    {
      Caption = Resources.ToolWindowTitle;
      BitmapResourceID = 301;
      BitmapIndex = 1;
    }
 
    override public object Content
    {
      get { return TextViewHost; }
    }
 
    private void InitializeEditor()
    {
      const string message = "This is an editor window embedded into a tool window.";
 
      var componentModel = (IComponentModel)Microsoft.VisualStudio.Shell.Package.
        GetGlobalService(typeof(SComponentModel));
      _OleServiceProvider = (IOleServiceProvider)GetService(typeof(IOleServiceProvider));
      _BufferFactory = componentModel.GetService<ITextBufferFactoryService>();
 
      _EditorAdapterFactory =
        componentModel.GetService<IVsEditorAdaptersFactoryService>();
      _BufferAdapter =
        _EditorAdapterFactory.CreateVsTextBufferAdapter(_OleServiceProvider,
        _BufferFactory.TextContentType);
      _BufferAdapter.InitializeContent(message, message.Length);
 
      _ViewAdapter = _EditorAdapterFactory.CreateVsTextViewAdapter(_OleServiceProvider);
      ((IVsWindowPane)_ViewAdapter).SetSite(_OleServiceProvider);
 
      var initView = new[] { new INITVIEW() };
      initView[0].fSelectionMargin = 0;
      initView[0].fWidgetMargin = 0;
      initView[0].fVirtualSpace = 0;
      initView[0].fDragDropMove = 1;
 
      _ViewAdapter.Initialize(_BufferAdapter as IVsTextLines, IntPtr.Zero,
        (uint)TextViewInitFlags.VIF_HSCROLL |
        (uint)TextViewInitFlags.VIF_VSCROLL |
        (uint)TextViewInitFlags3.VIF_NO_HWND_SUPPORT, initView);
    }
 
    public IWpfTextViewHost TextViewHost
    {
      get
      {
        if (_TextViewHost == null)
        {
          InitializeEditor();
          var data = _ViewAdapter as IVsUserData;
          if (data != null)
          {
            var guid = Microsoft.VisualStudio.Editor.DefGuidList.guidIWpfTextViewHost;
            object obj;
            var hr = data.GetData(ref guid, out obj);
            if ((hr == Microsoft.VisualStudio.VSConstants.S_OK) &&
              obj != null && obj is IWpfTextViewHost)
            {
              _TextViewHost = obj as IWpfTextViewHost;
            }
          }
        }
        return _TextViewHost;
      }
    }
 
    public override void OnToolWindowCreated()
    {
      // --- Register key bindings to use in the editor
      var windowFrame = (IVsWindowFrame)Frame;
      var cmdUi = Microsoft.VisualStudio.VSConstants.GUID_TextEditorFactory;
      windowFrame.SetGuidProperty((int)__VSFPROPID.VSFPROPID_InheritKeyBindings,
        ref cmdUi);
      base.OnToolWindowCreated();
    }
 
    protected override bool PreProcessMessage(ref Message m)
    {
      if (TextViewHost != null)
      {
        // copy the Message into a MSG[] array, so we can pass
        // it along to the active core editor's IVsWindowPane.TranslateAccelerator
        var pMsg = new MSG[1];
        pMsg[0].hwnd = m.HWnd;
        pMsg[0].message = (uint)m.Msg;
        pMsg[0].wParam = m.WParam;
        pMsg[0].lParam = m.LParam;
 
        var vsWindowPane = (IVsWindowPane)_ViewAdapter;
        return vsWindowPane.TranslateAccelerator(pMsg) == 0;
      }
      return base.PreProcessMessage(ref m);
    }
 
    int IOleCommandTarget.Exec(ref Guid pguidCmdGroup, uint nCmdID, uint nCmdexecopt,
      IntPtr pvaIn, IntPtr pvaOut)
    {
      var hr =
        (int)Microsoft.VisualStudio.OLE.Interop.Constants.OLECMDERR_E_NOTSUPPORTED;
      if (_ViewAdapter != null)
      {
        var cmdTarget = (IOleCommandTarget)_ViewAdapter;
        hr = cmdTarget.Exec(ref pguidCmdGroup, nCmdID, nCmdexecopt, pvaIn, pvaOut);
      }
      return hr;
    }
 
    int IOleCommandTarget.QueryStatus(ref Guid pguidCmdGroup, uint cCmds, OLECMD[]
      prgCmds, IntPtr pCmdText)
    {
      var hr =
        (int)Microsoft.VisualStudio.OLE.Interop.Constants.OLECMDERR_E_NOTSUPPORTED;
      if (_ViewAdapter != null)
      {
        var cmdTarget = (IOleCommandTarget)_ViewAdapter;
        hr = cmdTarget.QueryStatus(ref pguidCmdGroup, cCmds, prgCmds, pCmdText);
      }
      return hr;
    }
  }
}

ToolWindowWithEditor follows the Managed Package Framework pattern by means of setting up the caption and bitmap resources of the pane in the constructor and retrieving the control responsible for the UI in the Content property. However, all the other magic is required to embed the editor window properly into the window pane.

The key is the TextViewHost property — this is what the Content property retrieves. TextViewHost returns an IWpfTextViewHost instance and the concrete implementation is the WpfTextViewHost class of the Microsoft.VisualStudio.Text.Editor.Implementation namespace. Because WpfTextViewHost indirectly derives from System.Windows.UIElement, the window pane handles it is the same way as any other WPF controls, hosts it as the UI of the tool window.

The getter of TextViewHost invokes the InitializeEditor method that does the lion’s share of the work. After InitializeEditor prepares the editor instance, TextViewHost uses the IVsUserData interface to query the IWpfTextViewHost instance representing the editor.

InitializeEditor handles a lot of things related to COM interoperability and transparency between the new editor and old editors used prior to Visual Studio 2010.

private void InitializeEditor()
{
  const string message = "This is an editor window embedded into a tool window.";
 
  var componentModel = (IComponentModel)Microsoft.VisualStudio.Shell.Package.
    GetGlobalService(typeof(SComponentModel));
  _OleServiceProvider = (IOleServiceProvider)GetService(typeof(IOleServiceProvider));
  _BufferFactory = componentModel.GetService<ITextBufferFactoryService>();
 
  _EditorAdapterFactory =
    componentModel.GetService<IVsEditorAdaptersFactoryService>();
  _BufferAdapter =
    _EditorAdapterFactory.CreateVsTextBufferAdapter(_OleServiceProvider,
    _BufferFactory.TextContentType);
  _BufferAdapter.InitializeContent(message, message.Length);
 
  _ViewAdapter = _EditorAdapterFactory.CreateVsTextViewAdapter(_OleServiceProvider);
  ((IVsWindowPane)_ViewAdapter).SetSite(_OleServiceProvider);
 
  var initView = new[] { new INITVIEW() };
  initView[0].fSelectionMargin = 0;
  initView[0].fWidgetMargin = 0;
  initView[0].fVirtualSpace = 0;
  initView[0].fDragDropMove = 1;
 
  _ViewAdapter.Initialize(_BufferAdapter as IVsTextLines, IntPtr.Zero,
    (uint)TextViewInitFlags.VIF_HSCROLL |
    (uint)TextViewInitFlags.VIF_VSCROLL |
    (uint)TextViewInitFlags3.VIF_NO_HWND_SUPPORT, initView);
}

The old editor provided two interfaces, IVsTextBuffer and IVsTextView to access the text buffer behind the editor and to provide services to the view representing the UI of the editor, respectively. For backward compatibility reasons the new editor still provides these interfaces through the adapter pattern.

Line 5 and Line 6 obtain an IComponentModel instance that provides access to the default MEF composition container and the Visual Studio catalogs. This instance is used to obtain an ITextBufferFactoryService (in Line 8) — a factory that creates text buffers — instance and an IVsEditorAdaptersFactoryService — a factory that creates editor adapters — instance (in Line 10 and 11).

The statement starting with Line 12 creates the buffer and its related adapter; Line 13 initializes the content of the buffer with the predefined string message. Line 17 creates the view of the editor and the adapter to this view. In order this adapter could access the core Visual Studio services, it must be sited. The _OleServiceProvider field initialized in Line 7 provides a stub to obtain the service instances from within the adapter. Lines 20 to 29 are responsible to set up the initial properties of the view through an instance of the INITVIEW structure and a set of TextViewInitFlags. As a consequence of this initialization, the view will have a horizontal and a vertical scrollbar; it will be hosted in a WPF control (with no window handle), and it supports drag and move operations (to drag the selected text to another window, or drop text from other windows to the editor surface).

The window pane implemented by ToolWindowWithCodeEditor provides command routing from the IDE to the editor. This behavior is implemented by the following methods:

public class ToolWindowWithEditor : ToolWindowPane, IOleCommandTarget
{
  public override void OnToolWindowCreated() { ... }
  protected override bool PreProcessMessage(ref Message m) { ... }
  int IOleCommandTarget.Exec(...) { ... }
  int IOleCommandTarget.QueryStatus(...) { ... }
}

OnToolWindowCreated sets the key bindings of the window frame so that inherits the bindings from the text editor. PreProcessMessage is called to preprocess keyboard messages before Visual Studio handles them. The implementation in ToolWindowWithCodeEditor allows the view of the editor to catch and process navigation messages. The Exec and QueryStatus methods of IOleCommandTarget let the editor respond to command execution and command status queries sent to the window pane hosting the editor, respectively.

Tool Window Pane Embedding an Editor Indirectly

An editor can be embedded into a tool window indirectly, for example, as the ToolWindowWithCompoundEditor sample implements it. This tool window adds a checkbox to the UI that allows turning the read-only mode of the editor on or off, as Figure 1 shows.

Figure 1. Tool window with an editor and a check box

The majority of the window pane source code is exactly the same as shown in Listing 2. There are only a few changes as Listing 3 shows.

Listing 3: ToolWindowWithCompoundEditor.cs

[Guid("8BF4030D-C2AC-4F02-BDCA-1B2AC69477AB")]
public class ToolWindowWithCompoundEditor : ToolWindowPane, IOleCommandTarget
{
  // --- Members that are the same as in ToolWindowWithEditor.cs are omitted
  // --- for the sake of simplicity
 
  override public object Content
  {
    get
    {
      if (_Control == null)
      {
        _Control = new CompoundEditorControl(this);
        _Control.EditorPlaceHolder.Content = TextViewHost;
      }
      return _Control;
    }
  }
 
  public void SetReadOnly(bool isReadOnly)
  {
    uint flags;
    _BufferAdapter.GetStateFlags(out flags);
    var newFlags = isReadOnly
      ? flags | (uint)BUFFERSTATEFLAGS.BSF_USER_READONLY
      : flags & ~(uint)BUFFERSTATEFLAGS.BSF_USER_READONLY;
    _BufferAdapter.SetStateFlags(newFlags);
  }
}

Instead of simply retrieving the TextViewHost, the Content property assigns it to a ContentControl instance named EditorPlaceHolder in the CompoundEditorControl WPF user control. When this control is instantiated the window pane instance is passed so it can utilize the SetReadOnly method to turn on or off the read-only mode. The flags indicating and influencing the state of the buffer can be get and set through the buffer adapter with the GetStateFlags and SetStateFlags methods, respectively.

The XAML definition of CompoundEditorControl is really simple as Listing 4 shows.

Listing 4: CompoundEditorControl.xaml

<UserControl x:Class="DiveDeeper.CodeEditorInToolWindow.CompoundEditorControl"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
             xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
             mc:Ignorable="d"
             d:DesignHeight="300" d:DesignWidth="300">
  <Grid>
    <Grid.RowDefinitions>
      <RowDefinition Height="*" />
      <RowDefinition Height="Auto" />
    </Grid.RowDefinitions>
    <ContentControl x:Name="EditorPlaceHolder" />
    <CheckBox x:Name="IsReadOnly" Grid.Row="1" Margin="8" Click="IsReadOnly_Click">
      Use read-only editor
    </CheckBox>
  </Grid>
</UserControl>

The code-behind file responds to the event when the IsReadOnly check box is clicked, and calls the SetReadOnly method of the window pane, as Listing 5 shows.

Listing 1-5: CompoundEditorControl.xaml.cs

using System.Windows;
using System.Windows.Controls;
 
namespace DiveDeeper.CodeEditorInToolWindow
{
  public partial class CompoundEditorControl : UserControl
  {
    private readonly ToolWindowWithCompoundEditor _Pane;
 
    public CompoundEditorControl()
    {
      InitializeComponent();
    }
 
    public CompoundEditorControl(ToolWindowWithCompoundEditor pane)
    {
      InitializeComponent();
      _Pane = pane;
    }
 
    private void IsReadOnly_Click(object sender, RoutedEventArgs e)
    {
      if (IsReadOnly.IsChecked.HasValue)
      {
        _Pane.SetReadOnly(IsReadOnly.IsChecked.Value);
      }
    }
  }
}

I hope, this information helps you to host your the code editor in your tool windows. You can find the souece code of the package attached to this post.

VS 2010 Package Development – Chapter 2: Commands, Menus and Toolbars

2010-05-23T13:54:00Z

Here is the second chapter from my forthcoming book about Visual Studio 2010 Package Development.

I hope, you will find this chapters as useful as the first one.

Almost all packages are created to allow the user interact with through the corresponding user interface. This interaction generally means the user can click on a menu or toolbar item and activates a function of the package.

From the user interface perspective it is pretty easy to imagine what a menu, a menu item or a toolbar is. Developers either creating Windows Forms or ASP.NET applications can understand these ideas and know their semantics. WFP developers even meet with the concept of command binding. Coming from the world of Windows Forms application programming, most developers put an equation sign between the menu item and the event handler for that item. Using the same approach for Visual Studio simply will not work: the model behind the IDE is more generic and from this aspect is more complex.

In this chapter you’ll cruise around the concepts related to command handling. Command is a central concept of user interaction in Visual Studio — and as you are going to see, it is different from the idea most Windows Forms or ASP.NET programmers thinks about.

After reading this chapter you will be familiar with the following things:

Important concepts behind the command handling mechanism, like menu item, command, context, command binding and state.
The way the visibility and state of commands is determined by Visual Studio IDE. The CommandState sample will provide you a demonstration about how to enable or disable commands, and how to set their visual properties programmatically.
The role and structure of the Visual Studio Command Table (.vsct) file. The BasicVSCTSample and the AdvancedVSCTSample packages will show you a few simple tasks to carry out with a .vsct file:
- Creating a main menu
- Using command groups and submenus
- Decorating commands with icons and using command flags
- Creating toolbars and menu controllers
The concept and usage of visibility contexts. The VisibilityContextSample will demonstrate how to set up commands to be visible only in specific contexts.
Command routing used by Visual Studio to direct commands to an appropriate command target.

Commands are indispensable and frequently used entities in Visual Studio. Although the fundamental ideas behind them and many practical details are treated in this chapter, you will find a lot of command-related information also in the subsequent chapters.

Basic Command Handling Concepts

You generally create a VSPackage (and it is true for many other kind of software artifacts) in order to encapsulate functions. A part of these functions can be used from outside — for instance, by services your package offers for the Shell and for other packages. A part of these functions even can be used by users — assuming you provide appropriate interaction points to invoke them. These functions are called commands in the Visual Studio Extensibility terminology. A few samples are opening a solution, printing a source file, copying the selected text in the editor to the clipboard, adding a new file to the project hierarchy, and so on.

A command can be invoked by users only if you provide a way to do that. The most obvious way is to create a menu item or a button that can be clicked by the mouse or triggered by a keypress. There are other alternatives, for example you can provide a way where the user can type something in a console-like way to activate a command. If you do not think it is a real alternative, just look what the Command Window does in Visual Studio — visit the View ð Other Windows ð Command Window function!

Of course you have the “clickable” form of user interface representing commands in the Visual Studio IDE as menu and toolbar items. Each of them has the same function: when the user activates them, Visual Studio invokes the command bound to the item. From this perspective there is no difference if a command has been invoked from a menu or a toolbar.

Menus are generally displayed in a row at the top of the IDE and they generally provide a visual hierarchy of the items executing commands. Other user interface elements of the IDE — like tool windows, document windows, window frames — also can have their own context menus that pop up when the user right-clicks on them.
Toolbars hold a set of visual controls — typically organized in a row — that have the same function as menu items: execute commands. Toolbars can have a variety of control types, like buttons, text boxes, combo boxes and labels.

In this book the term of menu item is mentioned for user interface items that can be used to invoke a command independently of whether that is a menu item or a control on a toolbar.

Commands also can be executed programmatically. For example, the DTE object which is the root of the automation object model contains a method named ExecuteCommand that accepts a command name string and an optional parameter string — and as you guess it executes the action behind the command.

When pressing a button or triggering a command invocation action on any other kind of control, an event is raised that initiates the command action.

In the traditional Windows Forms programming many developers have only the idea of menu and toolbar items and event handler methods. Often they attach the same event handler method to more menu and toolbar items and handle the state of the UI separately. For example, if the same functionality is used by a menu item and a toolbar item they attach the same event handler method but handle the enabled/disabled state of the menu item and the toolbar item separately.

Visual Studio makes a clear separation on the concept of menu items and commands.

A command is responsible for determining its state (name, visibility, enabled, disabled, etc.) and executing the command triggered. A menu item is responsible for presenting the visual properties of a command and providing a way the user can trigger the execution of the command.

This means a command object can be bound to zero, one or more menu items. The command knows its state and can report it to the related menu items: developers have one central location to handle the state of the command independently of how many menu items make that accessible. They only have to deal with the state of the command; menu items adjust their appearance by themselves. Also there is only one location for the command action code independently of the number of interaction points which can trigger the command.

So the idea of a menu (or toolbar) item and the command behind them are separated. There is another twist in the story: a command does not own the code that is intended to run when the command is invoked or when the status of the command is queried.

A command itself is a logical entity that can be forwarded to so-called command targets which know how to handle the semantics of a specific command. There is a command routing model in the IDE that forwards a command to a command target. The target either can do something with the request related to a command (for example, sets the command state disabled, execute the command, etc.) or can pass back the command as not supported (the target does not know what to do with that). The target even can pass the command to other command targets.

To make it easier to follow, let me tell you an example. We have Cut, Copy and Paste menu items in the Edit menu and on the standard toolbar of Visual Studio. Moreover, these items are added to a number of context menus — each of them can be accessed at least from three different locations. The items are bound to commands having the logical name of Cut, Copy and Paste. There is not a single object in Visual Studio that knows how to execute those operations. The IDE forwards these commands to command targets depending on the current context. For example, when the text editor is focused the IDE sends the commands to the text editor. When you are in the Properties window, commands are sent there. When you edit an .aspx page visually, the designer receives these operation commands. So, the text editor, the Properties window and the ASP.NET page designer all are command targets. They can decide if they support the command — they understand what the command means — and how to respond to that. If they support the command they are also able to execute the corresponding action.

Figure 1 visualizes the logical relation among basic entities that are involved in the process of executing a command, and Table 1 describes them:

Figure 1: Logical diagram of basic command handling entities

Table 1: Summary of basic command handling concepts

*Entity*	*Responsibility*
Menu Item (toolbar item)	Provides a user interface to invoke commands. Allows feedback about the command state to the user.
Context	A logical context representing the state of the environment. The context determines the status of the command. For example, if there is no text copied to the clipboard, the Paste function is not enabled.
State	Commands are logical entities and they have states that influence if commands are allowed executing their related action or not and also how commands are visualized. Commands can be enabled or disabled and they can have shown or hidden states.
Action	The physical action to be invoked when an enabled command is executed by the command target.
Command	A logical entity representing an action that can be queried about its state within the current context, and can be resulted in executing some code. The command itself is just a logical entity, and it does not own the code responsible for status query and action execution.
Command Target	An entity that knows how to execute a status query and action belonging to a command entity. It can route, execute or even refuse actions of the command received.
Command Binder	An entity responsible for understanding a specific command received by the command target in the current context. The Command Binder invokes physically the action bound to the command.

The best way of getting more information about how these concepts work in practice is to create an example and diving into the code.

Physical Representation of Command Handling Concepts

You are going to use the FirstLook package sample code introduced in the previous chapter as the first example, because this is one of the smallest which can demonstrate how the logical concepts are represented in code. This sample application adds a command named Simple Message to the Tools menu. The command displays a message box when the user clicks on the related menu item.

First let’s have a look the code with the visual representations of commands. In the FirstLook.vsct file you can see the items for defining and placing the menu item:

<Groups>
  <Group guid="guidFirstLookCmdSet" id="MyMenuGroup" priority="0x0600">
    <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>
  </Group>
</Groups>
    
<Buttons>
  <Button guid="guidFirstLookCmdSet" id="cmdidShowMyMessage" priority="0x0100" 
    type="Button">
    <Parent guid="guidFirstLookCmdSet" id="MyMenuGroup" />
    <Icon guid="guidImages" id="bmpPic1" />
    <Strings>
      <CommandName>cmdidShowMyMessage</CommandName>
      <ButtonText>Simple Message</ButtonText>
    </Strings>
  </Button>
</Buttons>

By this definition the Simple Message menu item is represented by a Button element that is parented by a Group element. The Group, Button and Parent elements have guid and id attributes that are used as compound identifiers. The Parent elements create the relationships so that the Group is inserted into the Tools menu, the Button is added to the Group so as a result you’ll have the Simple Message item added to the Tools menu.

The (guid, id) pairs are the compound keys of command table elements. The guid represents a logical container of elements belonging together and the id represents the unique element identifier within that container. Here the identifier of the Button element is actually the identifier of the command represented by this Button node. The command here is used implicitly with its ID. This nature of the compound key is also represented by the Symbols section where GuidSymbol nodes have IDSymbol child nodes describe this logical containment:

<GuidSymbol name="guidFirstLookCmdSet" value="{4423366f-0518-4fd9-832f-9efd21a9013b}">
  <IDSymbol name="MyMenuGroup" value="0x1020" />
  <IDSymbol name="cmdidShowMyMessage" value="0x0100" />
</GuidSymbol>

Let’s see how this command is represented in the code. The Initialize method of the FirstLookPackage class contains the following code:

protected override void Initialize()
{
  Trace.WriteLine(string.Format(CultureInfo.CurrentCulture, 
    "Entering Initialize() of: {0}", this.ToString()));
  base.Initialize();
  OleMenuCommandService mcs = GetService(typeof(IMenuCommandService)) 
    as OleMenuCommandService;
  if (null != mcs)
  {
    CommandID menuCommandID = new CommandID(GuidList.guidFirstLookCmdSet, 
      (int)PkgCmdIDList.cmdidShowMyMessage);
    MenuCommand menuItem = new MenuCommand(MenuItemCallback, menuCommandID);
    mcs.AddCommand(menuItem);
  }
}

The package is a command target, so it can receive command notifications and execute actions of commands it understands. This behavior is defined by the IOleCommandTarget interface and the Microsoft.VisualStudio.Shell.Package class that is the ancestor of FirstLookPackage implements this interface. Although the package declares and understands only a single command, it receives many command notifications. However, it will refuse all commands except the one it knows. This command target behavior is delegated — the Package class implements it this way — to an object instance of type OleMenuCommandService. In Line 06 and 07 the GetService method is addressed with the type of IMenuCommandService to retrieve this OleMenuCommandService instance. You can add commands to this OleMenuCommandService instance to handle. When the package as a command target receives a command notification, it is processed by the command service instance. The command service checks if the command received is on its list or not. If the command is on the list, the required action is executed; otherwise command execution is refused. The sender object is notified about the command execution result (executed or refused).

Lines 10-13 contain the steps required to add a command to the list of the command service. First a CommandID instance is created which is a simple wrapper type for the compound key of a command. It uses a pair of System.Guid and System.UInt32 values to identify a command. When you check the identifiers used as the two construction parameters you can guess they are the same as the ones used for the Button node in the FirstLook.vsct file.

Line 12 creates a MenuCommand instance. MenuCommand is defined in the System.ComponentModel.Design namespace in the System.dll assembly and is the part of the .NET Framework and not the part of Visual Studio. It represents a part of the Command Binding entity id Figure 1. In Line 12 you construct it using the MenuItemCallback method delegate and the identifier of the command you have created in Line 10 and 11. MenuCommand — among the others — has an Invoke method to execute the menu action, and properties like Enabled and Visible to get or set the status of the related command item. The command service instance leverages on these properties and method to implement its behavior.

Line 13 adds the MenuCommand instance to the container of the command service object.

Now you can create Table 2 for associating the types for the roles summarized in Table 1.

Table 2: Summary of types implementing the command handling concepts

*Entity*	*Implementation*
Menu Item (toolbar item)	Menu and toolbar items do not appear as concrete .NET types in the package, they are defined in the .vsct file of the package project.
Command State	In the FirstLook sample command states are not used. However, the properties of MenuCommand — such as Enabled and Visible — represent the state.
Command	The command as a standalone physical entity is not used. The concept of command is represented by a CommandID instance that is used in several places. For example, a MenuCommand refers to a command by its CommandID property which is a CommandID instance.
Command Target	Objects implementing the IOleCommandTarget interface. In the FirstLook sample this is the FirstLookPackage class that implements the interface indirectly through the Package class. However, the package delegates this responsibility to its command service instance with the type of OleMenuCommandService.
Command Binder	In the FirstLook sample binders are represented by MenuCommand instances.

You have seen the implementation of a very simple command. It’s time to look other examples demonstrating more aspects of Visual Studio’s command handling architecture.

Command State and Visibility

Each command has a state in the current Visual Studio context. This state is built up from two orthogonal factors:

The availability of a command (enabled or disabled) tells if it is allowed to be invoked within the context or not. For example, if you do not have any text selected in the active text editor, the Copy or Cut commands should not be allowed being invoked.
The visual properties of a command tell if the menu and toolbar items related to the command are visible and what the displayed label or icon are.

Although these factors are independent from each other, the availability of a command is also reflected visually: menu items of disabled commands are grayed out.

The properties determining the state of commands can be set dynamically. Visual Studio updates the user interface asynchronously. It sends status requests to the appropriate command targets and asks them to tell the status of specific commands. This is done in Visual Studio idle time with an algorithm that sends status queries only for commands that have a chance to be displayed in the current context.

There is one thing that needs some consideration: how the initial state of a command is set up? Packages are on-demand loaded, so there is a part of the command lifecycle when their owner package is not loaded, but menu items representing them are already merged with Visual Studio menus. In this part of their life Visual Studio does not send status requests to the command target of unloaded commands, because it actually would require the command to be loaded.

Visual Studio uses the following approach to handle the visibility status of commands:

While a command is not flagged in the command table (.vsct file) as one that changes any of its visual properties during its life — this flag wears the remarkable DynamicVisibility name —, the explicit visual status of the command is never queried and never updated, the initial state set up in the command table is used during the whole IDE session. Of course, you should initialize these commands to be visible (this is their default state); otherwise they are not very useful.
If a command is flagged to dynamically change its visual properties, the initial settings in the command table are used unless the package is loaded. After the package gets sited the appropriate command target object is queried for the status of the command.

Command availability is not part of the explicit visual state. The enabled or hidden state of a command is maintained independently of the DynamicVisibility flag is used or not. While the package of the command is not loaded, the initial availability state defined in the command table is used. As soon as the package gets loaded the command target is queried for availability even if explicit visual state is not queried.

The Command State Sample

To follow the concepts above you’ll examine a package example named CommandState. This package adds five menu items to the Tools menu as indicated in Figure 2.

Figure 2: Menu items of the CommandState package

There is a hidden fifth menu item with the text “Changes Visibility #2”. When you click any of the Changes Visibility items, #1 and #2 are swapped. The “Click count: 0” item counts every click and indicates this counter in the menu text. The bottom menu item changes its availability. It is enabled when the click count above is an even number; otherwise it is disabled. So clicking 3 times on the Changes Visibility items and three times on the Click count item leads to the command status result that is illustrated in Figure 3.

Figure 3: Menu items after changing their visibility state

Listing 1 shows the command table defining the layout of the menu and initial state of commands.

Listing 1: CommandState.vsct

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <Extern href="stdidcmd.h"/>
  <Extern href="vsshlids.h"/>
  <Extern href="msobtnid.h"/>
  <Commands package="guidCommandStatePkg">
    <Groups>
      <Group guid="guidCommandStateCmdSet" id="MyMenuGroup" priority="0x0600">
        <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>
      </Group>
    </Groups>
 
    <Buttons>
      <Button guid="guidCommandStateCmdSet" id="AlwaysVisibleAndEnabled"
        priority="0x0100" type="Button">
        <Parent guid="guidCommandStateCmdSet" id="MyMenuGroup" />
        <Icon guid="guidOfficeIcon" id="msotcidClock" />
        <Strings>
          <CommandName>AlwaysVisibleAndEnabled</CommandName>
          <ButtonText>Always visible and enabled</ButtonText>
        </Strings>
      </Button>
 
      <Button guid="guidCommandStateCmdSet" id="ChangesVisibility1"
        priority="0x0200" type="Button">
        <Parent guid="guidCommandStateCmdSet" id="MyMenuGroup" />
        <Icon guid="guidOfficeIcon" id="msotcid1" />
        <CommandFlag>DynamicVisibility</CommandFlag>
        <Strings>
          <CommandName>ChangesVisibility1</CommandName>
          <ButtonText>Changes Visibility #1</ButtonText>
        </Strings>
      </Button>
      <Button guid="guidCommandStateCmdSet" id="ChangesVisibility2"
        priority="0x0300" type="Button">
        <Parent guid="guidCommandStateCmdSet" id="MyMenuGroup" />
        <Icon guid="guidOfficeIcon" id="msotcid2" />
        <CommandFlag>DynamicVisibility</CommandFlag>
        <CommandFlag>DefaultInvisible</CommandFlag>
        <CommandFlag></CommandFlag>
        <Strings>
          <CommandName>ChangesVisibility2</CommandName>
          <ButtonText>Changes Visibility #2</ButtonText>
        </Strings>
      </Button>
 
      <Button guid="guidCommandStateCmdSet" id="ChangesText"
        priority="0x0400" type="Button">
        <Parent guid="guidCommandStateCmdSet" id="MyMenuGroup" />
        <Icon guid="guidOfficeIcon" id="msotcidPaperStack" />
        <CommandFlag>TextChanges</CommandFlag>
        <Strings>
          <CommandName>ChangesText</CommandName>
          <ButtonText>Click count: 0</ButtonText>
        </Strings>
      </Button>
 
      <Button guid="guidCommandStateCmdSet" id="ChangesEnabledState"
        priority="0x0500" type="Button">
        <Parent guid="guidCommandStateCmdSet" id="MyMenuGroup" />
        <Icon guid="guidOfficeIcon" id="msotcidBlank" />
        <Strings>
          <CommandName>ChangesEnabledState</CommandName>
          <ButtonText>Enabled on even click count</ButtonText>
        </Strings>
      </Button>
    </Buttons>
  </Commands>
 
  <Symbols>
    <GuidSymbol name="guidCommandStatePkg"
      value="{ff5ab687-afbb-46c1-8542-17510542549a}"/>
    <GuidSymbol name="guidCommandStateCmdSet"
      value="{ab0f163e-cd16-404d-a378-60423d214c32}">
      <IDSymbol name="MyMenuGroup" value="0x1020" />
      <IDSymbol name="AlwaysVisibleAndEnabled" value="0x0100" />
      <IDSymbol name="ChangesVisibility1" value="0x0101" />
      <IDSymbol name="ChangesVisibility2" value="0x0102" />
      <IDSymbol name="ChangesText" value="0x0103" />
      <IDSymbol name="ChangesEnabledState" value="0x0104" />
    </GuidSymbol>
  </Symbols>
 
</CommandTable>

Each menu item representing a command is set up a bit differently than the others. Button elements can define flags determining their behavior in CommandFlag elements as highlighted in the listing. Table 3 describes the behavior defined by the initial settings of Button elements.

Table 3: Behavior of Button elements

*Button element ID*	*Description*
AlwaysVisibleAndEnabled	This element does not define any flags to handle the visibility properties dynamically, so its visibility state is always the default (visible). Even if the package is loaded, its visibility state is never queried.
ChangesVisibility1	By using the DynamicVisibility command flag this item is visible unless the package is loaded. When the package gets sited, the command target is queried for visibility status.
ChangesVisibility2	This element combines the DefaultInvisible flag with DynamicVisibility. As a result, it behaves exactly like ChangesVisibility1 except that its initial state is invisible.
ChangesText	Here the TextChanges command flag is used. While the package is not loaded the string specified in the ButtonText element is used as the label of the command. When the package is loaded Visual Studio asks the package for the label text before displaying the command.
ChangesEnabledState	Similarly to the AlwaysVisibleAndEnabled command this element does not define any flags to handle visibility state dynamically. However, you change the availability of the command programmatically and the appearance of the menu item follows it. This is because as soon as the package gets loaded availability status is queried before displaying the menu item.

The command table defines only the initial visual state of commands and some of them are changed during runtime. Listing 2 contains the source code for the CommandStatePackage class that defines this behavior:

Listing 2: CommandStatePackage.cs

using System;
using System.Runtime.InteropServices;
using System.ComponentModel.Design;
using System.Text;
using Microsoft.VisualStudio.Shell.Interop;
using Microsoft.VisualStudio.Shell;
 
namespace DeepDiver.CommandState
{
  [PackageRegistration(UseManagedResourcesOnly = true)]
  [InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
  [ProvideMenuResource("Menus.ctmenu", 1)]
  [Guid(GuidList.guidCommandStatePkgString)]
  public sealed class CommandStatePackage : Package
  {
    private OleMenuCommandService _CommandService;
    private OleMenuCommand _ChangesVisibility1;
    private OleMenuCommand _ChangesVisibility2;
    private OleMenuCommand _ChangesText;
    private OleMenuCommand _ChangesEnabledState;
    private int _ClickCount;
 
    protected override void Initialize()
    {
      base.Initialize();
      _CommandService = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;
      RegisterCommand(CmdIDs.AlwaysVisibleAndEnabled, AlwaysVisibleCallback);
      _ChangesVisibility1 =
        RegisterCommand(CmdIDs.ChangesVisibility1, ChangesVisibilityCallback);
      _ChangesVisibility2 =
        RegisterCommand(CmdIDs.ChangesVisibility2, ChangesVisibilityCallback);
      _ChangesVisibility2.Visible = false;
      _ChangesText =
        RegisterCommand(CmdIDs.ChangesText, ChangesTextCallback);
      _ChangesEnabledState =
        RegisterCommand(CmdIDs.ChangesEnabledState, ChangesEnabledStateCallback);
    }
 
    private void AlwaysVisibleCallback(object caller, EventArgs args)
    {
      OutputCommandString("'Always visible and enabled' command executed.");
    }
 
    private void ChangesVisibilityCallback(object caller, EventArgs args)
    {
      _ChangesVisibility1.Visible = !_ChangesVisibility1.Visible;
      _ChangesVisibility2.Visible = !_ChangesVisibility1.Visible;
      OutputCommandString("Visibility of buttons #1 and #2 swapped.");
    }
 
    private void ChangesTextCallback(object caller, EventArgs args)
    {
      _ChangesText.Text = String.Format("Click count: {0}", ++_ClickCount);
      _ChangesEnabledState.Enabled = _ClickCount % 2 == 0;
      OutputCommandString("Current click counter is " + _ClickCount);
    }
 
    private void ChangesEnabledStateCallback(object caller, EventArgs args)
    {
      OutputCommandString("Command is enabled at click count " + _ClickCount);
    }
 
    private OleMenuCommand RegisterCommand(uint id, EventHandler callback)
    {
      if (_CommandService == null) return null;
      var menuCommandID = new CommandID(GuidList.guidCommandStateCmdSet, (int)id);
      var menuItem = new OleMenuCommand(callback, menuCommandID);
      _CommandService.AddCommand(menuItem);
      return menuItem;
    }
 
    private void OutputCommandString(string text)
    {
      // --- Build the string to write on the debugger and Output window.
      var outputText = new StringBuilder();
      outputText.AppendFormat("CommandStatePackage: {0}
", text);
      // --- Get a reference to IVsOutputWindow.
      var outputWindow = GetService(typeof(SVsOutputWindow)) as IVsOutputWindow;
      if (outputWindow == null) return;
 
      // --- Get the window pane for the general output.
      var guidGeneral = Microsoft.VisualStudio.VSConstants.GUID_OutWindowDebugPane;
      IVsOutputWindowPane windowPane;
      if (Microsoft.VisualStudio.ErrorHandler.Failed(
        outputWindow.GetPane(ref guidGeneral, out windowPane)))
      {
        return;
      }
      // --- As the last step, write to the output window pane
      windowPane.OutputString(outputText.ToString());
      windowPane.Activate();
    }
  }
}

The package sets up command bindings in the overridden Initialize methods. Commands use the event handler methods having a Callback suffix. The RegisterCommand helper method carries out the necessary steps to bind a command handler to its logical command. Each command generates a diagnostic message to the Debug pane of the Output window in Visual Studio, OutputCommandString implements this functionality. Output window handling is treated in details in Chapter 3: Window Management and Tool Windows so there you will find more explanation about how OutputCommandString method works.

In the FirstLook sample at the beginning of this chapter you could see a MenuCommand instance was used as the command binder, whilst in this example OleMenuCommand instances are used. OleMenuCommand derives from MenuCommand and this kind of object is passed as the sender argument in the event handler methods. Each OleMenuCommand instances represent the command binders in private fields, and later these are used to change command status. The RegisterCommand method is implemented so that it retrieves the binder object.

AlwaysVisibleCallback simply generates an output message.

You can observe that both _ChangesVisibility1 and _ChangesVisibility2 are bound to ChangesVisibilityCallback that is a very simple method swapping the current visibility states of these two commands:

private void ChangesVisibilityCallback(object caller, EventArgs args)
{
  _ChangesVisibility1.Visible = !_ChangesVisibility1.Visible;
  _ChangesVisibility2.Visible = !_ChangesVisibility1.Visible;
  OutputCommandString("Visibility of buttons #1 and #2 swapped.");
}

The menu binder triggering the event is passed in the caller argument, so you could write the code above like this:

private void ChangesVisibilityCallback(object caller, EventArgs args)
{
  var command = caller as OleMenuCommand;
  if (command == null || (command.CommandID.ID != CmdIDs.ChangesVisibility1 &&
    command.CommandID.ID != CmdIDs.ChangesVisibility2))
  {
    return;
  }
  _ChangesVisibility1.Visible = command.CommandID.ID == CmdIDs.ChangesVisibility2;
  _ChangesVisibility2.Visible = !_ChangesVisibility1.Visible;
  OutputCommandString("Visibility of buttons #1 and #2 swapped.");
}

You need an additional step to make the swapping commands work correctly: you have to initialize the visibility state of _ChangesVisibility2 to hidden in the Initialize method:

_ChangesVisibility1 = 
  RegisterCommand(CmdIDs.ChangesVisibility1, ChangesVisibilityCallback);
_ChangesVisibility2 =
  RegisterCommand(CmdIDs.ChangesVisibility2, ChangesVisibilityCallback);
_ChangesVisibility2.Visible = false;

If you omit the last line, the package seems working properly. But click on the Always visible and enabled item first and then drop down the Tools menu. You will observe some unexpected thing as Figure 4 shows.

Figure 4: Both Changes Visibility commands are visible!

What’s wrong with the command logic? If you invoke the Always visible and enabled item first, it causes the package to load. The Initialize method runs and creates the binders for the Changes Visibility items. By default these binders are created with their Visibility property set to true. Because the package is loaded, the IDE uses the package to query the visibility status when you drop down the Tools menu and this time both commands are visible.

The ChangesText command also uses a very simple logic:

private void ChangesTextCallback(object caller, EventArgs args)
{
  _ChangesText.Text = String.Format("Click count: {0}", ++_ClickCount);
  _ChangesEnabledState.Enabled = _ClickCount%2 == 0;
  OutputCommandString("Current click counter is " + _ClickCount);
}

It uses the _ClickCount member variable to count the number of clicks and updates the label of the command through the Text property. This command controls the availability of the ChangesEnabledState command. Try to omit the TextChanges flag from the command table and run the package. You can use the ChangesText command — as you click the availability status of ChangesEnabledState switches between enabled and hidden — but the count of click is not displayed.

You do not need an event handler method for the ChangesEnabledState command, because its state is handled by the ChangesTextCallback method, but in this example the handler is used to display a trace message.

Commands and Visibility

When you move around in Visual Studio you can see that a few toolbars, menus and menu items are visible or invisible depending on the context you are in. For example, the Project and Debug menu items cannot be seen while there is no project open. Similarly, you cannot reach the Team menu unless you connect to a Team Server.

Visual Studio shows or hides commands according to the current context. Please note, showing or hiding commands means to make them visible or invisible. If a command is visible, availability state also influences the appearance — disabled commands are dimmed — but availability is totally independent of visibility.

Commands can be defined in different locations — they logically belong to one of the following entities:

The VS IDE environment. All commands defined by the Visual Studio IDE are always visible.
Packages registered in the IDE. Packages may define commands and decide whether to show or hide a certain command. Please remember that Visual Studio IDE is a combination of the core IDE (Shell) and the packages registered with the IDE. When you install Visual Studio many packages also get registered.
The active project. In Visual Studio you work with solutions that contain projects. There can be only one active project (the currently selected project) determined by either the active editor file or the item selected in the Solution Explorer. All the other projects (if there are any others in the solution) are inactive. Only the commands belonging to the active project are visible.
Active editor. When you edit a source file in the text editor or a form with the form editor or creating a class diagram, you work with an editor. If you have documents open you always have one active editor (and might have a set of inactive ones). The active editor can define its own commands (think about the Windows Forms editor). The commands defined by the active editors are visible, but any commands of other (inactive) editors are hidden. There are editors that support a variety of file types (e.g. the Image Editor). There can be commands that are available for one file type but not for another file type. For instance, you can set the transparent pixels for an icon but not for a .BMP file in the image editor. It is always the responsibility of the editor to show or hide a command depending on the file type currently used.
Tool windows. Packages can register tool windows and tool windows can have their own commands. When you register a package providing a tool window with Visual Studio, the related commands are visible by default. Of course, to make them appear on the screen you must show up the tool window.

Any time when you are in a concrete Visual Studio context all visible commands from the locations above are merged. So, the union of IDE environment commands, package commands, active project commands, active editor commands (depending on the file type) and visible tool window commands determine the set of visible commands.

You may feel that something is missing. As it has been treated here commands are visible or hidden for a package, editor or tool window. An example was also mentioned earlier that the Project and Debug menus are not available unless a file or a project is opened. How does this fit into the picture? How does Visual Studio handle this thing? How can a package make a command visible or hidden depending on whether a project is open or closed?

Visual Studio allows further control about command visibility. The IDE defines visibility contexts and commands can be bound to them. The most frequently used contexts are summarized in Table 4.

Table 4: User interface context definitions

*Context name*	*Description*
NoSolution	No solution is opened in the IDE (the Solution Explorer tool window is empty).
SolutionExists	There is an existing solution opened in the IDE. This can be an empty solution, a solution created by opening a single file, a solution with one or more project. Commands bound to this context are visible if you can see a root solution in the Solution Explorer.
EmptySolution	There is a solution opened in the IDE and this solution is empty (does not contain any item).
SolutionHasSingleProject	There is a solution opened in the IDE and this solution contains exactly one project of any type.
SolutionHasMultipleProjects	There is a solution opened in the IDE and this solution contains multiple projects loaded.
SolutionBuilding	The current solution or any of its projects is being built. The IDE stays in this context unless the build process finishes.
Debugging	The IDE is in Debug mode: its debugger is attached to a running process.
DesignMode	The IDE is in design mode (not in Debug mode).
FullScreenMode	The IDE is running in Full screen mode (it can be activated with the View \| Full Screen function.
Dragging	Currently there is an active drag/drop operation in the Visual Studio IDE.

When a command is bound to a set of visibility contexts it is visible only when Visual Studio IDE is in one of the contexts bound to it. You can define your own contexts and notify Visual Studio about entering into the specified context. Commands can be also bound to your custom contexts. Later in this chapter you are going to see a few code samples about handling visibility contexts.

The Visual Studio Command Table

You have already seen the Visual Studio Command Table in a few examples in the previous and also in this chapter. The command table is defined in the .vsct file of the package project and is compiled to a binary resource which is embedded into the package infrastructure resources during the build process. When deploying the package the command table is merged into the menus and toolbars of the IDE.

In this section you dive into the details of the command table structure and create a few more samples to understand the basic concepts. Of course, all nitty-gritty details cannot be handled, but the information here is enough that you can to discover the advanced aspects of the command table by yourself.

Note: The .vsct file was introduced as a new format for the command table substituting the .ctc file in the previous versions of Visual Studio SDK. Visual Studio 2005 SDK used a textual format (using files with .ctc extension). Editing and understanding a .ctc file was not a simple task. With the release of Visual Studio 2008 SDK Microsoft created the new XML-based file format with the .vsct extension and a new compiler to produce the binary .cto format.

The main advantage of using the .vsct file is that it is editable just like other XML files and so has all the great XML editing features like automatic generation of closing tags or IntelliSense based on the VSCT XML schema. Due to the fact XML format has so many advantage the old .ctc format has been deprecated. Microsoft recommends using the VSCT compiler to generate the .cto files, although CTC is still supported.

VSCT File Structure

When describing the elements of an XML file one alternative is to provide an XSD schema. It tells a lot about the syntax and the semantics and is said to be readable by either a human or a machine. There is no doubt that machines can easily understand an XSD, but for understanding concepts behind a certain XML file XSD is not the best way. Instead, here you will be shown small examples to help you understand the structure of the command file.

The root element of this structure is the CommandTable element:

<?xml version="1.0" encoding="utf-8"?>
<CommandTable
  xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <!-- Content of the command table -->
</CommandTable>

The elements of the command table are defined by the http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable namespace. You will rarely create the startup state of a command table by hand, because the VSPackage wizard does it for you when you ask it to create an initial command or tool window. When you create the command table by hand, do not forget about specifying this namespace otherwise your command table will not compile. In the code examples later the namespace information will be omitted just for the sake of brevity.

The CommandTable itself uses a few child elements to define the content of the table:

<CommandTable xmlns="..." xmlns:xs="...">
  <Extern/>
  <Include/>
  <Define/>
  <Commands/>
  <CommandPlacements>
  <VisibilityConstraints/>
  <KeyBindings/>
  <UsedCommands/>
  <Symbols/>
</CommandTable>

For a developer new to Visual Studio Extensibility, the Extern, Commands and Symbols elements are the most important and, of course, the most frequently used ones. When the VSPackage wizard creates a package with a simple menu command, you get something similar (the wizard injects a lot of comments to explain the content but here those are omitted):

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="..." xmlns:xs="...">
  <Extern href="stdidcmd.h"/>
  <Extern href="vsshlids.h"/>
  <Extern href="msobtnid.h"/>
 
  <Commands package="guidSimpleCommandPkg">
    <Groups>
      <Group guid="guidSimpleCommandCmdSet" id="MyMenuGroup" priority="0x0600">
        <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>
      </Group>
    </Groups>
 
    <Buttons>
      <Button guid="guidSimpleCommandCmdSet" id="cmdidMyFirstCommand"
        priority="0x0100" type="Button">
        <Parent guid="guidSimpleCommandCmdSet" id="MyMenuGroup" />
        <Icon guid="guidImages" id="bmpPic1" />
        <Strings>
          <CommandName>cmdidMyFirstCommand</CommandName>
          <ButtonText>My First Command</ButtonText>
        </Strings>
      </Button>
    </Buttons>
 
    <Bitmaps>
      <Bitmap guid="guidImages" href="Resources\Images_32bit.bmp"
        usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
    </Bitmaps>
  </Commands>
 
  <Symbols>
    <GuidSymbol name="guidSimpleCommandPkg"
      value="{2291da24-92e5-4ea4-bdb7-72a9b5ac7d59}" />
    <GuidSymbol name="guidSimpleCommandCmdSet"
      value="{a982b107-4ad4-437e-b2bc-cdf2708aa376}">
      <IDSymbol name="MyMenuGroup" value="0x1020" />
      <IDSymbol name="cmdidMyFirstCommand" value="0x0100" />
    </GuidSymbol>
    <GuidSymbol name="guidImages" value="{5c3faf04-8190-48c4-a6e9-71f04f1848e5}" >
      <IDSymbol name="bmpPic1" value="1" />
      <IDSymbol name="bmpPic2" value="2" />
      <IDSymbol name="bmpPicSearch" value="3" />
      <IDSymbol name="bmpPicX" value="4" />
      <IDSymbol name="bmpPicArrows" value="5" />
    </GuidSymbol>
  </Symbols>
 
</CommandTable>

You already know that commands and other elements of the command table objects are uniquely identified by a compound key composed from a GUID and a 32-bit unsigned integer. Command table elements have references to each other and the unique identifiers are used to describe this reference. The parts of the key are defined by the guid and id attributes, respectively.

In a .vsct file you generally use most element identifiers at least twice: once for identifying an object and at least once for referencing it. If you would use the GUID and uint values directly those would not provide the best readability. If you had to type the same GUID value several times it would make the hand-edited .vsct file very fragile, as humans are not very good in typing, comparing and checking GUID values.

The Symbols section is a central place in the command table file where you can define the identifiers to be used in the other parts of the .vsct file. You can use the GuidSymbol element to define the logical container represented by the GUID and the nested IDSymbol elements to provide (optional) identifiers within the logical container. The name and the value attribute of these elements do exactly what you expect: associate the symbol name with its value. The GUID and uint values of the compound key are checked together, the VSCT compiler takes care of that the uint value should be defined by an IDSymbol nested in the corresponding GuidSymbol elements value.

In the example above there are three GUID containers defined. The first is an empty container (with the symbolic name of guidSimpleCommandPkg) the last two contain a few nested ID elements. The identifiers defined here are referenced in the upper parts of the command table definition as in the following extract:

<Commands package="guidSimpleCommandPkg">
  <Groups>
    <Group guid="guidSimpleCommandCmdSet" id="MyMenuGroup" priority="0x0600">
      <!-- ... -->
    </Group>
  </Groups>
 
  <Buttons>
    <Button guid="guidSimpleCommandCmdSet" id="cmdidMyFirstCommand"
      priority="0x0100" type="Button">
      <!-- ... -->
    </Button>
  </Buttons>
 
  <Bitmaps>
    <Bitmap guid="guidImages" href="Resources\Images_32bit.bmp"
      usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
  </Bitmaps>
</Commands>

Objects defined by the Visual Studio IDE are frequently referenced in the command table. For example, when you add a menu item to the Tools menu, somehow you must refer to the Tools menu so that the VSCT compiler can understand it. Of course, the Tools menu is identified on the same way as any other command table elements:

<Group guid="guidSimpleCommandCmdSet" id="MyMenuGroup" priority="0x0600">
  <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>
</Group>

Here the Parent element defines the location where the logical command group declared by the Group element should be placed. The guidSHLMainMenu defines the logical container of the main menu bar of the IDE and the IDM_VS_MENU_TOOLS is the identifier of the Tools menu within the logical container. As you guess, there are thousands of GUIDs and IDs related to Visual Studio IDE elements.

The Extern element is the key to access them:

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="..." xmlns:xs="...">
  <Extern href="stdidcmd.h"/>
  <Extern href="vsshlids.h"/>
  <Extern href="msobtnid.h"/>
  <!-- ... -->
</CommandTable>

When the VSCT compiler processes the .vsct file it can run a preprocessor on its content. This preprocessor is by default the C++ preprocessor that allows including files defining symbols and macros. The Extern element is one of the elements directing the preprocessor. The href attribute names the file with .h (standard C++ header file) extension. After the preprocess phase the symbols in the #define pragmas and in the macro definitions of referenced files can be used anywhere just like GUID and ID values defined in the Symbols section of the command table.

The files named in the href attributes are searched in the include path passed to the VSCT compiler. This is the VisualStudioIntegration\Common\Inc folder under the root installation folder of VS SDK by default when you create your package with the VSPackage wizard. The wizard also creates three Extern elements. Table 5 describes the role of the referenced files.

Table 5: External file references in the VSCT file

File	Content
stdidcmd.h	This file represents the command IDs for all commands exposed by Visual Studio. IDs include the visible (or hidden) menu command IDs prefixed with cmdid, standard editor commands with ECMD_ prefix and a few others.
vsshlids.h	This file collects command IDs for the menus provided by the Visual Studio Shell.
msobtnid.h	This file represents IDs of the standard Microsoft Office commands (many of them, like Cut, Copy and Paste are also used in VS IDE).

If you look into the header files, you can find the definitions for guidSHLMainMenu and IDM_VS_MENU_TOOLS in the vsshlids.h file. The preprocessor understands both the DEFINE_GUID macro and the #define pragma.

...
DEFINE_GUID (guidSHLMainMenu,
  0xd309f791, 0x903f, 0x11d0, 0x9e, 0xfc, 0x00, 0xa0, 0xc9, 0x11, 0x00, 0x4f);
...
#define IDM_VS_MENU_TOOLS 0x0085
...

The DEFINE_GUID macro here sets the guidSHLMainMenu to the value of {d309f791-903f -11d0-9efc-00a0c911004f}. Any time you know a GUID value but you do not know which symbolic name is used for that value, search the VisualStudioIntegration\Common\Inc folder to find if the GUID value is defined there or not. If necessary add a new Extern directive to the command table.

Command Definitions

No doubt, the most important element of the .vsct file is Commands. Its role is to define commands, their initial layout and behavior:

<Commands package="...">
  <Groups/>
  <Menus/>
  <Buttons/>
  <Combos/>
  <Bitmaps/>
</Commands>

Any command in the IDE must belong to the IDE itself or to a package. A package assembly can implement one or more packages. To assign a command to the appropriate (owning) VSPackage, the package attribute of the Commands element must name the GUID of the corresponding package. Generally you have only one package in one assembly so you put the package ID generated by the VSPackage wizard into this attribute:

<Commands package="guidSimpleCommandPkg">
  <!-- ... -->
</Commands>

As you obviously guessed Visual Studio uses the package ID here to find out which package is to be loaded to handle a command. There are several types of nested child elements in Commands, and each of them has a specific role.

The Groups element defines so-called command groups using a nested Group element. A command group is a logical set of related commands that generally stand together. For example, the Build Solution, Rebuild Solution and Clean Solution menu items form a logical group: they stand together in the Build menu and in the context menu of a Solution item as shown in Figure 5.

Figure 5: Visual effect of a Group element

Instead of putting individual commands to an existing menu you can place them into a group and that group can be placed to the menu. Even if you have only one element to add to a menu, you must create a Group element for it and put the item into this group. Visual Studio menu groups also have related symbolic IDs in the header files, so you can add a command to one of the predefined groups. Each command in the logical set formed by the group appears in the related menu.

You can nest Menu elements as children of Menus to define a single menu. A single menu is a placeholder for items and of course, you also can put submenu items there.

Menus can have different appearance and behavior. The most frequent forms are:

Standard menus (for example the File, Edit and View menus in the IDE).
Context menus: They show up when right-clicking on the object they provide a command context for.
Toolbars: standard toolbars where commands are organized in rows with icons — and/or text labels — representing them.

The Buttons element is a container for nested Button elements. A Button represents a piece of user interface the user can interact with. The name is a bit confusing, because when saying the word button you generally associate it with the pushbutton. Here, Button relates to a menu or toolbar item. In .vsct you can define a few types of Button items:

Standard buttons represent a simple menu items which execute a command.
Menu buttons display a submenu.
Dropdown buttons allow functions like Undo and Redo on the main toolbar of the IDE.
“Swatch” buttons display color choices such as those in a font color dialog.

Not surprisingly Combos is a container for Combo elements. A Combo defines a set of commands that appear in a combo box.

Toolbars and menus would be poor without icons helping the user to associate a small image with the function. The Bitmaps section allows defining the visual elements (icons) used in menus. The section describes Bitmap elements that are uniquely identified. A bitmap can come from an external file or from a package resource.

When referring to bitmaps, you can use a few formats like .bmp, .gif, .png. Right now you cannot use all formats in the same way. For example, you may have problems with the 32-bit .bmp formats (alpha channel information for partial transparency). If you use 120 DPI in your display settings, the original 16x16 pixel images will be stretched to a 20x20 pixel size. If you use .png format, stretching is smooth without disturbing artifacts. In some cases only a few formats are accepted: for example for icons representing tool windows on their tabs, .png format is not welcomed (no icon appears), only 24-bit .bmp with fuchsia as the transparent color.

If you have problems with icon images, try a few formats and you can generally find the one expected by VS IDE.

Working with Commands and Bitmaps

To successfully define commands appearing in the VS IDE menus you have to use at least one Group and one Button element. If you want to add icons, you need at least one additional Bitmap element. If you prefer your own menu instead of inserting a command group in the middle of a Visual Studio menu, at least one Menu element should be defined. To establish the layout and the relation among the elements you have to look behind their attributes and child elements.

Menu, Group, Button and other elements have common attributes and child element with very similar semantics summarized in Table 6.

Table 6: Common attributes of command table elements

*Attribute*	*Description*
guid	The GUID part of the element identifier. This attribute is required.
id	The uint part of the element identifier. This attribute is required.
priority	An optional numeric value determining the order of the element. The lower this value is the closer the element is to the position of the first element. Visual Studio IDE sorts elements according to their priority. However, you cannot know the priority value of all other elements, so exact position is not guaranteed.
type	An optional stereotype of the element determining its layout and behavior. The Group element does not have this attribute (as it is a behavior-less element). The possible values and the meaning of this attribute changes according to the element type.

There are child elements connecting UI elements together and adding properties which fine-tune layout and behavior. Except of Bitmap all other types of Commands children have the child elements in Table 7.

Table 7: Common child elements

Child element

Description

Parent

Optional parent of the element. A command element can be attached to one or more menu items. Here you can define zero or one Parent element. If you want to attach a command to more than one menu item, the CommandPlacement element is for you.

The Parent element has the guid and id attribute to uniquely name the parent the element belongs to. For a Button the parent element must refer to a command Group. For a Group, the parent must refer to a Menu.

Annotation

This element allows adding optional comment information to the element. Annotations can have either simple text or a nested structure.

Table 8 summarizes child elements extending the layout and behavior of Menu, Button and Combo.

Table 8: Child elements influencing behavior

*Child element*	*Description*
CommandFlag	This child element can be applied zero, one or more times to its parent element. As the name indicates it sets flags influencing the layout and behavior of its parent. The VSCT Schema Reference enumerates all the command flags that can be applied to a particular element. Several flags have effect only when combining with other flags. For example, applying the DynamicVisibility and DefaultInvisible flags causes a menu item to be hidden at Visual Studio startup time.
Strings	This element is a container for children representing string information of UI elements. At least the ButtonText child of Strings should be applied to display a caption for the element. Possible child elements include ButtonText, ToolTipText, MenuText, CommandName and others. For details see the VSCT Schema reference.
Icon	Available only for Button. Optionally defines the icon associated with the button.

The Bitmaps section of Commands provides a place to define bitmaps you want to use in menu and toolbar items. Each definition must be in a Bitmap element. The concept of Bitmap covers one bitmap with a physical size of 16x16 pixels or a bitmap strip that has 16xN pixels where N is a multiple of 16 (number of pixels in a column). Bitmap handles the simple 16x16 pixel bitmap as a bitmap strip, where N equals 1. A Bitmap is identified with a GUID that must be a separate GUID from the package ID, command set IDs, and so on. When you refer to a certain item in the bitmap strip you do it by using a one-based index for the bitmap in the strip.

Just as in case of commands, menu IDs you can use the Symbols section of the command table to define IDs related to a bitmap. For example when you create a new Tool window package With the VSPackage wizard, the following entries are related to bitmaps:

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="..." xmlns:xs="...">
  <!-- Extern elements -->
  <Commands package="...">
    <!-- Menus, Groups and Buttons -->
    <Bitmaps>
      <Bitmap guid="guidImages" href="Resources\Images_32bit.bmp"
        usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
    </Bitmaps>
  </Commands>
  <Symbols>
    <GuidSymbol name="guidImages" value="{...}" >
      <IDSymbol name="bmpPic1" value="1" />
      <IDSymbol name="bmpPic2" value="2" />
      <IDSymbol name="bmpPicSearch" value="3" />
      <IDSymbol name="bmpPicX" value="4" />
      <IDSymbol name="bmpPicArrows" value="5" />
    </GuidSymbol>
  </Symbols>
</CommandTable

The Symbols section defines a GUID used only by the Bitmap definition (guidImages) and symbolic names for the one-based bitmap indexes within the strip. In the example above bmpPicSearch is the third picture within the strip.

The Bitmap element’s href attribute names the file where the bitmap strip can be found. This folder is relative to the location of the .vsct file. The usedList attribute enumerates the symbolic indices that can be used to identify bitmaps in the strip. If you want to set a button icon to the third image in the strip, you should use the following Icon child element in a Button:

<Button ...="">
  <Icon guid="guidImages" id="bmpPicSearch" >
</Button>

You are allowed to use stocked icons. For example, the CommandState sample uses such icons:

<Icon guid="guidOfficeIcon" id="msotcidClock" />

The guidOfficeIcon symbol is defined in the vsshlids.h file and is a logical container for office icons. The msotcidClock and thousands of other IDs can be found in the msobtnid.h file. If you are looking for stocked icons, definitely this is the place you should search for them. The msobtnid.h contains comments that help you to identify icons you are looking for.

Basic VSCT Samples

By now you have an understanding of the essential VSCT concepts, moreover, you have seen a few samples. In order to illustrate the structure and usage of command table element you are going to build a few more samples. You start from a very simple package created with the help of VSPackage wizard using a simple menu command. The package does not have any real function, because it is just a container for menu resources, the package class definition is quite simple as Listing 3 shows.

Listing 3: The BasicVSCTSamplePackage definition

// --- BasicVSCTSamplePackage.cs
 
using System.Runtime.InteropServices;
using Microsoft.VisualStudio.Shell;
 
namespace DeepDiver.BasicVSCTSample
{
  [PackageRegistration(UseManagedResourcesOnly = true)]
  [InstalledProductRegistration(false, "#110", "#112", "1.0", IconResourceID = 400)]
  [ProvideMenuResource("Menus.ctmenu", 1)]
  [Guid(GuidList.guidBasicVSCTSamplePkgString)]
  public sealed class BasicVSCTSamplePackage : Package
  {
  }
}
 
// --- Guids.cs
 
namespace DeepDiver.BasicVSCTSample
{
  static class GuidList
  {
    public const string guidBasicVSCTSamplePkgString =
      "41fe6025-c174-4d02-af4f-ea948a272830";
  }
}

You are going to work only with the BasicVSCTSample.vsct file. You start from simple scenario and transform the .vsct file to discover new usage opportunities. You can use the VSPackage wizard to create the sample, or open the BasicVSCTSample project downloaded from the book’s website.

Creating a Main Menu Level Command

The VSPackage wizard puts menu items in a fixed place: in the Tools menu if you create a simple command or into the View menu if you create a simple tool window. However, when you create a package you often would like to put your own package-specific menu in the main menu bar of Visual Studio. Now you are going to learn how to do that.

You create a new main level menu VSCTSample with two menu command items. This task requires the following steps:

Step1: Create a GuidSymbol element with children for the symbols you are going to use. Nest this element in the Symbols section.
Step 2: Create a Menu element representing the main level menu. Put this item into the Menus section and set up the Parent of this menu to a main menu level menu group.
Step 3: Create a Group element representing the logical group holding the menu command items. Set the Parent of this group to the Menu created in the previous step.
Step 4: Create two Button elements representing the commands and set their Parent to the Group created previously.

Following the steps the .vsct file looks like in Listing 4.

Listing 4: Creating main menu commands

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable"
  xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <Extern href="stdidcmd.h"/>
  <Extern href="vsshlids.h"/>
  <Extern href="msobtnid.h"/>
 
  <Commands package="guidBasicVSCTSamplePkg">
    <Menus>
      <Menu guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenu" priority="0x100"
        type="Menu">
        <Parent guid="guidSHLMainMenu" id="IDG_VS_MM_BUILDDEBUGRUN" />
        <Strings>
          <ButtonText>VSCTSample</ButtonText>
          <CommandName>VSCTSample</CommandName>
        </Strings>
      </Menu>
    </Menus>
 
    <Groups>
      <Group guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenuGroup"
        priority="0x0600">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenu"/>
      </Group>
    </Groups>
 
    <Buttons>
      <Button guid="guidBasicVSCTSampleCmdSet" id="FirstCommand" priority="0x0100"
        type="Button">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <CommandName>FirstCommand</CommandName>
          <ButtonText>First Command</ButtonText>
        </Strings>
      </Button>
      <Button guid="guidBasicVSCTSampleCmdSet" id="SecondCommand"
        priority="0x0101" type="Button">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <CommandName>SecondCommand</CommandName>
          <ButtonText>Second Command</ButtonText>
        </Strings>
      </Button>
    </Buttons>
 
  </Commands>
 
  <Symbols>
    <GuidSymbol name="guidBasicVSCTSamplePkg"
      value="{41fe6025-c174-4d02-af4f-ea948a272830}" />
    <GuidSymbol name="guidBasicVSCTSampleCmdSet"
      value="{234580c4-8a2c-4ae1-8e4f-5bc708b188fe}">
      <IDSymbol name="TopLevelMenu" value="0x0100" />
      <IDSymbol name="TopLevelMenuGroup" value="0x0200" />
      <IDSymbol name="FirstCommand" value="0x0300" />
      <IDSymbol name="SecondCommand" value="0x0301" />
    </GuidSymbol>
  </Symbols>
 
</CommandTable>

As you see, you have to write quite a lot for such a simple task. In the menu definition the IDs used in the Parent elements are highlighted. If you build and run your package, you can discover the new menu located just after the View menu group and before the Tools menu as Figure 6 shows.

Figure 6: New main menu item

When you open a solution the Build menu gets visible and VSCTSample menu goes between Build and Debug as it can be seen in Figure 7.

Figure 7: VSCTSample is located between Build and Debug

This is due to the Parent definition of Menu and the priority you assigned to it:

<Menu guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenu" priority="0x100" type="Menu">
  <Parent guid="guidSHLMainMenu" id="IDG_VS_MM_BUILDDEBUGRUN" />
  <Strings>
    <ButtonText>VSCTSample</ButtonText>
    <CommandName>VSCTSample</CommandName>
  </Strings>
</Menu>

The IDG_VS_MM_BUILDDEBUGRUN is the identifier of a logical group representing the Build and Debug menus on the main VS IDE menu bar. The priority value of 0x100 sets our menu to be shown before the Debug menu. If you change priority to 0x700 (and rebuild the package and run) VSCTSample moves after the Debug menu, as Figure 8 shows.

Figure 8: Changing the location of VSCTSample item

Looking into the Button definition you may say there is no need for a Group definition: let’s set the Parent attribute of Buttons directly to the Menu item like in the following example:

<Button ...="">
  <Parent guid=" guidBasicVSCTSampleCmdSet " id="TopLevelMenu" />
  <!-- ... -->
</Button>

When running the package, no VSCTSample menu will appear. The cause of this phenomenon is the fact that buttons cannot have menus as parents. They must have command groups as parents to be displayed in a menu. Because your VSCTSample menu does not have any child, it is not displayed.

Separating Command Groups in a Menu

As it’s been treated, a command group is a logical container for commands belonging together. This kind of grouping also can be used for visual effects. If you put more than one command group in a menu, a separator is created to visually emphasize the separation of command groups. Let’s add two more commands with a separate group to the .vsct file you’ve created above:

Step 1: Add new symbols representing the two new buttons and the group for new commands.
Step 2: Create new Group definition
Step 3: Define two new Button elements parented in the newly created Group.

After the third step your new .vsct file looks like in Listing 5. Please note, only new parts added in the steps above are indicated in this listing:

Listing 5: Separating Command Groups in a Menu

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="..." xmlns:xs="...">
  <!-- Extern elements -->
  <Commands package="...">
    <!-- Menus section unchanged -->
 
    <Groups>
      <!-- New group added -->
      <Group guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenuGroup2"
        priority="0x0600">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenu"/>
      </Group>
    </Groups>
 
    <Buttons>
      <!-- New buttons added -->
      <Button guid="guidBasicVSCTSampleCmdSet" id="ThirdCommand" priority="0x0100"
        type="Button">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenuGroup2" />
        <Strings>
          <CommandName>ThirdCommand</CommandName>
          <ButtonText>Third Command</ButtonText>
        </Strings>
      </Button>
      <Button guid="guidBasicVSCTSampleCmdSet" id="FourthCommand"
        priority="0x0101" type="Button">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenuGroup2" />
        <Strings>
          <CommandName>FourthCommand</CommandName>
          <ButtonText>Fourth Command</ButtonText>
        </Strings>
      </Button>
    </Buttons>
  </Commands>
 
  <Symbols>
    <GuidSymbol name="guidHowToPackageCmdSet" value="{...}" >
      <!-- New IDSymbols added -->
      <IDSymbol name="TopLevelMenuGroup2" value="0x0201" />
      <IDSymbol name="ThirdCommand" value="0x0302" />
      <IDSymbol name="FourthCommand" value="0x0303" />
    </GuidSymbol>
    <!-- Other Guids for the package -->
  </Symbols>
 
</CommandTable>

Running the package after these modifications you can see the VSCTSample menu where the two command groups are separated, as shown in Figure 9.

Figure 9: Separating commands into groups

Adding Icons to the Menu Items

If you want to add icons to the menu items representing a command, you have to define a Bitmap node and assign it to the Button elements with their Icon property:

Step 1: Create IDs for the bitmap strip and each individual icon in the strip.
Step 2: Create the Bitmap element and set it up to use the icons in the strip.
Step 3: Add Icon properties to the buttons.

After this change the .vsct file changes as indicated in Listing 6.

Listing 6: Adding Icons to the Buttons

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="..." xmlns:xs="...">
  <!-- Extern elements -->
  <Commands package="...">
    <!-- Menus section unchanged -->
    <!-- Groups section unchanged -->
    <Buttons>
      <Button guid="guidBasicVSCTSampleCmdSet" id="FirstCommand" priority="0x0100"
        type="Button">
        <!-- Icon added, other children unchanged -->
        <Icon guid="guidImages" id="bmpPic1" />
      </Button>
      <Button guid="guidBasicVSCTSampleCmdSet" id="SecondCommand"
        priority="0x0101" type="Button">
        <!-- Icon added, other children unchanged -->
        <Icon guid="guidImages" id="bmpPic2" />
      </Button>
      <Button guid="guidBasicVSCTSampleCmdSet" id="ThirdCommand" priority="0x0100"
        type="Button">
        <!-- Icon added, other children unchanged -->
        <Icon guid="guidImages" id="bmpPicX" />
      </Button>
      <Button guid="guidBasicVSCTSampleCmdSet" id="FourthCommand"
        priority="0x0101" type="Button">
        <!-- Icon added, other children unchanged -->
        <Icon guid="guidImages" id="bmpPicArrows" />
      </Button>
    </Buttons>
 
    <Bitmaps>
      <!-- A new Bitmap added -->
      <Bitmap guid="guidImages" href="Resources\Images_24bit.bmp"
        usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
    </Bitmaps>
  </Commands>
 
  <Symbols>
    <!-- New GuidSymbol section added -->
    <GuidSymbol name="guidImages" value="{...}" >
      <IDSymbol name="bmpPic1" value="1" />
      <IDSymbol name="bmpPic2" value="2" />
      <IDSymbol name="bmpPicSearch" value="3" />
      <IDSymbol name="bmpPicX" value="4" />
      <IDSymbol name="bmpPicArrows" value="5" />
    </GuidSymbol>
    <!-- Other Guids for the package -->
  </Symbols>
 
</CommandTable>

As you can see, separate identifiers with bmp prefix are defined to index icons in the bitmap strip. The Bitmap element references the physical resource and in the usedList attribute enumerates the symbols for the icons which can be referenced in Button definitions. Button elements use the Icon node to name the bitmap with guidImages and the appropriate strip index with its symbolic name.

Running the package with this .vsct file results the menu in Figure 10.

Listing 10: Adding Icons to the buttons

Playing with CommandFlag Values

Menu item behavior can be influenced by using so-called command flags. To discover a few of them you modify two buttons with CommandFlag elements. Add a TextOnly flag to the first command. Although the first command has an associated Icon, the TextOnly command flag sets the menu item appearance to show only the text and not the icon. Add a DynamicVisibility and a DefaultDisabled flag to the third command. These flags initialize the command in disabled state by default. Listing 7 shows the changes.

Listing 7: Applying CommandFlags

<Buttons>
  <Button guid="guidBasicVSCTSampleCmdSet" id="FirstCommand" priority="0x0100"
    type="Button">
    <!-- CommandFlag added, other children unchanged -->
    <CommandFlag>TextOnly</CommandFlag>
  </Button>
  <Button guid="guidBasicVSCTSampleCmdSet" id="ThirdCommand" priority="0x0100"
    type="Button">
    <!-- CommandFlag added, other children unchanged -->
    <CommandFlag>DynamicVisibility</CommandFlag>
    <CommandFlag>DefaultDisabled</CommandFlag>
  </Button>
  <!-- Other buttons are unchanged -->
</Buttons>

After building and running the package you can recognize the effect of command flag applied as Figure 11 shows.

Figure 11: Using CommandFlag elements to modify behavior

Creating Submenus

You have already seen how to create a new main menu item and separate items visually by using command groups. Now you make a little modification to use submenus for grouping related commands. Remove the command flags you have added in Listing 7 and change the VSCT content:

Step 1: Rename the TopLevelMenuGroup2 to SubMenuGroup (and all references). You turn the group of third and fourth command into a submenu group.
Step 2: Add a new menu representing the submenu and attach it to the existing TopLevelMenuGroup. Name it SubMenu and create a symbol for it.
Step 3: Attach the SubMenuGroup to the newly created submenu.

Listing 8 indicates the changes you have done.

Listing 8: Moving commands into a submenu

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="...">
  <!-- Extern section unchanged -->
  <Commands package="guidHowToPackagePkg">
    <Menus>
      <!-- New menu added -->
      <Menu guid="guidBasicVSCTSampleCmdSet" id="SubMenu" priority="0x200"
        type="Menu">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <ButtonText>Other Commands</ButtonText>
          <CommandName>Other Commands</CommandName>
        </Strings>
      </Menu>
    </Menus>
    <Groups>
      <!-- Group changed to SubMenuGroup and attached to SubMenu -->
      <Group guid="guidBasicVSCTSampleCmdSet" id="SubMenuGroup"
        priority="0x0600">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="SubMenu"/>
      </Group>
    </Groups>
 
    <Buttons>
      <!-- We attached these two buttons to SubMenuGroup -->
      <Button guid="guidBasicVSCTSampleCmdSet" id="ThirdCommand" priority="0x0100"
        type="Button">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="SubMenuGroup" />
        <Icon guid="guidImages" id="bmpPicX" />
        <Strings>
          <CommandName>ThirdCommand</CommandName>
          <ButtonText>Third Command</ButtonText>
        </Strings>
      </Button>
      <Button guid="guidBasicVSCTSampleCmdSet" id="FourthCommand"
        priority="0x0101" type="Button">
        <Parent guid="guidBasicVSCTSampleCmdSet" id="SubMenuGroup" />
        <Icon guid="guidImages" id="bmpPicArrows" />
        <Strings>
          <CommandName>FourthCommand</CommandName>
          <ButtonText>Fourth Command</ButtonText>
        </Strings>
      </Button>
    </Buttons>
 
  </Commands>
 
  <Symbols>
    <!-- We add a SubMenu and changed SubMenuGroup -->
    <GuidSymbol name="guidBasicVSCTSampleCmdSet" value="...">
      <IDSymbol name="SubMenu" value="0x0101" />
      <IDSymbol name="SubMenuGroup" value="0x0201" />
    </GuidSymbol>
  </Symbols>
</CommandTable>

After building and running the package with the modified command table, you can see the submenu as Figure 12 shows.

Figure 12: Commands moved to a submenu

If you carefully examine the command table, you can observe the following nesting: TopLevelMenu --> TopLevelMenuGroup --> SubMenu --> SubMenuGroup --> Button elements. As you see, menus can be nested to each other through Group elements. Should you break this nesting the menu would not display as expected.

Adding Shortcut Keys to Menu Items

The command table allows you to bind shortcut keys to commands, and here you are going to examine this feature. Till this time you’ve used all commands in the BasicVSCTSample package that have no code behind to execute. In order to demonstrate that shortcut keys are working, add code to commands to display the name of the command invoked. Listing 9 shows the code of BasicVSCTSamplePackage:

Listing 9: Command handling in BasicVSCTSample

using System;
using System.ComponentModel.Design;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.VisualStudio.Shell;
using Microsoft.VisualStudio.Shell.Interop;
 
namespace DeepDiver.BasicVSCTSample
{
  [PackageRegistration(UseManagedResourcesOnly = true)]
  [InstalledProductRegistration(false, "#110", "#112", "1.0", IconResourceID = 400)]
  [ProvideMenuResource("Menus.ctmenu", 1)]
  [Guid(GuidList.guidBasicVSCTSamplePkgString)]
  public sealed class BasicVSCTSamplePackage : Package
  {
    private OleMenuCommandService _CommandService;
 
    protected override void Initialize()
    {
      base.Initialize();
      _CommandService = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;
      RegisterCommand(CmdIDs.FirstCommand, "First Command", CommandHandlerCallback);
      RegisterCommand(CmdIDs.SecondCommand, "Second Command", CommandHandlerCallback);
      RegisterCommand(CmdIDs.ThirdCommand, "Third Command", CommandHandlerCallback);
      RegisterCommand(CmdIDs.FourthCommand, "Fourth Command", CommandHandlerCallback);
    }
 
    private void CommandHandlerCallback(object caller, EventArgs args)
    {
      var command = caller as OleMenuCommand;
      if (command == null) return;
      OutputCommandString(command.Text + " has been invoked");
    }
 
    private void RegisterCommand(uint id, string initialText,
      EventHandler callback)
    {
      if (_CommandService == null) return;
      var menuCommandID = new CommandID(GuidList.guidBasicVSCTSampleCmdSet, (int)id);
      var menuItem = new OleMenuCommand(callback, menuCommandID) { Text = initialText };
      _CommandService.AddCommand(menuItem);
    }
 
    private void OutputCommandString(string text)
    {
      // --- Build the string to write on the debugger and Output window.
      var outputText = new StringBuilder();
      outputText.AppendFormat("BasicVSCTSamplePackage: {0}
", text);
      var outputWindow = GetService(typeof(SVsOutputWindow)) as IVsOutputWindow;
      if (outputWindow == null) return;
      var guidGeneral = Microsoft.VisualStudio.VSConstants.GUID_OutWindowDebugPane;
      IVsOutputWindowPane windowPane;
      if (Microsoft.VisualStudio.ErrorHandler.Failed(
        outputWindow.GetPane(ref guidGeneral, out windowPane)))
      {
        return;
      }
      windowPane.Activate();
      windowPane.OutputStringThreadSafe(outputText.ToString());
    }
  }
}

Each command invokes the CommandHandlerCallback method as a response for their invocation. This method uses the OutputCommandString method to display the name of the command. The RegisterCommand method is used to bind the commands to the code to execute and setup their Text property. Because you do not use the TextChanges command flag the values set here never get reflected in the menu items.

While shortcut keys are generally assigned to menu items, in Visual Studio shortcuts are assigned to commands. Because the same command can be used in different contexts, shortcuts of commands are also interpreted in different contexts. It might be so that in a certain context a command does not have a keyboard shortcut while in another it has. In a third context the command may even have a different shortcut.

The VSCT schema has an element called KeyBinding that is put into the KeyBindings container like in the following example:

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="..." xmlns:xs="...">
  <Commands package="...">
    <!-- Command information goes here -->
  </Commands>
 
  <KeyBindings>
    <KeyBinding guid=".." id=".." ... />
    <!-- More key bindings -->
  </KeyBindings>
 
</CommandTable>

Please note, that KeyBindings is located outside of the Command element, directly within the CommandTable element. In the BasicVSCTSample you can add shortcut keys as defined in Listing 10.

Listing 10: Shortcut key definitions in BasicVSCTSample

<KeyBindings>
  <KeyBinding guid="guidBasicVSCTSampleCmdSet" id="FirstCommand" editor="guidVSStd97"
    key1="VK_F6" mod1="Control Alt" key2="VK_F1" />
  <KeyBinding guid="guidBasicVSCTSampleCmdSet" id="SecondCommand" editor="guidVSStd97"
    key1="VK_F6" mod1="Control Alt" key2="VK_F2" />
</KeyBindings>

You can assign not only a simple hotkey for a command but also two. The key1 and mod1 attributes set the first hotkey, key2 and mod2 the second one. These hotkeys are not alternatives of each other: you have to press the first then the second to activate the command.

For example, in the code above for FirstCommand the first key is Ctrl+Alt+F7, the second F1. In values of key1 and key2 attributes you can use alphanumeric characters available on the keyboard, VK_ constants (IntelliSense will offer you as you type) or two digit hexadecimal constants with 0x prefix.

The values of mod1 and mod2 specify the modification keys. You can use the Control, Alt and Shift values or a combination of them where the value items are separated by a space.

With the guid and id attributes you can bind the specified key combination to the appropriate command. The editor attribute defines the context for a specific binding. The guidVSStd97 value defines that the command is global, so it is available in anywhere in Visual Studio.

Shortcut keys are displayed in menu items as Figure 13 shows.

Figure 13: Shortcut keys are displayed

Open the Output window and use the First Command and Second Command menu items with their keyboard shortcuts. You can see the trace messages in the Output window indicating that the commands are executed.

Advanced VSCT Samples

You have just scratched the surface of the command table features as you created a main menu item and played with groupings, icons and submenus. In this section you dive a bit deeper and look after other useful samples: you are going to build toolbars, menu controllers and examine visibility contexts.

You are going to examine a new package (AdvancedVSCTSample) that was created with VSPackage wizard. You can download it from the book’s website. The package is non-functional, it is only a container for resources, so it has an empty body.

Creating a Toolbar

In many cases a toolbar represents commands in a more useful way than a menu does. Here you are going to turn a menu above into a toolbar and then play with a few options. The steps to create the toolbar with the commands are very similar to the ones you’ve used when creating a main menu item.

Step1: Create a GuidSymbol element with children for the symbols we are going to use. Nest this element in the Symbols section.
Step 2: Create a Menu element representing the toolbar menu. Put this item into the Menus section and set up the Parent pointing to the menu item itself.
Step 3: Create a Group element representing the logical group holding the four toolbar command items. Set the Parent of this group to the Menu created in the previous step.
Step 4: Create four Button elements representing the commands and set their Parent to the Group created previously.

After these steps the .vsct file should look like in Listing 11.

Listing 11: Creating a toolbar

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="...">
  <!-- Extern section unchanged -->
  <Commands package="guidAdvancedVSCTSamplePkg">
    <Menus>
      <Menu guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbar" priority="0x0000"
        type="Toolbar">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbar" />
        <CommandFlag>DefaultDocked</CommandFlag>
        <Strings>
          <CommandName>VSCTSampleToolbar</CommandName>
          <ButtonText>VSCT Sample Toolbar</ButtonText>
        </Strings>
      </Menu>
    </Menus>
 
    <Groups>
      <Group guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbarGroup"
        priority="0x0600">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbar"/>
      </Group>
    </Groups>
 
    <Buttons>
      <Button guid="guidAdvancedVSCTSampleCmdSet" id="FirstCommand" priority="0x0100"
        type="Button">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbarGroup" />
        <Strings>
          <CommandName>FirstCommand</CommandName>
          <ButtonText>First Command</ButtonText>
        </Strings>
      </Button>
      <Button guid="guidAdvancedVSCTSampleCmdSet" id="SecondCommand"
        priority="0x0101" type="Button">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbarGroup" />
        <Strings>
          <CommandName>SecondCommand</CommandName>
          <ButtonText>Second Command</ButtonText>
        </Strings>
      </Button>
      <Button guid="guidAdvancedVSCTSampleCmdSet" id="ThirdCommand" priority="0x0102"
        type="Button">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbarGroup" />
        <Strings>
          <CommandName>ThirdCommand</CommandName>
          <ButtonText>Third Command</ButtonText>
        </Strings>
      </Button>
      <Button guid="guidAdvancedVSCTSampleCmdSet" id="FourthCommand"
        priority="0x0103" type="Button">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbarGroup" />
        <Strings>
          <CommandName>FourthCommand</CommandName>
          <ButtonText>Fourth Command</ButtonText>
        </Strings>
      </Button>
    </Buttons>
 
  </Commands>
 
  <Symbols>
    <GuidSymbol name="guidAdvancedVSCTSamplePkg" value="..." />
    <GuidSymbol name="guidAdvancedVSCTSampleCmdSet" value="...">
      <IDSymbol name="VSCTToolbar" value="0x0100" />
      <IDSymbol name="VSCTToolbarGroup" value="0x0200" />
      <IDSymbol name="FirstCommand" value="0x0300" />
      <IDSymbol name="SecondCommand" value="0x0301" />
      <IDSymbol name="ThirdCommand" value="0x0302" />
      <IDSymbol name="FourthCommand" value="0x0303" />
    </GuidSymbol>
  </Symbols>
</CommandTable>

The key in this scenario is the Menu element that uses the Toolbar value in its type attribute. Standard menus have parent groups defined by Visual Studio. However, for toolbars the concept of parent menu or menu group has no meaning just like as a nested toolbars does not. As a convention, you set the Parent of a toolbar to the same GUID and ID pair as used for the toolbar identification. The first time the toolbar is shown up you want it to be docked so you set a CommandFlag with the value of DefaultDocked. The Button elements now are parented into the Group element that points to the Menu instance.

Now, you can build the project and see how the toolbar works. Start debugging and make the toolbar visible by enabling our toolbar with View ð Toolbars ð VSCTSampleToolbar menu item. The toolbar will be shown docked right under the standard toolbar as shown in Figure 14.

Figure 14: Toolbar with button placeholders

Note: In previous Visual Studio versions this .vcst file would have resulted in a toolbar with four button placeholders without any text. To achieve the save visual properties you can see in Figure 3-14 the TextOnly command flag should have been assigned to the Button elements. Visual Studio 2010 changes this behavior. By default, when a toolbar button does not have an icon, its text is displayed even if the TextOnly command flag is not used.

Well, this toolbar resembles to a standard menu, the original concept of a toolbar seems lost. So, let’s move on using icons. To set up button icons you are going to use exactly the same code changes as used in Listing 3-6. Now the result shown in Figure 15 rather resembles to a toolbar than the first one.

Figure 15: Toolbar buttons with text

With toolbars you can use some other controls. Let’s see a few examples!

Menu Controllers on Toolbars

By now you have seen examples for two kinds of menus: standard menus and submenus. In toolbars you can use a third kind of menu called menu controller: this is a split-button drop-down menu. You can change the toolbar above so that the last three buttons go into a menu controller just like in Figure 16.

Figure 16: Menu controller with three items

Creating a menu controller is very similar to creating a submenu. To setup the items as in Error! Reference source not found. the following steps should be carried out:

Step 1: Create IDs for a new Menu element and a new Group.
Step 2: Create a Menu item with type of MenuController.
Step 3: Create a Group item for encapsulate the three Button controls that will appear in the menu controller.
Step 4: Attach the button items to the Group created in the third step.

Listing 12 summarizes the changes to establish the menu controller.

Listing 12: Using a menu controller

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="...">
  <!-- Extern section unchanged -->
  <Commands package="guidAdvancedVSCTSamplePkg">
    <Menus>
      <!-- New item representing the menu controller -->
      <Menu guid="guidAdvancedVSCTSampleCmdSet" id="VSCTMenuController"
      priority="0x0200" type="MenuController">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTToolbarGroup"/>
        <CommandFlag>IconAndText</CommandFlag>
        <Strings>
          <ButtonText>VSCT Menu Controller</ButtonText>
          <CommandName>Menu Controller</CommandName>
        </Strings>
      </Menu>
    </Menus>
 
    <Groups>
      <!-- New group for the items in the menu controller -->
      <Group guid="guidAdvancedVSCTSampleCmdSet" id="VSCTControllerGroup"
        priority="0x0600">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTMenuController"/>
      </Group>
    </Groups>
 
    <Buttons>
      <!-- We leave the first button as it is -->
      <!-- We change the 2nd 3rd and 4th button as indicated -->
      <Button guid="guidHowToPackageCmdSet" id="cmdSecondCommand"
        priority="0x0101" type="Button">
        <Parent guid="guidAdvancedVSCTSampleCmdSet" id="VSCTControllerGroup" />
        <CommandFlag>IconAndText</CommandFlag>
        <Icon guid="guidImages" id="bmpPic2" />
        <Strings>
          <CommandName>cmdidSecondCommand</CommandName>
          <ButtonText>Second Command</ButtonText>
        </Strings>
      </Button>
      <!-- Code for the 3rd and 4th button is similar -->
    </Buttons>
    <!-- Bitmaps section unchanged -->
  </Commands>
 
  <Symbols>
    <GuidSymbol name="guidHowToPackageCmdSet" value="..." >
      <!-- We use these two new IDs -->
      <IDSymbol name="VSCTMenuController" value="0x0101" />
      <IDSymbol name="VSCTControllerGroup" value="0x0201" />
    </GuidSymbol>
    <!-- Other Guids of the package -->
  </Symbols>
</CommandTable>

The Menu item for a menu controller can be defined so that the type attribute is set to MenuController. The Parent of the menu is the command group representing the four command buttons as it was used in the previous example.

You attach the newly created group to the Menu item above and then connect the last three Button elements to this Group. You also change the CommandFlag elements for the new menu controller item and for the tree involved button to IconAndText in order to make it dropdown-menu-like.

IconAndText is the default value for the buttons attached to a menu controller, so if you leave them for buttons, the toolbar appearance will not change. However, for the menu controller itself the default mode displays only the icons. If you had omitted the IconAndText flag from the controller definition we could see the toolbar like in Figure 17.

Figure 17: Menu controller with icon only

Combo Boxes

Combo boxes provide you an enhanced form of input by allowing a combination of hand-typed text selection with picking items from a list. Visual Studio also allows combo boxes on the user interface. The command table file (.vsct) has Combo elements to represent UI of commands with combo boxes instead of standard menu items or buttons. There are four stereotypes of combos; each of them is identified by a type name used in the .vsct file.

DropDownCombo: This type does not let the user type into the combo box; they can only pick an item from a list. After selecting an item the string value of the selected element is returned.
IndexCombo: This type is the same as a DropDownCombo in that it allows only picking up items from a list. However, an IndexCombo returns the zero-based index of the selected value on the list and not the value itself.
MRUCombo: This combo type allows the user to type into the edit box. The history of strings entered is automatically persisted by the IDE on a per-user or per-machine basis for the last 16 items.
DynamicCombo: This combo allows the user to type into the edit box or pick from the list. The list of choices is managed dynamically by a command event handler method.

Handling combo boxes is more complicated than working with simple menu items. A part of the complexity comes from the fact that combo boxes use two commands behind. The first command is executed as you select an item from the dropdown list. The second command is used to fill up the list of items.

Working with Visibility Contexts

In the beginning of this chapter you have already learnt about the concept of visibility contexts, and in Table 4 you can see the most frequently used ones. In this section you are going to create a small sample package demonstrating concepts treated there.

You can examine a package named VisibilityContextSample and similarly to the previous samples this package is only a container for the menu and does not provide any real function. The package adds a menu that looks like as shown in Figure 18.

Figure 18: Menus defined by the VisibilityContextSample package

The command table producing this menu can be found in Listing 13 and uses exactly the same approach that can be found in Listing 4.

Listing 13: VisibilityContextSample initial command table

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable" xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <Extern href="stdidcmd.h"/>
  <Extern href="vsshlids.h"/>
  <Extern href="msobtnid.h"/>
  <Commands package="guidVisibilityContextSamplePkg">
    <Menus>
      <Menu guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenu" priority="0x100"
        type="Menu">
        <Parent guid="guidSHLMainMenu" id="IDG_VS_MM_BUILDDEBUGRUN" />
        <Strings>
          <ButtonText>Visibility Sample</ButtonText>
          <CommandName>Visibility Sample</CommandName>
        </Strings>
      </Menu>
    </Menus>
 
    <Groups>
      <Group guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenuGroup"
        priority="0x0600">
        <Parent guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenu"/>
      </Group>
    </Groups>
 
    <Buttons>
      <Button guid="guidVisibilityContextSampleCmdSet" id="NoSolution" priority="0x0100"
        type="Button">
        <Parent guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <CommandName>cmdNoSolution</CommandName>
          <ButtonText>No Open Solution</ButtonText>
        </Strings>
      </Button>
 
      <Button guid="guidVisibilityContextSampleCmdSet" id="EmptySolution"
        priority="0x0101" type="Button">
        <Parent guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <CommandName>cmdEmptySolution</CommandName>
          <ButtonText>Empty Solution</ButtonText>
        </Strings>
      </Button>
 
      <Button guid="guidVisibilityContextSampleCmdSet" id="SingleProject"
        priority="0x0102" type="Button">
        <Parent guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <CommandName>cmdSingleProject</CommandName>
          <ButtonText>Single Project</ButtonText>
        </Strings>
      </Button>
 
      <Button guid="guidVisibilityContextSampleCmdSet" id="MultipleProject"
        priority="0x0103" type="Button">
        <Parent guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <CommandName>cmdMultipleProject</CommandName>
          <ButtonText>Multiple Project</ButtonText>
        </Strings>
      </Button>
 
      <Button guid="guidVisibilityContextSampleCmdSet" id="NotBound" priority="0x0104"
        type="Button">
        <Parent guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <CommandName>cmdNotBound</CommandName>
          <ButtonText>Not bound to context</ButtonText>
        </Strings>
      </Button>
 
      <Button guid="guidVisibilityContextSampleCmdSet" id="SingleOrMultiple"
        priority="0x0105" type="Button">
        <Parent guid="guidVisibilityContextSampleCmdSet" id="TopLevelMenuGroup" />
        <Strings>
          <CommandName>cmdSingleOrMultiple</CommandName>
          <ButtonText>Single or Multiple</ButtonText>
        </Strings>
      </Button>
    </Buttons>
 
  </Commands>
 
  <Symbols>
    <GuidSymbol name="guidVisibilityContextSamplePkg" value="..." />
    <GuidSymbol name="guidVisibilityContextSampleCmdSet" value="...">
      <IDSymbol name="TopLevelMenu" value="0x1000" />
      <IDSymbol name="TopLevelMenuGroup" value="0x1020" />
      <IDSymbol name="NoSolution" value="0x0100" />
      <IDSymbol name="EmptySolution" value="0x0101" />
      <IDSymbol name="SingleProject" value="0x0102" />
      <IDSymbol name="MultipleProject" value="0x0103" />
      <IDSymbol name="NotBound" value="0x0104" />
      <IDSymbol name="SingleOrMultiple" value="0x0105" />
    </GuidSymbol>
  </Symbols>
 
</CommandTable>

If you apply this .vsct file for a package you will get the menu in the Figure 18, but nothing extra. Bind the commands to specific visibility contexts! First, add DynamicVisibility command flag to all buttons. Without this flag the sample would not work. Second, add the VisibilityConstraints section as in Listing 14 to the command table.

Listing 14: VisibilityContextSample initial command table

<VisibilityConstraints>
  <VisibilityItem guid="guidVisibilityContextSampleCmdSet" id="NoSolution"
    context="UICONTEXT_NoSolution"/>
  <VisibilityItem guid="guidVisibilityContextSampleCmdSet" id="EmptySolution"
    context="UICONTEXT_EmptySolution"/>
  <VisibilityItem guid="guidVisibilityContextSampleCmdSet" id="SingleProject"
    context="UICONTEXT_SolutionHasSingleProject"/>
  <VisibilityItem guid="guidVisibilityContextSampleCmdSet" id="MultipleProject"
    context="UICONTEXT_SolutionHasMultipleProjects"/>
  <VisibilityItem guid="guidVisibilityContextSampleCmdSet" id="SingleOrMultiple"
    context="UICONTEXT_SolutionHasSingleProject"/>
  <VisibilityItem guid="guidVisibilityContextSampleCmdSet" id="SingleOrMultiple"
    context="UICONTEXT_SolutionHasMultipleProjects"/>
</VisibilityConstraints>

Each VisibilityItem node binds the specified command to a visibility context defined by the context attribute. Symbols starting with the UICONTEXT_ prefix define the contexts as summarized in Table 3-4. The NotBound button is not assigned with any contexts, so it is always visible (it is displayed in every context). The SingleOrMultiple command is bound to two contexts (represented by the last two VisibilityItem nodes), so it is displayed when there is a solution with one or more projects open.

We can check in a few steps how these constraints work. First, when you open Visual Studio you can see the initial state of the menu as shown in Figure 19.

Figure 19: Initial menu state after starting Visual Studio

Now, carry out the following steps and see the results in the corresponding figures:

Create an empty solution (Figure 20)
Add a C# class library (or any other kind of project) to the solution (Figure 21)
Add another project to the existing solution (Figure 22)

Figure 20: Empty solution created

Figure 21: A new project is added to the solution

Figure 22: Another project is added to the solution

As you see, visibility contexts work as expected.

Command Routing and Nested Contexts

The Visual Studio IDE, its registered packages, and objects owned by packages (editors, tool windows, and so on) define a huge set of executable commands. A command can be executed by a number of entities depending on the current context, for instance by the active editor window, the currently selected project, active tool window, and so on.

There are many objects at the same time in the IDE which are command targets and so are able to receive and execute commands. Visual Studio has a well-defined routing architecture that lays down the rules how commands are executed in a certain context — in which order command targets are offered to process commands. This algorithm starts form the innermost context and goes to the outermost context while it reaches the global context that is the core Visual Studio IDE.

From this point of view contexts are nested into each other. Here is a very simple example how contexts are nested. The real life is a bit more complex, but this helps you imagine nesting.

Assume you create a package with a tool window and register it with Visual Studio IDE. Because both the package itself and the tool window owned by the package are command targets, you have the following contexts from the top to the bottom:

The top level (global context) is Visual Studio IDE.
Your package is sited in the IDE. Before siting it has its own logical context. After you site the package its context logically will be a context nested into the IDE.
The tool window of the package has its own contexts. When an instance is created its context becomes a nested context within the package.

Visual Studio IDE, packages and package-owned objects form a tree of nested command contexts. From this perspective the routing algorithm starts from a leaf of that tree and bubbles up while it reaches the root of this tree that is called the global context.

The Routing Algorithm

The algorithm that routes commands has many fine details which add small twists. Here you will not learn all those subtle details; instead you’ll be given a high level overview.

In the route the current level is called the active command context. This context has the chance to handle the command or to say “I do not know what to do with this command” and the bubble goes on its way.

The routing algorithm defines the following levels from the leaves to the root:

Present Add-ins and special packages. Commands first are offered to the registered and loaded Add-ins or specially registered packages.
Context (shortcut) menus. If the user initiates a command from a context menu, the command target object belonging to this menu has the first chance to handle the command. If it does not, then the normal route (starting from Present Add-Ins) is applied.
Focus window. The window having the focus is the next entity that can undertake command handling. This can be either a tool window or a document window, for instance, a window related to an editor. The management of the command is different depending on what kind of window is focused.
- Document window. There are windows in Visual Studio like editors and designers that have physical or virtual documents behind them. Document windows are composed logically from two separate parts: a document view that is responsible to display the UI representing the document and a document data object that is responsible to handle the information set behind the document. Both the document view and the document data can be command targets. The command first goes to the document view and goes on to the document data if the view does not support the command.
- Tool window. The tool window can handle the command by its own logic. There are tool windows that route the commands within themselves to nested command targets. The Solution Explorer window is an example of them. Within Solution Explorer a command is routed according to the hierarchy composed from the elements of the Solution Explorer where each node type (file, folder, project, solution, etc.) has the ability to handle the command. This internal route also goes from the lower hierarchy levels to the upper ones.
Current project. The current project gets the opportunity to process the command. If it does not handle, the command goes up in the hierarchy of projects till the level of solution. All nodes on this route can manage the command just like other command target objects. (Visual Studio allows creating nested projects. When subprojects are used, the upper level of a project is not necessary the solution.)
Environment. Each package should be able to handle commands owned (defined) by it. Theoretically it is not mandatory, but why to define a custom command which is not handled by the only entity that knows it?
Global level. If a command is not handled in the previous levels, the environment attempts to route it to the appropriate package (the package defining the command). If necessary, Visual Studio loads the appropriate package into the memory.

Any command target objects along the route can decide how to process a command. They must answer status queries and execute requested commands.

Summary

Visual Studio clearly separates the concept of menu items and commands.

A command itself it a logical entity that can be forwarded to command targets which know how to handle the semantics of a specific command. There is a command routing model in the IDE that forwards a command to a command target. The target either can do something with the request related to a command (for example, set the command state disabled, execute the command, etc.) or can pass back the command as not supported (the target does not know what to do with that). The target even can pass the command to other command targets.

Each command has a state in the current Visual Studio context. This state is built up from two orthogonal factors: availability (the command is enabled or disabled) and visuals (the command is visible or hidden, the label it has, and so on).

The Visual Studio Command Table describes the commands and related UI elements that should be merged with Visual Studio menus. The command table is compiled to a binary resource which is embedded into the package infrastructure resources during the build process. When deploying the package the command table is merged into the menus and toolbars of the IDE.

Visual Studio 2010 uses an XML format with .vsct extension to describe the command table. Older versions used a simple textual format called .ctc that has been deprecated.

In this chapter you have seen the structure of the .vsct file and solved simple tasks like building a new main menu item or a toolbar, putting commands visually into command groups or submenus, working with menu controllers, etc. You have also examined a sample illustrating how visibility constraints work.

VS 2010 Package Development – Chapter 1: Visual Studio Packages

2010-03-02T12:13:00Z

I have spent a lot of time with preparing a book about Visual Studio Extensibility, focusing on Visual Studio Package Development. I have made proposals for several book publishers, but I did not manage to get a contract, most of them found such a book is not profitable. I decided to share the four chapters of the book that I’ve already written. They are the followings:

Chapter 1: Visual Studio Packages
Chapter 2: Commands, Menus and Toolbars
Chapter 3: Window Management and Tool Windows
Chapter 4: Services

I hope, you will find these chapters useful.

The majority of Visual Studio’s functions you use in your everyday work (such as programming languages, editors, designers and debuggers) are provided by Visual Studio Integration Packages, or shortly by packages. Some call them VSIP packages but the VSIP acronym is overloaded: while the first two letters means “Visual Studio” the last two may mean either “Integration Package” or “Industry Partner” and unfortunately both terms are frequently used. To avoid ambiguity hereinafter you’ll meet the term package or VSPackage.

Developing packages means you can extend Visual Studio on the same way as its developer team at Microsoft. Adding new functions through packages is actually programming a new part of Visual Studio just like if you were the member of the team. You can use the full power and integrate any functionality you miss from the IDE!

In this chapter you will create a very simple package called FirstLook to get a feeling that first steps are easy. Then you’ll learn the basic concepts behind packages and dive into the FirstLook project’s structure and source code to have a closer look at the implementation of those concepts. At the end of this chapter you’ll be familiar with the following:

Building a package with the VSPackage Wizard
The idea of a package
The on-demand package loading mechanism and the idea of package siting
Registration of packages and information stored in the registry
The Visual Studio Experimental Hive and using it for debugging packages
The package build process
Deploying VSPackages

This chapter will not teach you how to build a specific functionality into a package and does not cover the API used to develop packages. The focus is on understanding the concepts, architectural considerations behind VSPackages to let you take a look behind the scenes and get acquainted with package mechanisms. These concepts will be very useful when you are about creating your own packages.

Building a Simple Package

There are a few important concepts to understand if you want to develop a package. In order treat them in the right context you build a very simple functional package to touch the surface of those concepts and then jump into the details.

A Visual Studio package is a class library containing the types responsible for the package infrastructure and functionality. In order Visual Studio recognize the compiled class library as package, encapsulated types should have specific metadata information and some additional steps are required after compilation. So, even if you could start building a package from an empty class library, it is much easier to use the VSPackage Wizard installed with Visual Studio SDK.

Start a new project with the File|New|Project command. The IDE displays the New File dialog to select the desired project type. You can find the Visual Studio Integration Package project type under the Other Project Types category in the Extensibility folder as Figure 1 illustrates.

Figure 1: The New Project dialog with the Extensibility project types

Should you not find this project type or many other project types in the Extensibility folder means that Visual Studio SDK is not — or not properly — installed on your machine. Install it according to the setup notes in order to go on with building the package.

Give the FirstLook name to the package in order to be able to follow code details later in this chapter. Clicking the OK button starts the Visual Studio Integration Package Wizard (henceforward VSPackage Wizard is used, it is shorter) which welcomes you with the dialog in Figure 2.

Figure 2: The Welcome page of the VSPackage Wizard

Click the Next button to go on specifying the package parameters and you get to the Select a Programming Language page of the wizard as Figure 3 shows.

Figure 3: VSPackage Wizard lets you select the programming language

As it was mentioned earlier you create the code in C#. Packages are strongly named assemblies, so you need to sign the class library assembly with a key. For this project the wizard creates the signing key. Click Next and you get to the Basic VSPackage Information page as Figure 4 shows.

Figure 4: The wizard asks for the basic package information

The information you provide here will be used in the source code generated for the package and will be displayed in the Visual Studio About dialog. The Company name will be used in the namespace of generated types as well as VSPackage name which also names the class representing the package in code. VSPackage version is additional information to give a way for distinguishing separate package releases.

Text typed in the Detailed information field will be displayed in the About dialog and can supply the user with more information about what the package does.

When you click the Next button the wizard moves you to the VSPackage Options page — as can be seen in Figure 5 — to set a few more code generation options.

Figure 5: You can select a few code generation options

In this sample you are going to create only a menu command that pops up a message on the screen, so set the Menu Command option. Should you select the other two options the VSPackage Wizard would create some more code for a simple tool window or a rich text editor. Please, let those options remain unchecked. With the Next button the wizard goes to the page where we can specify a few details about the menu command to create. This page is shown in Figure 6.

Figure 6: Command options are specified here

The command will be added to the Tools menu of Visual Studio, in Command name you can specify the text to be displayed for the menu item. According to the internal command handling architecture each command has an identifier. The Command ID field supplies a name for this identifier and VSPackage Wizard will generate an ID value behind this name. With clicking Next the wizard moves to the Test Project Options page as shown in Figure 7.

Figure 7: VSPackage Wizard asks for test project options

The wizard can create unit test for the package which check if its functional units work properly. The wizard also can create an integration test project for you, in which packages are tested within the context of a Visual Studio instance.

For the sake of simplicity here you do not create any tests, so clear the options — by default both are checked. Now you have set all parameters the wizard uses to generate the package project, click on the Finish button.

In a few seconds the wizard generates the package project ready to build and run. Taste the pudding you have just cooked! With the Build ð Rebuild Solution function you can compile the package and carry out all other steps required to run the package with Visual Studio. So rebuild the project and start with Ctrl + F5 (Debug|Start Without Debugging).

You might be surprised as a new instance of Visual Studio is started with “Experimental Instance” in its window caption.

Note: If this is the first time you have started the Experimental Instance, the Choose Default Environment Settings dialog appears just like when you first time launch Visual Studio after installation.

This is an instance of Visual Studio that hosts the FirstLook package — later you’re going to learn the concept behind. The menu command implemented by this freshly generated package can be seen in the Tools menu as Figure 8 shows it.

Figure 8: The menu command item appears in the Tools menu

When you click the Simple Message command, it pops up a message box telling you it was displayed from the FirstLook package.

The package also registered some branding information that can be seen in the Help|About dialog as Figure 9 shows.

Figure 9: Branding information of the FirstLook package

Nothing call tell more about your VSPackage than its source code. But before deep-diving into it, let’s treat important concepts about packages.

Concepts behind Visual Studio Packages

A VSPackage is the principal architectural unit of Visual Studio. As you already know, Visual Studio IDE itself is the Shell hosting a set of VSPackages working together with each other and with the Shell. The basic responsibility of a package is to provide a common container for extensibility objects. So, a VSPackage is a software module that is a unit not only from architectural point of view but also from deployment, security and licensing aspects.

Developers — including the developers of Visual Studio — create VSPackages to provide some extension to the VS IDE and group them into modules according to their functionality. These extensions can be:

Services. These are software objects that offer functionality for other objects in the same package or even for other packages. For example, the C# Language Service (as its name also tells) is a service.
User interface elements. Menus, toolbars, and windows can be used by developers to initiate some actions in the user interface, interact with, display messages, information and figures, and so on.
Editors. During development you write and modify program text to create applications. This task is the responsibility of an editor. Visual Studio 2010 has its own core text editor and you can extend it or even create your own editors.
Designers. Application creation is not just simply a text-typing activity. There are many visual tools known as designers that allow an alternative representation and design of modules, components, parts or even full applications. Well-known examples are the Windows Forms designer, The WPF Forms designer, the ASP.NET page designer or the Data Table designer.
Projects. When developing applications you generally work with a large number of files. A project is an organization of source files and resources. A project not just simply stores these files but also defines operations with them, allows building, debugging and deploying the products created from source files.

It is natural in .NET that you can divide your functional units into separate assemblies where consumer assemblies will reference other service assemblies. The same principle works for VSPackages: an assembly containing a package can reference other assemblies that may contain not just helper types but even extensibility object types.

An assembly — as the smallest physical deployment unit in .NET — may contain more than one VSPackage. Although generally only one package is encapsulated in an assembly, you may have many reasons to group more packages in one assembly — including deployment considerations.

The Package Load Key

The previous versions of Visual Studio checked the package before loading them into the process space of the Shell. Any VSPackage should have been “sealed” with a so-called Package Load Key (PLK) and this key was verified during package load time. PLK was not a digital signature or a full hash, because it was calculated from a few information fields in the package. PLK could have been requested from Microsoft through a webpage: the developer specified a few well-defined attributes of the package and some logic calculated the PLK value. This value was embedded as a resource into the assembly representing the package.

Every time the package was loaded, the Shell checked the PLK against the package attributes it had been created from. Should have been this check fail, the Shell would have refused loading the package. This PLK mechanism did not mean that a developer had to request a new PLK for each package modification. While no basic information the PLK had been generated from was changed, the package continued to load.

Although this concept had been seemed useful, in the real life in had no real advantage. To be honest, in most of the cases it was the root cause of deployment issues, in many scenarios it raised more problems than it solved.

In the new Visual Studio 2010 the Shell does not use the Package Load Key to check packages before loading them into the memory.

On-demand Loading of Packages

You can imagine that complex packages like the C#, VB, F# or C++ languages with all of their “accessories” could consume many system resources by terms of memory and CPU. If you do not use them they do not press the CPU, but they might use the memory if they sit within the Visual Studio process space. If you create a project using F# you actually do not need services belonging to other languages, so why to load them into the memory at all?

The architects of Visual Studio implemented the package load mechanism so that packages are loaded into the memory at the first time when an event requiring the presence of the package is raised. These events can be one of the followings:

Command activation. The user (or some running code) activates a menu or toolbar command (or even a command that cannot be accessed from UI) served by a package which has not been loaded yet. It does not matter if the user has clicked on a menu item or the running code has activated it with a “virtual click” the result is the same.
Object or service request. The Shell is about to use an object or a service in a package not loaded yet. For example a tool window should be displayed or a service function is about to be executed.
Context change. The Shell can enter into certain user interface contexts. For example, when you start debugging a project, the Shell enters into the Debugging context. When a solution with a single project is loaded, the Shell enters into the SolutionHasSingleProject context. You can declare that a package should be loaded as the Shell enters in a certain context. Visual Studio has a few predefined contexts, but you can also define your own ones.

So, if you do not need a package during the whole IDE session, it does not consume the memory at all. Should you click on a menu item activating a command sitting in a package which has not been loaded yet the IDE will immediately load and initialize it. Should you ask for a tool window in a package not in the memory yet, the IDE will start loading it.

Binding package loading with a context change is generally required where your package want to subscribe for events raised in Visual Studio. You cannot bind the event either to command activation or object or service requests, because in order your package could work you have to subscribe to events. The code to create subscriptions is generally put into the initialization code. But you cannot run any code belonging to a package while it is not loaded into the memory! In this case you declare that the best context (the latest possible) to load the package. If your package logic requires, you can specify the NoSolutionExists context. Visual Studio enters into this context immediately when the Shell is loaded and ready to function, so packages bound to this context load at Visual Studio startup time.

Note: Be frugal with system resources if you have to load a package at Visual Studio startup time. Allocate only resources that are indispensable to carry out the required initialization at startup time.

Package Siting

When you develop a package it is an independent piece of code. When it is loaded into Visual Studio it becomes an organic part of the IDE:

Your package can access services and objects provided by the Shell and other packages.
The Shell and other packages can access the objects and services you proffer them.

The process of making a package physically integrated into the Shell is called siting. While the package is not sited, its functions cannot be used from outside. From the same reason the package can be only partially initialized, because it cannot touch any objects or services through the Shell. As soon as the package gets sited, it is ready to finish its initialization and be fully functional. Siting happens when Visual Studio loads the package.

The object type representing your package must implement an interface called IVsPackage (you are going to learn details later in this chapter) and must have a default constructor.

Loading a package contains the following steps:

The Shell creates an instance of the object type representing your package by invoking its default constructor.
The Shell calls the SetSite method of the object instance — IVsPackage defines this method — and passes a so-called service provider instance which can be used by the package to query objects in order to access services implemented by the Shell or other packages.
The Shell allows your package to finish its initialization. In the first step during the construction call the service object did not have any contact with the Shell. After siting all initialization steps invoking Shell services can be carried out.

Although siting physically integrates your package functionally with Visual Studio, functional integration may require some additional — and sometimes complex — steps depending on what your package is intended to do.

Package Registration

Visual Studio must keep track of packages in order to load and use them. Of course, the most flexible would be some kind of discovery where the Shell can look around only in the file system to guess out which entities represent packages. The .NET framework supports and intensively uses metadata (attributes) that can represent the information you can use for this purpose. You can even load an assembly so that only the metadata part is read from the file system and put into the memory. Although you can imagine this mechanism could work, it is not used by the Shell in this way.

The reason is that the roots of Visual Studio go back to the COM era. Packages are COM objects and can be created not only in managed code but also in native code using the Win32 API with any language including C++, Delphi and others. So, not surprisingly Visual Studio uses the registry to keep information about packages.

Although the registry is used to store configuration information about Visual Studio settings, developers and package users are not bothered with registration issues. The new deployment mechanism (through VSIX files) implemented in Visual Studio 2010 takes away this task. When Visual Studio is started, its discovery mechanism collects the information to be entered into the registry and does all the registration process on the fly. Developers perceive they do installation only by copying files and this resembles to the great mechanism we are using with the .NET Framework.

Package Information in the Registry

Packages are loaded into the memory on-demand. To effectively use this approach, Visual Studio stores the registration information about packages in a way so that this information could be accessed from the direction of objects to be used. For example, one kind of object that could trigger package loading is a tool window. A tool window has its own identity. When it is about to be created in order to be displayed, Visual Studio turns into the registry and addresses the corresponding key with the tool window identity. Under that key there is information stored about the identity of the package owning and implementing the tool window. Using this identity Visual Studio finds the registry key containing the package information and loads the package into the memory accordingly. The identity of packages and objects is represented by a GUID.

Figure 10 shows a few registry keys that store package-related information for Visual Studio.

Figure 10: Package and object information in the registry

Assume that Visual Studio is about to create a service instance. It uses the Services registry key and according to the service identity it finds the package. Figure 11 illustrates the service key of the Class Designer Service. At the left side you can see the subkey named by the GUID identifying the service. At the right side you see the corresponding package ID in the default value under the service key.

Figure 11: Service information in the registry

Visual Studio uses the same approach to find owner packages for any other objects.

There is one important thing to treat about package information in the registry. Packages can add their own user interface items to the Visual Studio IDE in form of menus and toolbars. If this UI information were created during the package initialization time, Visual Studio would need to load the package at startup time in order to present the package-dependent UI to the users. This approach would demolish the whole concept of on-demand loading.

Instead, the package uses a declarative way to define the user interface that should be displayed in the IDE at startup time. This information is encapsulated into the package assembly as an embedded resource. During the registration process Visual Studio extracts this resource information and merges it with its standard menus. Each user interface element — the commands they represent — is associated with the identity (GUID) of the owner package, so the Shell knows which package to load when a command is activated.

Visual Studio Experimental Instance

When you started the FirstLook package a new instance of Visual Studio was launched with the “Experimental Instance” text in its caption. What is that Visual Studio instance and how did it get to the computer?

Visual Studio Experimental Instance is a test bed to run and debug Visual Studio packages during the development and test phase. It is not a new installation of Visual Studio. It is the same devenv.exe file you use normally. But why you need it?

As it’s been mentioned earlier the package is registered — information is written into the system registry — in order it could integrate with Visual Studio. Every time you build and run a package some information goes into the registry. When you modify the package it might affect also the information in the registry. You can imagine what an unexpected confusion it can lead that you always modify the registry under the Visual Studio instance you actually use to develop and debug a package? What if your package does not work or even worse it prevents Visual Studio start correctly or even causes a crash? How would you fix the pollution of registry?

That is the point when Visual Studio Experimental Instance comes into the picture. The Experimental Instance is simply another instance of Visual Studio that picks up its settings from a different place — including configuration files and registry keys.

The devenv.exe keeps its configuration settings in the system registry in the CURRENT_USER hive under the Software\Microsoft\VisualStudio\10.0_Config key. When Visual Studio runs it reads out the configuration information from these keys by default. With the /rootsuffix command line parameters the root key used by devenv.exe can be changed.

The VSPackage Wizard sets up the package project so that the devenv.exe uses the /rootsuffix Exp command line parameter when running or debugging the package. By doing it so devenv.exe will use the Software\Microsoft\VisualStudio\10.0Exp_Config registry key under the CURRENT_USER registry hive. So running the package with the Start Debugging (F5) or Start Without Debugging (Ctrl+F5) functions will launch the Visual Studio Experimental Instance using this registry key.

The build process of a package copies the package binaries and the so-called VSIX manifest information to a well-known location under the current user’s application data folder. When the Experimental Hive starts, it discovers the package in the folder and uses the information found there to enter the package information into the registry key consumed by the Experimental Instance.

Using the Experimental Instance prevents you polluting the registry of the Visual Studio instance used for the normal development process. However, making mistakes, recompilations and faulty package registrations does not prevent putting junk or leaving orphaned information in the Experimental Instance registry. Making an appropriate cleanup could be very complex and dangerous if you would do it by delving in the registry.

Cleaning up packages from the Experimental Instance’s registry is quite easy! The Visual Studio SDK installs the CreateExpInstance.exe utility and adds it to the Visual Studio 2010 SDK menu items under the Tools folder with the name “Reset the Microsoft Visual Studio 2010 Experimental Instance”. Running this utility will reset the registry key belonging to the Experimental Hive to the state after the installation of VS SDK.

Note: If you develop Visual Studio packages you can get into situations several times where your package which worked before seems suddenly stop working. In majority of these cases the cause is the pollution of Visual Studio registry. There can be many orphaned objects in the registry as a result of continuous modification and rebuild of packages, and that can cause problems. If you run in such a situation, reset the Experimental Instance and then build your package with the Rebuild All function of Visual Studio. This procedure often helps.

Diving into the Package Source Code

You have already created a FirstLook project with the VSPackage wizard and by now you have a good overview about the basic concepts behind packages. Now we go into details and look how those concepts and ideas are reflected in the source code.

When the VSPackage Wizard generated the code according to the parameters we specified on the wizard pages, it made a lot of work at the background. The wizard carried out the following activities:

Generation of a class library project in C#.
Adding references to this project for the interoperability assemblies required to access Visual Studio functionality.
Creating resources used by the package and other resources used by the registration process.
Adding new MSBuild targets to the project to support the build and registration process of the package.
Generation of types responsible for implementing the package functionality.
Setting up the debug properties of the project to start Visual Studio Experimental Instance.

Table 1 summarizes the source files in the FirstLook project.

Table 1: FirstLook source files generated by the VSPackage wizard

Source File	Description
source.extension.vsixmanifest	This is the so-called VSIX manifest file which plays vital role in the discovery and registration mechanism of Visual Studio extensions.
FirstLook.vsct	The so-called command table file storing the definition of the menus and commands to be merged into the Visual Studio IDE during the registration process.
FirstLookPackage.cs	Class implementing the simple functionality of the package.
GlobalSupressions.cs	Attributes used to suppress messages coming from the static code analysis.
Guids.cs	GUID values used to identify the package and command objects within the package.
Key.snk	Signing key used to generate the strong name for the package assembly.
PkgCmdID.cs	Constants for identifying command values.
Resources.resx	Resource file to store your functional package resources — resources you use according to the functions you implement in the package.
VSPackage.resx	Resource file to store package infrastructure resources — those resources which are used by Visual Studio to integrate your package into the IDE.

The wizard added several assemblies to the class library project. Table 2 summarizes their roles. Their names start with the Microsoft.VisualStudio, this prefix is omitted in the table for the sake of clarity.

Table 2: Interoperability assembly references in the project

Source File	Description
~.Shell.Interop	This assembly defines several hundreds of core interoperability types (interfaces, structures, enumerations, classes, etc.).
~.Shell.Interop.8.0, ~.Shell.Interop.9.0 and ~.Shell.Interop.10.0	There are COM types new in VS 2005, VS 2008 and VS 2010 IDEs. The interoperability wrappers of them are defined in these assemblies where the 8.0 suffix is for VS 2005, the 9.0 suffix for VS 2008 while the 10.0 suffix for VS 2010.
~.Shell.Interop.Immutable.10.0	A few abstract and enumeration types used for package registration attributes.
~.OLE.Interop	There are a few hundred of standard OLE types and interfaces. This assembly provides wrapper types for them.
~.Shell.9.0	The core types of the Managed Package Framework. There is a separate version for VS 2008 with the 9.0 suffix. If you work with VS 2008, you should use this assembly.
~.TextManager.Interop	Interoperability assembly with wrapper types to access text editor and text management functionality. Although this assembly is referenced by the project, it is not used in the package you’ve created.

All assemblies having Interop in their names contain only proxy type definitions to access the core Visual Studio COM service interface and object types.

Package Type Definition

Now, let’s see the source code of the package! The wizard added many useful comments to the generated source files. In the code extracts listed here those commands are cut out to make the listings shorter and improve the readability of the code. The indentation has also been changed a bit for the same purpose.

Listing 1 shows the source code of the most important file in our project named FirstLookPackage.cs. This file implements the type representing our package:

Listing 1: FirstLookPackage.cs

using System;
using System.ComponentModel.Design;
using System.Diagnostics;
using System.Globalization;
using System.Runtime.InteropServices;
using Microsoft.VisualStudio.Shell;
using Microsoft.VisualStudio.Shell.Interop;
 
namespace DeepDiver.FirstLook
{
  [PackageRegistration(UseManagedResourcesOnly = true)]
  [InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
  [ProvideMenuResource("Menus.ctmenu", 1)]
  [Guid(GuidList.guidFirstLookPkgString)]
  public sealed class FirstLookPackage : Package
  {
    public FirstLookPackage()
    {
      Trace.WriteLine(string.Format(CultureInfo.CurrentCulture, "Entering constructor for: {0}", this.ToString()));
    }
 
    protected override void Initialize()
    {
      Trace.WriteLine(string.Format(CultureInfo.CurrentCulture, "Entering Initialize() of: {0}", this.ToString()));
      base.Initialize();
 
      // Add our command handlers for menu (commands must exist in the .vsct file)
      OleMenuCommandService mcs = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;
      if (null != mcs)
      {
        // Create the command for the menu item.
        CommandID menuCommandID = new CommandID(GuidList.guidFirstLookCmdSet, (int)PkgCmdIDList.cmdidShowMyMessage);
        MenuCommand menuItem = new MenuCommand(MenuItemCallback, menuCommandID);
        mcs.AddCommand(menuItem);
      }
    }
 
    private void MenuItemCallback(object sender, EventArgs e)
    {
      // Show a Message Box to prove we were here
      IVsUIShell uiShell = (IVsUIShell)GetService(typeof(SVsUIShell));
      Guid clsid = Guid.Empty;
      int result;
      Microsoft.VisualStudio.ErrorHandler.ThrowOnFailure(uiShell.ShowMessageBox(
                 0,
                 ref clsid,
                 "FirstLook",
                 string.Format(CultureInfo.CurrentCulture, "Inside {0}.MenuItemCallback()", this.ToString()),
                 string.Empty,
                 0,
                 OLEMSGBUTTON.OLEMSGBUTTON_OK,
                 OLEMSGDEFBUTTON.OLEMSGDEFBUTTON_FIRST,
                 OLEMSGICON.OLEMSGICON_INFO,
                 0,        // false
                 out result));
    }
  }
}

The FirstLookPackage class becomes a working package by inheriting the behavior defined in the Package class of the Microsoft.VisualStudio.Shell namespace and by using the attributes decorating the class definition.

The Package base class implements the IVsPackage interface that is required by Visual Studio in order to take an object into account as a package. This interface provides a few methods managing the lifecycle of a package and also offers methods to access package related objects like tool windows, options pages, and automation objects. One of the most important of them is the SetSite method having the following signature:

int SetSite(IServiceProvider psp);

Visual Studio calls this method immediately after the package has been instantiated by its default constructor. The psp parameter is an instance of System.IServiceProvider and this object is the key in keeping contact between the package and the IDE: any time the package requests a service object from its context—from the IDE—the psp instance is used at the back, however, the implementation of Package hides it from our eyes.

The overridden Initialize method is called after the package has been successfully sited. This method has to do all the initialization steps that require access to services provided by the Shell or other packages. Should you move this code to the package constructor you would get a NullReferenceException because at that point all attempts to access the Shell would fail as the package is not sited yet and actually has no contact with any shell objects.

The package constructor should do only inexpensive initialization that you would put normally to a constructor. Any other kind of initialization activities should be put to the overridden Initialize method. If you have some other expensive initialization activity that can be postponed, you should do them right when there’s no more time to delay them.

In this case the Initialize method binds the single menu command provided by the FirstLookPackage with its event handler method called MenuItemCallback:

protected override void Initialize()
{
  Trace.WriteLine(string.Format(CultureInfo.CurrentCulture, "Entering Initialize() of: {0}", this.ToString()));
  base.Initialize();
 
  // Add our command handlers for menu (commands must exist in the .vsct file)
  OleMenuCommandService mcs = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;
  if (null != mcs)
  {
    // Create the command for the menu item.
    CommandID menuCommandID = new CommandID(GuidList.guidFirstLookCmdSet, (int)PkgCmdIDList.cmdidShowMyMessage);
    MenuCommand menuItem = new MenuCommand(MenuItemCallback, menuCommandID);
    mcs.AddCommand(menuItem);
  }
}

First it calls the Initialize method of the base class — Package in this case. Omitting the call to the base implementation would prevent the package running correctly. Look at the call of GetService in Line 7! If you could select a method that is especially very important when creating Visual Studio Extensions, probably the GetService method is that one! This method is implemented by the Package class — many other Managed Package Framework objects also implement this method — in order to request service objects from the environment. GetService has one type parameter — it’s called service address — that retrieves a service object implementing the service interface specified by the address type.

So, Line 7 obtains an OleMenuCommandService instance that you can use to bind event handlers to so-called command objects. In Line 11 and 12 a CommandID instance is created to address the command to be put to the Tools menu. In Line 12 a MenuCommand instance is created to assigns the MenuItemCallback method as a response for the command specified with the CommandID instance. Line 13 entitles the menu command service to handle events related to the command. The result of this short initialization code is that your package handles the event when the user clicks the Simple Message menu item in the Tools menu by executing the MenuItemCallback method. In the next chapter you will find all nitty-gritty details about the command handling concepts used in Visual Studio and there you will learn much more about the initialization approach used here.

The MenuItemCallback method uses the IVsUIShell service to pop up a message box from within the IDE.

Registration Attributes

By now you know that packages are registered with Visual Studio in order to support the on-demand loading mechanism and allow merging menus and toolbars into the user interface of the IDE. The information to be registered is created during the build process from attributes assigned to the package class:

[PackageRegistration(UseManagedResourcesOnly = true)]
[InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
[ProvideMenuResource("Menus.ctmenu", 1)]
[Guid(GuidList.guidFirstLookPkgString)]
public sealed class FirstLookPackage : Package
{
  // --- Package body omitted
}

Packages are COM objects and so they must have a GUID uniquely identifying them. The Guid attribute is used by the .NET framework to assign this GUID value to a type. All attributes above except Guid are derived from the RegistrationAttribute class which is the abstract root class for all attributes taking a role in package registration. Table 3 describes the attributes decorating the FirstLookPackage:

Table 3: Registration attributes in FirstLookPackage

Source File	Description
PackageRegistration	Adding this attribute to a class, the build process will handle it as a package and looks for other attributes to prepare the package registration according to your intention. In the example this attribute sets the UseManagedResourcesOnly flag to tell that all resources used by the package are described in the managed package and not in a satellite DLL.
InstalledProductRegistration	This attribute is responsible to provide information to be displayed in the Help\|About dialog in the IDE. The constructor of this attribute requires four arguments with the following meanings: The first and second strings provide the name and the description of the package. The “#” characters indicate that these values should be looked up in the package resources with the IDs following “#”. The third “1.0” parameter is the product ID (version number). The fourth parameter (IconResourceID) tells which icon to use for the package. All resources (name, description and icon) should be defined in the VSPackage.resx file.
ProvideMenuResource	This attribute is to create registry entries about menu and toolbar items provided by the package. Visual Studio uses the embedded resources here to merge the package menus into the Visual Studio menus. The attribute has two parameters. The first is the so-called resourceID. This value is set to Menus.ctmenu as during the build process the VSCT compiler uses this value by default when adding the binary representation of the .vsct file to the package resources. The second parameter is called versionID and it plays important role in the caching mechanism of resources. In the next chapter you are going to examine the role of this attribute in details.

There are many other registration attribute beside the ones in the table above, later in the book we are going to meet a few of them. You are not constrained to apply only the registration attributes defined by the Managed Package Framework, and you can define your own attributes. Any of them including yours are handled on the same way by the build process as the predefined ones.

The Command Table

The wizard generated a file named FirstLook.vsct. It is an XML file and the file extension refers to the acronym coming from the “Visual Studio Command Table” expression. The schema of the XML file defines the command table owned by the package.

The command table is transformed into a binary format during the build process and is embedded into the package assembly as a resource. During the registration phase the ID of this resource is put into the registry. When Visual Studio starts, loads this binary resource information and merges it with the menus of the IDE including toolbars and context menus.

In order to avoid menu merges every time Visual Studio is launched, the IDE uses a cache mechanism and carries out the merge process only once for each package.

The next chapter will treat this mechanism and the structure of the command table in details. Listing 2 shows you the command table described in the FirstLook.vsct file.

Listing 2: FirstLook.vsct

<?xml version="1.0" encoding="utf-8"?>
<CommandTable xmlns="http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable" 
              xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <Extern href="stdidcmd.h"/>
  <Extern href="vsshlids.h"/>
  <Extern href="msobtnid.h"/>
 
  <Commands package="guidFirstLookPkg">
    <Groups>
      <Group guid="guidFirstLookCmdSet" id="MyMenuGroup" priority="0x0600">
        <Parent guid="guidSHLMainMenu" id="IDM_VS_MENU_TOOLS"/>
      </Group>
    </Groups>
 
    <Buttons>
      <Button guid="guidFirstLookCmdSet" id="cmdidShowMyMessage" priority="0x0100" type="Button">
        <Parent guid="guidFirstLookCmdSet" id="MyMenuGroup" />
        <Icon guid="guidImages" id="bmpPic1" />
        <Strings>
          <CommandName>cmdidShowMyMessage</CommandName>
          <ButtonText>Simple Message</ButtonText>
        </Strings>
      </Button>
    </Buttons>
   
    <Bitmaps>
      <Bitmap guid="guidImages" href="Resources\Images_32bit.bmp" usedList="bmpPic1, bmpPic2, bmpPicSearch, bmpPicX, bmpPicArrows"/>
    </Bitmaps>
  </Commands>
 
  <Symbols>
    <GuidSymbol name="guidFirstLookPkg" value="{d55758eb-6581-48fe-930b-f3536f43b6f0}" />
    <GuidSymbol name="guidFirstLookCmdSet" value="{05da2180-8d8e-4822-913b-b6a9012c4b2b}">
      <IDSymbol name="MyMenuGroup" value="0x1020" />
      <IDSymbol name="cmdidShowMyMessage" value="0x0100" />
    </GuidSymbol>
    <GuidSymbol name="guidImages" value="{49ba23b3-1631-483d-a095-003cb157f55d}" >
      <IDSymbol name="bmpPic1" value="1" />
      <IDSymbol name="bmpPic2" value="2" />
      <IDSymbol name="bmpPicSearch" value="3" />
      <IDSymbol name="bmpPicX" value="4" />
      <IDSymbol name="bmpPicArrows" value="5" />
    </GuidSymbol>
  </Symbols>
 
</CommandTable>

In this listing all comments placed into the generated file are omitted for saving space. However, it is worth to read those comments to have a better understanding of the command table structure.

The .vsct file tells a lot about how Visual Studio is architected, how it solves the coupling of functions (commands) and user interface elements.

Commands (actions to execute) are separated from the user interface element triggering the command. The same command can be assigned to different menus and toolbars; they will use the same action.
Commands used together can be grouped and simply merged into existing menus by using the command group representation. It is much easier then coupling commands with hosting menus one-by-one.
Elements are identified by symbols rather than using explicit values. This makes the coupling less error-prone: values of symbols must be defined only once, and the VSCT compiler can check for mistyping.

The root element of a .vsct file is the CommandTable element. As you can see all related elements are defined by the http://schemas.microsoft.com/VisualStudio/2005-10-18/CommandTable namespace. No doubt, the most important element is Commands, because this node defines commands, their initial layout and behavior.

Any command in the VS IDE must belong to the IDE itself or to a package. To assign a command to the appropriate (owning) VSPackage, the package attribute of the Commands element must name the GUID of the corresponding package.

Commands node can have a few child elements; each has a very specific role.

Group elements define so-called command groups; each of them is a logical set of related commands that visually stand together. In the FirstLook.vsct file we have a Group element that holds only a Button. A button represents a piece of user interface element the user can interact with, in this case a menu item that can be clicked. The Parent element defines the relationship between elements, for example the Button element defined above is parented in the Group.

Toolbars and menus would be poor without icons helping the user to associate a small image with the function. The Bitmap nodes allow defining the visual elements (icons) used in menus.

The Symbols section is a central place in the command table file where you can define the identifiers to be used in the other parts of the .vsct file. You can use the GuidSymbol element to define the “logical container GUID” and the nested IDSymbol elements to provide (optional) identifiers within the logical container. The name and the value attribute of these elements do exactly what you expect: associate the symbol name with its value.

The VSPackage Wizard put the generated GUID values into the FirstLook.vsct file but they also can be found in the Guids.cs file. The PkgCmdID.cs file defines constant values for the IDSymbol values used by package commands. These three files must be kept consistent, so if you change a GUID or a command identifier, the changes should be tracked in the other files as well; otherwise your package will not work as expected.

Package Resource Files

The FirstLook project has two resource files: Resources.resx and VSPackage.resx. They both utilize the resource handling mechanism in the .NET Framework, but have different roles.

Resources.resx is to store functional resources that are consumed by the objects and services of your package. For instance, you can store error messages, prompt strings, UI elements, logos, and so on in this resource file and access them programmatically through the static members of the Resources class generated by the ResXFileCodeGenerator custom tool attached to the .resx file.

VSPackage.resx can store resources just like Resources.resx, but its primary role is to embed package infrastructure resources. This resource file does not use the ResXFileCodeGenerator custom tool and so does not generate any helper class to access resources.

As you remember the package is decorated with the InstalledProductRegistration attribute which refers to resource identifiers 110, 112 and 400:

[InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]

These IDs refer to string and icon resources in the VSPackage.resx file as shown in Figure 12.

Figure 12: String resources in VSPackage.resx

Package resources will be extracted from the content of the VSPackage.resx file, so if you put them in the Resources.resx file, the package will not find the resource. Although you can put functional resources into VSPackage.resx file, their recommended place is the Resources.resx file.

The Package Build Process

Understanding the package build process can help a lot when you are about to debug or deploy your application. In this part you’ll learn the steps of this process in details.

Building a package is not simply compiling the package source code into a .NET assembly. There are other important steps to complete in order to use the package either in the Experimental Instance or in its productive environment.

When the wizard generates the package it adds new build targets to the .csproj file of the corresponding class library. You can discover these entries by first unloading the project and then editing the project file. If you want to try it, first right-click on the project file in Solution Explorer and use the Unload Project function, then activate the Edit FirstLook.csproj command also with right-click. When you scroll down to the bottom of the file you can discover the following entries:

<Import Project="$(MSBuildBinPath)\Microsoft.CSharp.targets" />
<Import Project="$(MSBuildExtensionsPath)\Microsoft\VisualStudio\v10.0\VSSDK\\uinput1?
  Microsoft.VsSDK.targets" />
 

The first Import entry can be found in any C# language projects to invoke the C# compiler and all the other tools (for example the resource compiler) to create the assemblies from the source project. The second Import entry is the one added by the VSPackage Wizard. The .targets file specified here contains Visual Studio SDK related build targets. If you would like to have a look at this file, you can find it in the MSBuild\Microsoft\VisualStudio\v10.0\VSSDK folder under Program Files. This book is not about MSBUILD, so you won’t find more explanations about what the build targets describe and how they internally work, instead, here are the steps of the package build process:

The Resources.resx and VSPackage.resx files are compiled into the corresponding .resource files.
With the help of the vsct.exe utility the content of the .vsct file belonging to the package is compiled into a binary file called CTO file. This file format is used by Visual Studio when merging the package menu and command information into the IDE menu.
The CTO file is merged into the VSPackage.resource file as a binary resource with the name of Menus.ctmenu.
The C# compiler is invoked to compile the project source code just like normally when we build a standard class library. During this step the Resources.resources file and the VSPackage.resources files are embedded into the assembly.
The CreatePkgDef.exe utility is executed and it scans the assembly for registration metadata information. Each registration attribute is translated to corresponding registry data. The utility is parameterized so that it creates a .pkgdef text file containing the information that is to be entered into the system registry.
The binaries of the package (including the .dll and .pdb file), the corresponding .pkgdef file and the VSIX manifest file are zipped into a file with .vsix extension. This .vsix file is the installation kit of the package. You will find this file just beside the binaries (in the bin\Debug or bin\Release or maybe in another folder depending on the build configuration). With double clicking on this file you can start the Visual Studio Extension Installer utility.
The .vsix file is installed in your LocalAppData folder under the Extensions subfolder of the Visual Studio Experimental Instance. The location of this folder depends on your user account and profile type. For example, if your user name is jsmith, you have installed Windows 7 on your C: drive and you have a local profile the build process will look for the C:\Users\jsmith\AppData\Local\Microsoft\VisualStudio folder and install the .vsix file under the 10.0Exp\Extensions subfolder. The extension will be enabled (setting a key in the registry).

As a result of the build process the package is available in the Experimental Instance. The next time you start the Experimental Instance, it scans the Extensions folder, uses the .pkgdef file of your package to create the appropriate registry settings, the package’s menus gets merged into the IDE, so your package is ready to run.

Debugging Visual Studio Packages

Anyone who develops software creates programming mistakes. Majority of them can be caught during a simple or more complex code review. Many of them are obvious and you can find them in the code after observing the faulty behavior. There are a few of them which cannot be easily caught without using a debugger.

Developing VSPackages is the same story. Sooner or later you find yourself debugging a package and searching for a bug. This book does not want to go into details about debugging techniques; this is definitely not its topic. However, you will learn how easy is to debug your package and what is going behind the scenes.

To debug or run a package you should set it as the startup project. If your package is the only project is the solution, it is already marked so. If you have more projects in the solution, you should mark any VSPackage project as the startup project.

Independently if you run a package with or without debugging, the Visual Studio Experimental Instance is started. You can check it on the project property pages on the Debug tab as Figure 13 shows it for the FirstLook project.

Figure 13: Debug properties

You can see that devenv.exe is selected as the startup project and it is launched with the /rootsuffix Exp command line parameters. As you have learnt before this command line starts the Experimental Instance.

When you start the project with the Start Debugging (F5) function Visual Studio attaches the debugger to the Experimental Instance and so you can set breakpoints in Visual Studio. As your package running in the Experimental Instance reaches a breakpoint, you are taken back to the debug view as Figure 14 illustrates it. In this case a breakpoint was set within the Initialize method of the FirstLookPackage class.

Figure 14: The debugger in action

You can use the same techniques for debugging a VSPackage as for any other applications. All debugging features of Visual Studio are accessible: you can watch variables, evaluate expressions, set up conditional breakpoints, and so on.

There are cases when you would like to trace your application without a debugger using trace messages. You can follow this practice with Visual Studio. The simplest one is writing to the Debug pane of the Output window. You can learn about this topic in Chapter 3.

Deploying a Package

It is very comfortable to use the Experimental Instance while developing a package. The build process takes care about setting up your package to work, so you can use either the Start Debugging or Start Without Debugging commands to try what you’ve created. However, when your package is ready for distribution you should care about deployment questions.

Package Deployment in the Past

With Visual Studio versions preceding 2010 developers had to do some extra activities to prepare packages for deployment and it has a few potential pitfalls. The two main issues were that you needed to obtain a so-called Package Load Key (PLK) through a web page and take care of entering the required entries into the registry to allow Visual Studio recognize and integrate your package.

¾ Any change in package information like name, GUID, company or version required obtaining a new PLK. The Experimental Hive (this is what is now called Experimental Instance) did not check the PLK by default, so it often happened that developers faced with a wrong (missing or not renewed) PLK only after the installation kit was built and tested in the production Visual Studio environment.

¾ While the build process automatically registered the package under the Experimental Hive, developers had to create their own registration mechanism in the installation kit. It was not difficult, but because it was not automatic, forgotten registration updates could have led to annoying issues.

The VSIX installation

The new deployment mechanism built into Visual Studio 2010 removes this pain and provides an easy and straightforward way for package deployment.

Generally the easiest form of deploying an artifact is if you have an installation kit. The package build process as treated earlier creates this installation kit as a .vsix file containing the package binaries and some additional information. You can distribute your package by simply distributing the .vsix file to your customers. When they receive it, the Visual Studio Extension Installer utility can be started with double clicking on the .vsix file as Figure 15 illustrates.

Figure 15: Installing a VSIX file

When you click install the content of the VSIX file will be installed to the specified Visual Studio instance.

If you create a package for a broad set of customers or for the community, you can upload the VSIX file to the Visual Studio Gallery. The new Shell of Visual Studio contains a great tool called Extension Manager that is able to search this gallery for extensions, install or remove them, and keep track of installed extensions as well as managing their updates. Figure 16 shows a screenshot of the Extension Manager browsing the extensions available on Visual Studio Gallery.

Figure 16: Browsing Visual Studio Gallery with the Extension Manager

You can select any of the components while browsing, and on the right pane of the window you find some more details about the highlighted item. With the More Information link you will be directed to component’s home page on the Visual Studio Gallery. If you like this component, you can get it with the Download button just as others can obtain your uploaded components. The Extension Manager is the recommended way to obtain extensions. Because it runs within a Visual Studio instance, you can use it to install a separate set of components for your development environment and for the Experimental Instance. When using the Visual Studio Extension Installer utility your components will be installed under the normal development environment by default.

It was mentioned earlier that the build process packages the binaries and some other files into the VSIX file. In order the installation process could understand your .vsix installation file you need to create a so-called VSIX manifest file that is the soul of the installation kit. This file describes the metadata that is used as the set of instructions about what, where and how should be put during the setup. The VSPackage Wizard automatically creates this manifest for you and names the file as source.extension.vsixmanifest. You are probably not surprised that the manifest is an XML file with its own schema. When the FirstLook package was generated the wizard created the manifest shown in Listing 3:

Listing 3: source.extension.vsixmanifest

<?xml version="1.0" encoding="utf-8"?>
<Vsix Version="1.0.0" xmlns="http://schemas.microsoft.com/developer/vsx-schema/2010">
  <Identifier Id="d55758eb-6581-48fe-930b-f3536f43b6f0">
    <Name>FirstLook</Name>
    <Author>DeepDiver</Author>
    <Version>1.0</Version>
    <Description xml:space="preserve">Demonstrates the basic VSPackage concepts</Description>
    <Locale>1033</Locale>
    <InstalledByMsi>false</InstalledByMsi>
    <SupportedProducts>
      <VisualStudio Version="10.0">
        <Edition>Pro</Edition>
      </VisualStudio>
    </SupportedProducts>
    <SupportedFrameworkRuntimeEdition MinVersion="4.0" MaxVersion="4.0" />
  </Identifier>
  <References>
  </References>
  <Content>
    <VsPackage>|FirstLook;PkgdefProjectOutputGroup|</VsPackage>
  </Content>
</Vsix>
 

The root element of the manifest structure is the VSIX element that uses the http://schemas.microsoft.com/developer/vsx-schema/2010 namespace. The manifest contains three sections:

Identifier is used to uniquely define the different installation packages. The information here is used by the setup mechanism to manage the initial setup and the updates using the Id attribute and Version element values. This section also contains information describing the package and attributes taken into account during the setup process.
References element contains a collection of dependencies. Each item is a Reference element which defines a dependency on another product. In the FirstLook.vsix sample the package contains one dependency.
The Content element is a collection of content items that are packed in the payload. It our case the content is a VSPackage where the value of the item is used to generate the .pkgdef file containing the package information.

When running the Visual Studio Extension Installer or using the Extension Manager, the VSIX manifest is used to determine how the VSIX package should be set up. The VSPackage content type tells the installer that the related FirstLook.pkgdef file will contain the information to be put into the registry in order to register the COM object representing a Visual Studio package. The FirstLook.pkgdef file that has been created during the build process contains the information in Listing 4:

Listing 4: FirstLook.pkgdef

[$RootKey$\InstalledProducts\FirstLookPackage]
@="#110"
"Package"="{d55758eb-6581-48fe-930b-f3536f43b6f0}"
"PID"="1.0"
"ProductDetails"="#112"
"LogoID"="#400"
[$RootKey$\Packages\{d55758eb-6581-48fe-930b-f3536f43b6f0}]
@="DeepDiver.FirstLook.FirstLookPackage, FirstLook, Version=1.0.0.0, Culture=neutral, PublicKeyToken=8e5c6425e9b83cf4"
"InprocServer32"="$WinDir$\SYSTEM32\MSCOREE.DLL"
"Class"="DeepDiver.FirstLook.FirstLookPackage"
"CodeBase"="$PackageFolder$\FirstLook.dll"
[$RootKey$\Menus]
"{d55758eb-6581-48fe-930b-f3536f43b6f0}"=", Menus.ctmenu, 1"

The content of this file resembles to the content of a .reg file that can be exported from or imported to the Windows registry. However, the .pkgdef file contains a few tokens closed between dollar signs. The values of these tokens are passed by the context of the .pkgdef file to the entity processing the file content.

For example, if you use the Visual Studio Extension Installer utility to process the .vsix file, the utility extracts the payload into the Microsoft\VisualStudio\10.0\Extensions subfolder under the LocalAppData folder of your user profile. The files are put not directly into the Extension folder but into the subfolder calculated from the Author, Name and Version elements of the manifest’s Identity section. In this case the payload includes the FirstLook.pkgdef and FirstLook.dll files beside a few others.

When Visual Studio starts, it recognizes that a new .pkgdef file is under the Extensions folder and processes it. It substitutes the $RootKey$ token with the corresponding registry root of Visual Studio 2010, $Windir$ with the current Windows installation folder, $PackageFolder$ with the encapsulating folder of the .pkgdef file. After Visual Studio startup finishes, all information required to find and load the package is entered into the registry. When the first action demanding the package is executed, Visual Studio can pick up and initialize it.

Summary

A VSPackage is the principal architectural unit of Visual Studio, a container for extensibility objects. It is also a unit from deployment, security and licensing aspects. Packages are not loaded immediately as Visual Studio starts, they are read into the memory on-demand at the first time when any of their objects or services is about to be used.

The process of integrating a package physically into the Shell is called siting. While the package is not sited, its functions cannot be used from outside. As soon as the package gets sited, it is ready to finish its initialization and be fully functional. Siting happens when Visual Studio loads the package.

Visual Studio keeps track of packages installed through registration, and package information is stored in the system registry under a specific Visual Studio key. With command line parameters this registration key can be suffixed in order to use another configuration set — even with separate package registration parameters.

The Visual Studio SDK sets up the Visual Studio Experimental Instance which is a test bed to run and debug Visual Studio packages during the development and test phases. The Experimental Instance is not a separate Visual Studio installation, it uses the same devenv.exe file but with different configuration settings.

VSPackages use a build process that contains some additional steps in order to prepare the packages for debugging or deployment. The easiest way to create a package is running the VSPackage Wizard which sets up the build process appropriately. During this process package infrastructure resources — like to so-called command table — are embedded into the package assembly, the package installation kit is created and installed under the Experimental Instance.

During the development phase packages run inside the process space of the Experimental Instance and the same debug techniques can be used for tracing and troubleshooting as for any other .NET applications.

VSPackage deployment in Visual Studio 2010 became really simple related to the preceding versions. The package installation kit is represented by a VSIX file that can be distributed directly to the users of your package or — and this way opens up brand new opportunities — uploaded to the Visual Studio Gallery. The Extension Manager built into the IDE can be used to browse, install, and remove VSPackages (and many other kinds of extensions) as well as to keep track of them.