Browser Link feature in Visual Studio 2013 provides APIs for you to write your own Browser Link Extension. To take a look at some of the extensions, you can download Web Essentials for Visual Studio 2013 RTM.
In this blog, I will give you a step by step overview of the various APIs that we provide.
You will need the following to start with:
- Visual Studio 2013 RTM.
- Visual Studio 2013 SDK.
- Go to http://sidewaffle.com/ and download a template for extensions.
Once you have installed all of the above, you can get started:
Step 1: Go to File –>New-> Visual C# –> Extensibility and select Browser Link Extension as shown in the image below.
Click OK, to create MyBrowserLinkProject. The browser link project will have a C# file and a JavaScript file. In the sample project, we have MyBrowserLinkProjectExtension.cs file and a MyBrowserLinkProjectExtension.js file.
MyBrowserLinkProjectExtension.js contains the script that will be injected in every browser that is invoked after Visual Studio is launched.
Step 2: Open file MyBrowserLinkProjectExtension.cs.
Here you will find a MyExtensionFactory class that implements interface IBrowserLinkExtensionFactory and MyExtension class that derives from base class BrowserLinkExtension.
MyExtensionFactory class has a CreateExtensionInstance() method and a GetScript().
CreateExtensionInstance method takes in a connection object. A connection can be thought of as a link to a page being rendered. For example, if Visual Studio has IE and Chrome browser rendering a particular page, then each of these can be thought of as a unique connection. You can create a new instance of an extension object or return the same instance of the extension object depending on what you want to do per connection.
- publicBrowserLinkExtension CreateExtensionInstance(BrowserLinkConnection connection)
- {
- returnnewMyExtension();
- }
GetScript method just reads the script to use from MyBrowserLinkProject.js file.
- publicstring GetScript()
- {
- using (Stream stream = GetType().Assembly.GetManifestResourceStream("MyBrowserLinkProject.Scripts.MyBrowserLinkProject.js"))
- using (StreamReader reader = newStreamReader(stream))
- {
- return reader.ReadToEnd();
- }
- }
Step 3: Now, let us look at the MyExtension class itself. This file contains an OnConnected method which you can implement and any number of Browser Link Callback methods.
- publicclassMyExtension : BrowserLinkExtension
- {
- publicoverridevoid OnConnected(BrowserLinkConnection connection)
- {
- Browsers.Client(connection).Invoke("greeting", "Hello from Visual Studio!");
- }
- [BrowserLinkCallback] // This method can be called from JavaScript
- publicvoid SendText(string message)
- {
- MessageBox.Show(message);
- }
- }
OnConnected() will be called when a connection between Visual studio and browser has happened. This is a good place to do any kind of initialization. In our example, we have chosen to Invoke the greeting function in Javascript.
- publicoverridevoid OnConnected(BrowserLinkConnection connection)
- {
- Browsers.Client(connection).Invoke("greeting", "Hello from Visual Studio!");
- }
This is how we can make a call from Visual Studio to the browser. In the above example we are trying to call the greetings function in the browser from within visual studio’s extension.
Step 4: Open MyBrowserLinkProjectExtension.js file and you will see the greeting function which you invoked in step 3.
- (function (browserLink, $) {
- ///
- ///
- function output(message) { // Helper for the 'greeting' function
- if (console) {
- console.log(message);
- }
- }
- return {
- greeting: function (message) { // Can be called from the server-side extension
- output(message);
- },
- onConnected: function () { // Optional. Is called when a connection is established
- browserLink.invoke("SendText", "Hello from " + browserLink.initializationData.appName);
- }
- };
- });
Now let us see how we can make a call from Browser to Visual studio. For this, you will need Browser Link Callback methods defined in your extension.
In our example, you can see that we have a “SendText” method with a [BrowserLinkCallback] attribute. This means, this method can be called from javascript running in your browser.
- [BrowserLinkCallback] // This method can be called from JavaScript
- publicvoid SendText(string message)
- {
- MessageBox.Show(message);
- }
Step 5: Do F5 and this will open up the experimental instance of VS. Here, create a new webforms website. Bring up the Browser Link dashboard. Click on the view in browser link here.
This will bring up a Message box which says “Hello from Internet Explorer”. This way you can see Browser’s JavaScript invoking a Visual studio method.
Step 6: If you invoke F12 tools in IE, you can see a Browserlink.js file that plugs in the extension script for you in all the browsers.
You can also see that Visual studio has successfully printed in your console. This was done by greetings function in your JavaScript.
Step 1 to 6 was a basic introduction of some of the APIs that you would require to get started.
Step 7: Let us look at Actions API.
These APIs provide a way for your Actions(BrowserLinkCallBack Methods) to be invoked via the Browser link Dashboard.
This will give you an entry in the context menu of your connection right next to the Refresh Extension as shown in the image below.
In our Example, we have two actions defined. One is “Action for SendText” and the other is “Action for Greetings”.
To do this you will need to add the following piece of code:
- publicoverrideIEnumerable<BrowserLinkAction> Actions
- {
- get
- {
- returnnewBrowserLinkAction[] {
- newBrowserLinkAction("Action for SendText", this.AddSendText),
- newBrowserLinkAction("Action for SendGreetings", this.AddGreetings),
- };
- }
- }
Note that, each of these Action methods AddSendText and AddGreetings inturn invoke a BrowserLinkCallBack method.
- publicvoid AddSendText(BrowserLinkAction action)
- {
- SendText("Invoked from Actions context menu!");
- }
- publicvoid AddGreetings(BrowserLinkAction action)
- {
- SendGreetings("Invoked via Actions: Hello from Visual Studio!");
- }
Here are their corresponding BrowserLinkCallBack methods:
- [BrowserLinkCallback] // This method can be called from JavaScript
- publicvoid SendText(string message)
- {
- MessageBox.Show(message);
- }
- [BrowserLinkCallback] // This method can be called from JavaScript
- publicvoid SendGreetings(string message)
- {
- Browsers.Client(_browserlinkConnection).Invoke("greeting", message);
- }
At this point, you can do an F5 on MyBrowserLinkProject. This will open up the experimental instance of VS. Create a Website here and Browse About.aspx with IE and Chrome.
Now click on the little arrow next to chrome and that will bring up the Actions menu for you.
Click on Action for SendGreetings and it will print out the following in Chrome’s console as shown in the image below. This lets you test out the BrowserLinkCallback methods quickly on a per connection basis. You can also invoke this on IE and see similar results.
Step 8: Mapping Data API.
The API will provide two kinds of operations: mapping a source file position to a DOM element, and mapping a DOM element to a source file range.
All mapping operations will involve a DOM element reference. DOM elements only exist in the browser; they cannot be marshaled to the Visual Studio process. Because of this, the API will only be available in JavaScript. There will be no way to use the API directly from C#.
Each element that can be mapped will have a sourceMapping property attached to it.
Let us see a quick example. Open file MyBrowserLinkProjectExtension.js.
Inside the greeting method, add the following two lines of code. In the example, we are trying to get div1 and open the source file with the complete range for div tag selected.
- greeting: function (message) { // Can be called from the server-side extension
- output(message);
- var testElement = document.getElementById("div1");
- browserLink.sourceMapping.selectCompleteRange(testElement);
- }
Now, do an F5 again. This will bring up experimental instance. Create a Razor website. In About.cshtml file add the following
div tag:
View this page in IE Browser. Now from the Dashboard, invoke the “Action for SendGreetings”. This will select the text in source view as shown in the image below.
You can download WebEssentails2013 and look at InspectModeBrowserLink.js to see how to make use of the Mapping Data API.
Hope this was useful.
Thanks,
Reshmi