How-To

Code Documentation Generation with SandCastle

Stacy Vicknair — Wed, 26 Oct 2011 01:15:38 GMT

If you, like me, have ever looked over the MSDN documentation and though how nice it would be to have that type of documentation for your codebase, SandCastle is the tool you’ve been looking for. SandCastle is a Codeplex project initiated by Microsoft in order to provide MSDN-esque documentation for .NET projects or asssemblies. The documentation can come in several formats such as CHM files or a website.

GhostDoc and SandCastle Help File Builder

To get started with SandCastle for documentation, I recommend a few additional tools: GhostDoc and SandCastle Help File Builder.

GhostDoc is a Visual Studio extension that allows quick XML documentation to be generated based on naming convention for methods, properties and parameters. XML documentation is the heart of how SandCastle generates documentation, so being able to quickly generate simple comments is a great benefit. The Pro version of GhostDoc also allows for customizations based on T4 templating.

SandCastle Help File Builder is a second Codeplex project that adds a GUI and additional support for SandCastle to make the overall experience of its use even better.

Installation

For a comprehensive installation guide, check out the SandCastle Help File Builder Installation Instructions. Their guided installer is easy to use and will verify that everything you need is in the right place. It will also let you know if you are lacking any dependencies you might need for generating specific help file types.

Usage

Once you have SHFB installed, open the SandCastle Help File Builder GUI and select File > New Project… then choose a location and name for your project. I follow the conventions for project naming that we use for any other project type and add the project to a subdirectory of the code solution.

SHFB saves projects as shfbproj types. These types can be built using MSBuild and incorporated into your current build processes. Do note that the time to generate documentation has a fair amount of overhead to reflect through your generated code.

After you have saved your project you can proceed to customize the sources to document by right clicking Documentation Sources then browsing to either the solution, project, or dll file you would like to include.

If you are looking to generate an HTML site specifically, this can be set on the HelpFileFormat under the Build section of the project properties.

Afterwards, just select Documentation > Build Project to create your very own MSDN-esque documentation!

Links

http://sandcastle.codeplex.com
http://shfb.codeplex.com/
http://submain.com/products/ghostdoc.aspx
http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/8c0c97d0-c968-4c15-9fe9-e8f3a443c50a.htm
http://broadcast.oreilly.com/2010/09/build-html-documentation-for-y.html

Unit Testing Role-based Authorization in ASP.NET MVC 3

Stacy Vicknair — Tue, 23 Aug 2011 13:02:13 GMT

When testing in ASP.NET MVC3, one of the common elements you might want to test is authorization. Although the framework does most of the heavy lifting for ASP.NET Membership and authorization it is still worthwhile to be able to write a test to show that the proper Authorization tag is in place.

You might think that it’s as easy as calling the method on the controller with a proper context, but that’s not the case. When you call the methods directly on the controller the authorizations are skipped. These authorizations are handled by the ActionInvoker when the MVC application runs, so in order to test this via MVC itself would take a lot of cruft. Since we trust that ASP.NET MVC is doing its job correctly it is easier to simply test for the presence of the attributes.

Since this is such a common task I ventured forth to create an extension method that will accomplish exactly what I want with the API I want. Using a lambda syntax most of us are familiar with from mocking frameworks, the final product yields a test method like the following:

        1: <TestMethod()>

       2: Public Sub Register_WhenUserIsInAdministratorRole_ShouldBeAuthorized()

       3:     'Arrange

       4:     Dim target = New AccountController()

       5:  

       6:     'Assert

       7:     target.AssertRoleIsAuthorizedForAction(Sub(a) a.Register(New RegisterModel()), "Administrator")

       8: End Sub

