Microsoft Visual C# Starter Kit (Visual Studio 2010)
Starter Kit: ADO.NET Entity Data Model Designer Extension
Introduction
Goals
Building the Project and Deploying the Extension
Testing the Extension
Modifying the Extension
Debugging the Extension
Un-Installing the Extension
How an ADO.NET Entity Data Model Designer Extension Works
Ideas for More Extensions
Resources
Introduction
This Visual C# Starter Kit is a complete ADO.NET Entity Data Model Designer (Entity Designer) extension. Building the project "as is" will produce a Visual Studio extension (a .vsix file) that extends the functionality of the Entity Data Model Designer in the following ways:This starter kit also contains placeholder classes for transformation and conversion extensions. By writing code for these classes you can do the following:
Note: The functionality described above can be implemented to work together in a Visual Studio extension. For example, a conversion extension could load a custom file which could then be modified by a transformation extension. Then, the conversion extension could convert the file back to the custom format when it is saved.
You can customize this functionality further by modifying the source code and rebuilding the project. (For more information, see Modifying the Extension and Ideas for More Extensions.) You are free to use this project's source code as the basis for your own extension projects. You are also free to share your work with others or upload it to the Internet.
Note: This documentation assumes that you are familiar with the following technologies:- Visual Studio 2010/.NET Framework 4 versions of the ADO.NET Entity Data Model Tools and the ADO.NET Entity Framework.
- The basic principles of the Managed Extensibility Framework (MEF).
- Basic programming concepts and the Visual C# programming environment.
Goals
This starter kit helps you understand how an Entity Data Model Designer extension works provides you with a Visual Studio 2010 project that you can use as the basis for your own extensions.
This starter kit demonstrates the following features:
- Model generation extension — Use extensibility interfaces to influence the "create model from database" functionality of the Entity Data Model Wizard.
- Property extension — Use extensibility interfaces to make custom properties visible in the Visual Studio Properties window and make the properties available only when specific types of objects are selected in the Entity Designer.
- Update model extension — Use extensibility interfaces to influence the "update model from database" functionality of the Update Wizard.
- Packaging and deployment — Package content and extension manifests into a .vsix file and deploy the .vsix file.
- Debugging — Debug the extension.
Building the Project and Deploying the Extension
Building the Project
Building this starter kit project creates a Visual Studio extension that can be deployed to any Visual Studio 2010 installation.
To build the project:- Open the project in Visual Studio 2010.
- Press Ctrl+Shift+B to build the project.
Building the project creates a .vsix file in the output directory (typically the bin/debug or bin/release directory in the project directory). A .vsix file is a Visual Studio extension that can be deployed to a Visual Studio installation.
Deploying the Extension
After you create the .vsix file by building the project, you can deploy the extension by performing the following steps:- Open Visual Studio if it is not already open.
- Locate and double-click the Microsoft Visual Studio Extension file (the the .vsix file).
- Follow the instructions in the Visual Studio Extension Installer to install the extension.
- Exit and restart Visual Studio to load the extension.
- After restarting Visual Studio, click Tools in the main menu and then click Extension Manager to show the Extension Manager dialog box. Ensure that the extension you just installed is visible under Installed Extensions.
Testing the Extension
To test the model generation extension...
- Open Visual Studio if it is not already open.
- Create a new C# Console Application project.
- Add a new ADO.NET Entity Data Model item to the project by choosing Add New Item... from Project in the main menu.
- In the Entity Data Model Wizard, select Generate from Database, choose a connection, select some tables, and then click Finish.
Code in the model generation extension executes a simple message box with an OK button appears.
- Click OK to continue and to add the generated model to the project.
To test the property extensions...
- Click an entity type on the Entity Designer surface and press
F4 to show the Properties window.
Two new properties are available in the Properties window: a boolean property called My New Property and an Int32 property called My New Property 2. Note that these properties are only available when an entity type is selected on the Entity Designer surface or in the Model Browser window. My New Property was added by the model generation extension and has a corresponding element in the .edmx document. My New Property 2 is visible in the Properties window, but does not have a corresponding element in the .edmx document until the property value is changed and the .edmx document is saved.
- Change the value of My New Property 2 to 1 in the Properties window and note that the .edmx file has been modified (as indicated by the * next to the file name).
- Save the .edmx file.
- Right-click the .edmx file in Solution Explorer, click Open With..., and then select XML Editor in the Open With dialog.
- Locate the entity type that has the newly modified property value in the <edmx:ConceptualModels> element and note that My New Property 2 is saved as a new XML element under the <EntityType> node:
<EntityType Name="Entity1">
<Key>
<PropertyRef Name="Id" />
</Key>
<Property Type="Int32" Name="Id" Nullable="false" />
<a:MyNewProperty2 xmlns:a="http://schemas.tempuri.com/MyNewProperty2">1</a:MyNewProperty2>
</EntityType>
Note: This XML element is a
structured annotation and can be accessed with public Entity Framework metadata APIs
at design time and runtime.
To test the update model extension...
- Right-click an empty area on the Entity Designer surface and choose Update Model from Database .
- Select a table and click Finish.
Code in the update model extension executes and a simple message box with an OK button appears.
- Click OK to continue.
Modifying the Extension
You can edit the source code to change the functionality of the extension. The example below makes the My New Property property available when an EntityType or a NavigationProperty is selected.
To make a property available when an entity type or a navigation property is selected...
The Entity Designer calls the CreateProperty() method of a property extension depending on values specified in the EntityDesignerExtendedProperty attribute in the class that implements the IEntityDesignerExtendedProperty interface. A property extension can specify a variety of selection combinations depending on the scenario.
- Open the file MyNewPropertyFactory.cs
- Change the line:
[EntityDesignerExtendedProperty(EntityDesignerSelection.ConceptualModelEntityType)]
to:
[EntityDesignerExtendedProperty(EntityDesignerSelection.ConceptualModelEntityType | EntityDesignerSelection.ConceptualModelNavigationProperty)]
- Press Ctrl+Shift+B to build the project.
- Uninstall the extension as described below in UnInstalling the Extension.
- Reinstall and test the extension as described above in Building the Project and Deploying the Extension and Testing the Extension.
- Note that the new boolean property My New Property is now available in the Properties window when an Entity or a NavigationProperty is selected in the designer canvas or the Model Browser. Note also that a corresponding MyNewProperty element is not added to the .edmx document until the property value has been changed and the .edmx document saved.
Debugging the Extension
You can debug an installed extension in Visual Studio 2010 as follows:
- Ensure that the extension is installed as described in the section Deploying the extension.
- Start Visual Studio 2010 if it is not already running.
- Open the extension project and set breakpoints as desired. For example, open the file MyNewPropertyFactory.cs and set a breakpoint on the CreateProperty() method.
- Press F5 to start debugging.
- Test your extension as described in the section Testing the Extension in the second instance of Visual Studio 2010.
A second instance of Visual Studio 2010 is started.
Breakpoints in the first instance of Visual Studio 2010 are hit when an EntityType is selected in the the second instance of Visual Studio 2010.
UnInstalling the Extension
To uninstall the extension...
- Start Visual Studio 2010 if it is not already running.
- In Visual Studio 2010, click Tools in the main menu, and then click Extension Manager to show the Extension Manager dialog box.
- Click the extension you wish to uninstall and click Uninstall.
- Click Restart to restart Visual Studio 2010.
How an Entity Designer Extension Works
This starter kit project contains six C# source-code files in the project root folder that make up the extension and three files in the VSIX folder that are needed to package the extension into a Visual Studio extension (a .vsix file). The source code files perform the following functions:
Property extension |
MyNewPropertyFactory.cs and MyNewProperty2Factory.cs |
These two files contain the MyNewPropertyFactory and MyNewProperty2Factory classes that implement the IEntityDesignerExtendedProperty interface.
|
MyNewProperty.cs and MyNewProperty2.cs |
Contains the MyNewProperty and MyNewProperty2 classes whose public properties are shown in the Visual Studio Properties window. These classes use attributes in System.ComponentModel (such as DisplayName, DefaultValue, Description, Category, etc.) to control appearance in the Properties window.
|
Model Generation extension |
ModelGenerationExtension.cs |
This file contains the ModelGenerationExtension class that implements the IModelGenerationExtension interface.
|
See the starter kit source code for more details about the ModelGenerationExtensionContext and UpdateModelExtensionContext classes. |
VSIX extension manifest |
extension.vsixmanifest |
This XML file is required to package your Entity Designer extension as a
.vsix package and has information about the extension such as Author, Supported VS
editions, and MEF component name. Double-click extension.vsixmanifest
to open it in XML Editor and change it as necessary for your extension.
Specifically, if you change the Assembly Name in
Project Properties also remember to change at least the following lines
in extension.vsixmanifest:<Identifier ID="your-new-extension-identifier-name-goes-here">
<Content>
<MEFComponent>your-new-assembly-name-goes-here</MEFComponent>
</Content>
|
Ideas for More Extensions
Category |
Description |
End-to-End Scenarios |
|
Property Extensions |
|
Model Generation |
|