Simply pass in a lambda of the action you are attempting to test along with the role you expect authorization to be successful for. The extension method code is as follows:

       1: <Extension()>

       2: Public Sub AssertRoleIsAuthorizedForAction(Of T As Controller)(ByVal controller As T,

       3:     ByVal expression As Expression(Of Action(Of T)), role As String)

       4:  

       5:     'Arrange

       6:     'Get method from expression

       7:     Dim callExpression = TryCast(expression.Body, MethodCallExpression)

       8:     If callExpression Is Nothing Then

       9:         Throw New ArgumentException("Could not determine method from expression", "expression")

      10:     End If

      11:  

      12:     'Act

      13:     Dim roles = callExpression.Method.GetCustomAttributes(GetType(AuthorizeAttribute), inherit:=True) _

      14:         .Cast(Of AuthorizeAttribute)() _

      15:         .Where(Function(a) Not String.IsNullOrEmpty(a.Roles)) _

      16:         .SelectMany(Function(a) a.Roles.Split(",")) _

      17:         .ToList()

      18:  

      19:     'Assert

      20:     Assert.IsTrue(roles.Contains(role))

      21: End Sub

The method takes the given lambda and extracts the method. Then the AuthorizeAttributes for the method that include roles are split into a list of roles. Finally we assert that the list of roles contains our role in question.

In C#:

       1: [TestMethod]

       2: public void Register_WhenUserIsInAdministratorRole_ShouldBeAuthorized()

       3: {

       4:     //arrange

       5:     var accountController = new AccountController();

       6:  

       7:     //assert

       8:     accountController.AssertRoleIsAuthorizedForAction(ac => ac.Register(new RegisterModel()), "Administrator");

       9: }

       1: public static void AssertRoleIsAuthorizedForAction<T>(this T controller, 

       2:     Expression<Action<T>> expression, string role) where T : Controller

       3: {

       4:     //Arrange

       5:     //Get method from expression

       6:     var callExpression = expression.Body as MethodCallExpression;

       7:     if(callExpression == null)

       8:         throw new ArgumentException("Could not determine method from expression", "expression");

       9:  

      10:     //Act

      11:     var roles = callExpression.Method.GetCustomAttributes(typeof(AuthorizeAttribute),true)

      12:         .Cast<AuthorizeAttribute>()

      13:         .Where(a => !string.IsNullOrEmpty(a.Roles))

      14:         .SelectMany(a => a.Roles.Split(','))

      15:         .ToList();

      16:  

      17:     //Assert

      18:     Assert.IsTrue(roles.Contains(role));

      19: }

References:
http://stackoverflow.com/questions/669175/unit-testing-asp-net-mvc-authorize-attribute-to-verify-redirect-to-login-page
http://darioquintana.com.ar/blogging/2009/05/23/aspnet-mvc-testing-a-custom-authorize-filters/

Technorati Tags: MVC,ASP.NET,ASP.NET MVC3,MVC3,Unit Testing,Authorize

MSXML 6 failure on SQL Server 2005 Tools install

Stacy Vicknair — Thu, 10 Sep 2009 02:37:39 GMT

Today I ran into this problem when setting up the SQL Server Management Tools for SQL Server 2005. Like any good little code slinger, I googled (if you are particular to Microsoft, you can read that as “binged”) to see who’s had the problem, because it’s no news that when you aren’t on the crest of the tech wave that someone else has had the same issue.

In particular, MSXML 6 would fail and the log would have a message similar to:

MSI (s) (40:58) [22:16:00:859]: MainEngineThread is returning 1605

Well, undoubtedly I found many other results for others who have had this issue, primarily those that have XP SP3. To get around this failure, you’ve got to install the tool available at the link below and then use it to remove any entry starting with MSXML 6. For me, I had two entries, one “parser” and one SP2. Afterwards, just start the install over again.

I think what made the experience frustrating for me is that the SQL Server 2005 Setup fails in too friendly of a way. I’m used to the brutal honesty of the NUnit GUI. Give me a big red bar to illustrate how bad I failed or get out.

For the uninstall tool:
http://support.microsoft.com/kb/290301

A couple resources about the problem itself:
http://social.msdn.microsoft.com/Forums/en-US/sqlsetupandupgrade/thread/493b5a95-1af6-4ec1-aa24-92875e4497c0
http://www.eggheadcafe.com/conversation.aspx?messageid=33740907&threadid=33664744

Technorati Tags: MSXML6,MSXML,SQLServer2005,SQL Server 2005

How To: Create a plugin architecture in VB.NET

Stacy Vicknair — Thu, 07 May 2009 01:19:35 GMT

Creating a plugin architecture in .NET can be achieved in a few steps using the .NET framework. All it takes is a little time, a common interface and reflection. In this blog we’re going to look at how to make a simple plugin that performs basic integer calculations. As a disclaimer, this method is not CLS compliant. If that is necessary for you, then stick around and I hope to have a new version that maintains compliance posted.

The code in this blog is mostly illustrative, and the full code is available on CodePlex at the following link:

http://wtfnext.codeplex.com/Release/ProjectReleases.aspx?ReleaseId=27051

Setting up a common interface

Our main console application has to know just basic things about our plugin. It doesn’t need to know any more about it than that it complies to an expected interface. For this example, our plugins must:

Expose a class named Plugin
The class must implement our common interface: IPlugin.
The plugin must end in “Plugin.dll” and be present in the application directory.

If we get all of these done, we can connect to the plugin successfully. The first step is to define the IPlugin interface, which acts as the basic contract between any plugin and the console application. We’ll place this in its own project to compile into a separate DLL, so that we can easily reference it from our plugin projects.

Public Interface IPlugin
    ReadOnly Property Name() As String
    ReadOnly Property ActionName() As String
    Sub Calculate(ByVal value1 As Integer, ByVal value2 As Integer)
End Interface

Consuming the interface according to our rules

So our calculation plugins will expose the name, what their action is and a calculate function that operates on two values. We can create an example plugin that performs addition:

Public Class Plugin
    Implements IPlugin

    ReadOnly Public Property Name() As String Implements IPlugin.Name
        Get
            Return "Addition"
        End Get
    End Property

    ReadOnly Public Property ActionName() As String Implements IPlugin.ActionName
        Get
            Return "Add Values"
        End Get
    End Property

    Public Sub Calculate (ByVal value1 As Integer, ByVal value2 As Integer) Implements IPlugin.Calculate
        Dim result As Integer = value1 + value2
        MessageBox.Show ("The result is " + result.ToString)
    End Sub
End Class

See how we named the class that implements the plugin as just Plugin? This is because this is what the consol application expects. We can have other classes and whatnot in our plugin that do the meat of our work, but the application that consumes the plugin only cares that the possible plugin follow our rules stated earlier.

Checking and consuming the plugin

In our console application, all we’ve got to do is grab our possible plugins, then check their validity. Once we’re sure it is valid, we can consume it via the interface.

Dim asm As Assembly = Assembly.LoadFrom(possiblePlugin)
Dim myType As System.Type = asm.GetType(asm.GetName.Name + ".Plugin")
Dim implementsIPlugin As Boolean = GetType(IPlugin).IsAssignableFrom(myType)
If implementsIPlugin Then
    Console.WriteLine(asm.GetName.Name + " is a valid plugin!")

    Dim plugin As IPlugin = CType(Activator.CreateInstance(myType), IPlugin)
    Console.WriteLine("{0}: {1}", plugin.Name, plugin.ActionName)
    plugin.Calculate(5, 4)
End If

Wrapping things up

Well, this was a quick and dirty look at implementing your own plugin architecture into your application. Please leave feedback or questions. I’d be happy to hear both!

Technorati Tags: VB.NET,Plugin,architecture

Hot-To: Model a Work Breakdown Structure with Project 2007 and Visio 2007

Stacy Vicknair — Mon, 12 Jan 2009 00:05:25 GMT

If you’re trying to make a WBS from your suite of 2007 applications, Microsoft Download Center has a Visio add-on that might save you some time.

To get a WBS pumped out quickly, just do the following:

Download and install Microsoft Office Visio 2007 WBS Modeler.
Open Visio, and start from the new WBS Modeler.
Open Project and open the project you want to make a WBS for.
In Visio, click WBS Modeler, then Import From Microsoft Office Project…

Click through a couple more settings and here you have it. An easy WBS, and best of all it is free! When I was looking around the best alternative looks like it will run you around $200.

Technorati Tags: Project,Visio,WBS

How-To: Enumerate the Internet Explorer Installed OpenSearch Engines

Stacy Vicknair — Thu, 27 Nov 2008 01:27:41 GMT

For my recent Launcher project, I was constructing a ribbon that would allow the user to search the web via their engines installed in Internet Explorer. The engines themselves are an XML document following the OpenSearch schema. For firefox, these xml documents just get stored locally. What does IE do with theirs?

Well, IE sticks them in the registry. Why? Maybe someone else can answer that. Here's a brief look at how to get the search engines out of the registry. The following snippets of code come from the launcher project. If you want to see how I abstracted the engines and the complete code, you can download it from Codeplex. If you want to critique the code or make suggestions on how I can code better, leave me a comment here. I'm not the best programmer and I'm starving to learn.

First off, lets give a simple answer to this post: How do I enumerate the IE search engines? The search engines are located in Software\Microsoft\Internet Explorer\SearchScopes, the rest of the task is just enumerating the keys and values to extract important information.

First off, I made a straightforward structure to represent my individual search engine:

Public Structure SearchEngine
    Private m_DisplayName As String
    Public Property DisplayName() As String
        Get
            Return m_DisplayName
        End Get
        Set(ByVal value As String)
            m_DisplayName = value
        End Set
    End Property

    Private m_SearchString As String
    Public Property SearchString() As String
        Get
            Return m_SearchString
        End Get
        Set(ByVal value As String)
            m_SearchString = value
        End Set
    End Property

    Private m_isDefault As Boolean
    Public Property isDefault() As Boolean
        Get
            Return m_isDefault
        End Get
        Set(ByVal value As Boolean)
            m_isDefault = value
        End Set
    End Property

    Public Overrides Function ToString() As String
        Return m_DisplayName.ToString
    End Function
End Structure

This structure just contains the display name, the search string and whether or not it is the default.

I fill a list of search engines as so:

Private Sub GatherEnginesFromRegistry()
    'Clear list
    m_engineList.Clear()

    Dim regKey As RegistryKey = Registry.CurrentUser.OpenSubKey("Software\Microsoft\Internet Explorer\SearchScopes", False)
    'Gather Default key
    Dim defaultKey As String = regKey.GetValue("DefaultScope")

    'Gather all search engines
    For Each subKey As String In regKey.GetSubKeyNames
        Dim engine As New SearchEngine
        Dim engineKey As RegistryKey = regKey.OpenSubKey(subKey)
        If engineKey.GetValue("") = String.Empty Then
            engine.DisplayName = engineKey.GetValue("DisplayName")
        Else
            engine.DisplayName = engineKey.GetValue("")
        End If
        engine.SearchString = engineKey.GetValue("URL")
        If (subKey = defaultKey) Then
            engine.isDefault = True
        Else
            engine.isDefault = False
        End If
        m_engineList.Add(engine)
        engineKey.Close()
    Next

    regKey.Close()
End Sub

Here you see regKey as a key to the SearchScopes subkey within CURRENT_USER. Within SearchScopes the DefaultScope value contains the subkey name for the default search engine.

After fetching the name of the default engine, I just iterate through eachsubKey and convert it into my structure, and add it to a generic list. The important values being DisplayName and URL. However, if the (Default) value for the subkey is specified, I take it instead of the DisplayName. Why? because LiveSearch does this oddity:

The DisplayName is a DLL call of sorts and the (Default) is the name? What's up with that? :\

And finally, to use the search within an application just replace the {searchTerms} in the URL with the appropriate URI formatted text and send it on its way via Process.Start!

Private Sub btnSearch_Click(ByVal sender As System.Object, ByVal e As Microsoft.Office.Tools.Ribbon.RibbonControlEventArgs) Handles btnSearch.Click
    Process.Start(searchURL.Replace("{searchTerms}", ConvertStringToURI(searchText)))
End Sub

Technorati Tags: How-To,IE Search Engine Enumeration

How to: Set up Google Analytics on your GeeksWithBlogs blog

Stacy Vicknair — Sat, 22 Nov 2008 00:58:08 GMT

If you haven't seen Google analytics before, you ought to know this: it rocks. You'll get great reports on everything from geographic location to browser to flash version (Why no Silverlight version, eh Google?) See example awesomeness here:

Obviously I've only recently set this up. However, since it is up and running and working great, I figured I'd show you how to get yours up and running as well.

Firstly, sign up for Google Analytics. Then afterwards, Google will provide a script to monitor the site usage. But if you can't access the head for your site, where do you put it? Good question. Almost million dollar.

So since there's only one question when it comes to Google Analytics and GWB, I figured I'd just throw out the answer.

Q. Where do I put the JavaScript thingy?

A. Put it in your news section. Google screams a tantrum that you've got to stick it in the <head> of your html, but the whole thing works out fine right in the news section (which you can edit in your GWB admin panel).

So my next question is, Does anyone know how to get Google Webmaster Tools working on GWB?

Technorati Tags: geekswithblogs,google analytics

Custom Code Snippets Series Part 3: XML Example

Stacy Vicknair — Wed, 05 Nov 2008 00:45:58 GMT

Hey guys,

Here we are, and I’m taking the time to finish up my first series at my new host geekswithblogs! For this part of the series we’ll be taking a look at a practical example of an XML snippet, namely the snippet to create snippets.

I’ve created my own version, but if you’ve toyed with XML snippets before you would know that Microsoft has already included a snippet snippet. This is a good alternative to the “Hard” way described in Part 1, but what if you want a little more of a custom feel to your snippet snippet?

Getting Started

This time around I’ve published the code on Codeplex, at the following address:

http://www.codeplex.com/wtfnextsnippetseries

You can download the premade snippet directly, and then we’ll be looking into the elements of the snippet briefly.

A look through the XML

This snippet is fairly straightforward, and many of the items you might recognize if you are familiar with snippets or have gone through the first part of this series. Our header section is straightforward, and we make good use of literals.

There is one literal that we need to note here: CDATAEND. There’s a bit of a quirk that requires a workaround when making an XML snippet, and that’s if we need to use a CDATA section within our snippet itself.

The problem is that a CDATA section cannot contain another CDATA section. As a result, making a snippet of another snippet becomes complicated. How do you do it? Simply put a literal in the CDATA of your snippet that represents the terminator for the internal CDATA in the snippet.

So, we see in the snippet itself this:

    <Snippet>
      <Code Language="$Language$">
        <![CDATA[$selected$$CDATAEND$
      </Code>
    </Snippet>

and we have the literal CDATAEND defined as this:

<Literal Editable="false">
  <ID>CDATAEND</ID>
  <Default>]]&gt;</Default>
</Literal>

The $selected$ is a placeholder for any selected text when we use the SurroundsWith datatype. This allows us to highlight some VB or whatever and when we insert the snippet it automatically knows we want the code selected to be surrounded by our snippet, and have the selection inserted at the $selected$ point.

Summary

So this concludes the brief look at snippets, and I want to tell you guys that I’ll appreciate any feedback. The “Hard” way isn’t really that bad, and all in all (if you’re like me) it gives you complete quick control over your snippet creation. The “Easy” way is an external application, and is designed with syntax highlighting for a language specific creation, so you won’t be popping out the XML or C# snippets from the VB snippet creator.

Please post comments if you have criticisms or anything to say, I’m looking forward to improving the quality of this blog and of myself, and feedback will help with both!

Technorati Tags: Custom Code Snippets Series,snippet,xml

Custom Code Snippets Series Part 2 of 3: The “Easy” Way

Stacy Vicknair — Mon, 20 Oct 2008 22:58:08 GMT

Here we are at part two of the Custom Code Snippet Series. In the previous part we covered how to make your own snippet by creating an XML .snippet file and adding to it the necessary content to get a custom snippet up and running.

This time around, we’re going to cover the “Easy” method of creating custom code snippets: through a GUI. Thankfully, the MSDN itself has a Code Snippet Editor for both Visual Basic 2005 and 2008 available at the following links. This tutorial will make use of the Visual Basic 2005 Code Snippet Editor.

To get the 2005 version:
http://msdn.microsoft.com/en-us/vbasic/ms789085.aspx

to get the 2008 version:
http://msdn.microsoft.com/en-us/vbasic/bb973770.aspx

So, after installing the Code Snippet Editor, we’re ready to get started.

Add the path to My Code Snippets

Right off the bat, you can tell we are going to have a small issue. Looking through the tree in the snippet editor does not show the custom code snippets! That’s alright, we’ll just add our path.

Right-click in the tree view area of the program and select Add Path…. Browse to the path we discussed for saving snippets in the previous part:My Documents > Visual Studio YYYY > Code Snippets > Language of Choice > My Code Snippets.

Now we can see our custom code snippets in the editor. If you’ve done the previous part in this series you should see the cmdWrite snippet show up in the tree under the My Code Snippets folder:

Create new snippet in My Code Snippets

Why do I stress putting the new snippets in our My Code Snippets folder? If you want a centralized location that is somewhat protected from other users of the computer, in your My Documents folder makes sense. You might even want to make your own location that you point Visual Studio to, that way you can implement version control to make sure changes benefit your code and rollback if they do not.

To create a new snippet, just right click the folder and select Add New Snippet. Name your snippet, today we’re going to make a simple For loop, so I’ll name this one ForLoop. Obviously, you’ll make snippets that matter more.

Once you create the snippet, double click on it. Here you’ll see a GUI representation of the XML document. Fairly straightforward.

To start, let’s fill in our info. Here’s what I put:

Now let’s put in our VB code into the editor at the top. Here’s what I put:

Dim count as integer = 0
Dim countMax as integer = 100

For count = 0 to countMax
    'Something to do
Next

Now we’ll transform this code into a dynamic snippet. I want count to be a choice for the variable name, so highlight count and on the Replacements tab at the bottom hit the yellow plus sign.

count will become surrounded by $ symbols, and become a decadent orange color. At the bottom, you’ll see that most information has been filled in for us. For type, we’ll leave it blank, and for tooltip, we’ll just describe the replacement. Now, do the same for countMax.

We’re practically done! Flip over to the Test tab and hit the big test button. Did it work okay? If so, we’re ready to find it in VS and start using it, just make sure to save your snippet!

Check it out in Visual Studio

Go ahead and close the Snippet Editor and open up a new console project in Visual Studio, VB of course.

If you’ve set up the same snippet as me, go ahead and type ForLoop? and hit Tab twice and you should see your new snippet come to life!

Technorati Tags: Custom Code Snippets Series,VB .NET,Tutorials

For those geeks that want decent looking <pre> code

Stacy Vicknair — Wed, 15 Oct 2008 01:48:51 GMT

I mashed together a variety of random web resources on how to make a decent pre tag for code and the output looks like this (ignore how incredibly bad this code is... I was testing SVN and making sporadic changes... Steve McConnell would strangle me):

Module Module1
    Sub Main()
        Console.BackgroundColor = ConsoleColor.DarkBlue
        Console.ForegroundColor = ConsoleColor.White
        Console.Clear()

        My.User.InitializeWithWindowsUser()

        Dim sw As New Stopwatch()
        sw.Start()

        Dim username As String = My.User.IsInRole(ApplicationServices.BuiltInRole.Administrator).ToString

        Console.WriteLine("User is admin: " & username & "!")
        sw.Stop()
        Console.WriteLine("Time: " & sw.Elapsed.ToString)
        Console.ReadLine()

        
    End Sub
End Module

There’s word wrap, and it’s at least differentiated from the rest of the post nicely IMO. the code is as follows:

pre {border: solid 1px #CCCCCC; 
 font-size: 1.3 em;   
 margin: 10px; 

 padding:10px; 

 background: #EEEEEE; 
 white-space: pre-wrap;  
 white-space: -moz-pre-wrap !important;

 white-space: -pre-wrap;

 white-space: -o-pre-wrap; 

 word-wrap: break-word;

}

Hope it helps some of you other code bloggers :)

Technorati Tags: Code,Pre,CSS,GWB