Doing Software Engineering research requires well thought out planning and validation approaches. Studying such topics, I have come across a couple of interesting papers. A summary of their most interesting points (for me) follows below.

Writing Good Software Engineering Research Papers
(Mary Shaw)

· A research paper should include a number of questions stating your contribution (question you answered, why the reader should care larger questions addressed), your new result (previous work , new knowledge, details) and why readers should believe you (evaluation standard/method, evidence connecting claim and result).

· Types of software engineering research questions include: method/means of development, method for analysis or evaluation, design/evaluation/analysis of a particular instance, generalization or characterization, feasibility study or exploration.

· Program committees look for a clear statement on the specific problem you solved and how it will scale. Tell your answer and why it matters.

· Quantitative models have a better success rate (as being recognized by the scientific community) when compared to quantitative models. Tools and notations are well represented, usually as auxiliary results in combination with a procedure or technique.

· Types of software engineering research results include: procedure or technique (should be really a procedure, not advice or guidelines), qualitative or descriptive model (e.g., a taxonomy, a framework, well-organized interesting observations), empirical model, analytic model, tool or notation, specific solution/prototype/answer/judgment, report.

· You should explain your result in such a way that someone else could use your ideas. Precisely tell what’s new: the idea, the application of the idea, the implementation, the analysis or what?

· For tools: was the contribution the technique that is embedded in the tool, the effectiveness of the tool when compared to others, the applicability of the tool or what? Does the tool simply support the main contribution, or is itself a principal contribution? Can the idea be applied without the tool?

· Explain how you build atop previous work, otherwise you may damage credibility if the committee can’t tell whether you know about related work.

· A paper that simply reports on using numerous elements together is not enough, even if it’s well engineered. There must be an idea or lesson or model readers can take and apply to other situation.

· Types of software engineering validations include: analysis, evaluation, experience, example, persuasion, blatant assertion.

· Analysis, actual experience in the field and good use of realistic examples tend to be the most effective ways of showing why your result should be believed. Careful narrative, qualitative analysis can also work.

· Pilot studies that lay the groundwork for controlled experiments are often publishable by themselves.

· If you claim to improve on prior art, compare your result objectively to prior art.

· If you performed a controlled experiment, explain the experimental design: hypothesis, treatment, what is being controlled, collected data, how it was analyzed, significance of results, confounding factor, whether the conclusions follows rigorously from the experimental data.

· For PhD thesis validation section: global statements (“always, fully”) often require analytic validation, qualified statements (“X% of improvement”) can often be validated by evaluation or careful examination of experience existential statements (“we found an instance of”) can sometimes be validated by a single positive example. Students can restate thesis claims to reflect more precisely what the theses actually achieve.

· Suggested abstract structure: two or three sentences about the current state of the art identifying a problem, one or two sentences on the contribution, one or two sentences about the specific result and its main idea, one sentence about how the result is demonstrated or defended.

Selecting Empirical Methods for Software Engineering Research
(Steve Easterbrook, Janice Singer, Margaret-Anne Storey, Daniela Damian)

· Five classes of research methods are considered to be the most relevant to software engineering: controlled experiments, case studies, survey research, ethnographies and action research. The choice of methods depends upon the theoretical position (stance) of the researcher, access to resources and how closely the method aligns with the questions that have been posed.

· The selection of methods for a given research project depends on many local contingencies, including available resources, access to subjects, opportunity to control the variables of interest and the skills of the researcher.

· One of the first steps in choosing an appropriate research method is to clarify the research question.

· The most obvious question is not the best choice for a starting point.

· Defining the precise meaning of terms is a crucial part of empirical research and is closely tied with the idea of developing or selecting an appropriate theory.

· In the early stages of a research program, we usually need to ask exploratory questions to understand the phenomena: existence questions (Does X exist?), description and classification questions (What is X like? What is it for? How to categorize/measure it?), descriptive-comparative questions (How does X differ from Y?)

· Then we need to ask base-rate questions about the normal patterns of occurrence of the phenomena: frequency and distribution questions (How often does X happen? What is the average amount?), descriptive-process questions (How does X normally occur? What is the process by which it happens? What is its sequence of events?), relationship questions (Are X and Y related?)

· Then we should ask causality questions and, finally, design questions (How to achieve X?)

· Theories support the process of empirical induction because an individual study can never offer conclusive results. Each study adds more evidence for or against the prepositions of the theory. Without the theory, we have no way of making sense of the accumulation of empirical results.

· A controlled experiment is an investigation of a testable hypothesis where one or more independent variables are manipulated to measure their effect on one or more dependent variables. Each combination of variables is a treatment (configuration).

· A precondition of conducting an experiment is a clear hypothesis. The theory also helps to decide who the subjects are and what the tasks should be.

· A case study is something very different than just worked example. It can be exploratory (initial investigation to derive hypothesis and build theories) or confirmatory (to test existing theories).

· Case study research is most appropriate for cases where the reductionism of controlled experiments is inappropriate.

· The major weakness of case studies is that the data collection and analysis is more open to interpretation and researcher bias. For this reason, an explicit framework is needed for selecting cases and collecting data.

· A survey research is used to identify the characteristics of a broad population of individuals. It can be done through questionnaires for data collection, structured interviews or data logging techniques.

· Sampling bias causes problems in generalizing the survey results, because the respondents to the survey may not be representative of the target population. Low response rates increase the risk of bias.

· Ethnography is a form of research focusing on the sociology of meaning through field observation. The goal is to study a community of people to understand how members of that community make sense of their social interactions.

· In action research, the researchers attempt to solve a real-world problem while simultaneously studying the experience of solving the problem. There’s lots of debate on the validity of action research as an empirical method.

· Mixed methods research recognizes all methods have limitations and the weaknesses of one method can be compensated for by the strengths in other methods.

· Criteria for validity (for positivists/reductionists) include: construct validity (whether theoretical constructs are interpreted and measured correctly), internal validity (whether the results really follow from the data), external validity (whether claims for the generality of the results are justified) and reliability (whether the study yields the same results if other researchers replicate it).

· In reporting positivist empirical studies, it is important to include a section on threats to validity, in which potential weaknesses in the study design as well as attempts to mitigate these threats are discussed in terms of the criteria above.

· Strengths for improving validity (from a constructivist point of view) include: triangulation (use different sources and methods), member checking, rich/thick descriptions, clarify bias, report discrepant information, prolonged contact with participants, peer debriefing, external auditor.

· It is important to document the original planned research protocol, and all subsequent deviations to it, to allow other researchers to understand the study design, interpret the search results and replicate the study.

· Methods that are primarily qualitative include ethnography, case study and action research. Quantitative include controlled experiments and survey research.

· With regard to research and validation, it is important to plan ahead, for smooth analysis and interpretation of results.

Qualitative Methods in Empirical Studies of Software Engineering
(Carolyn B. Seaman)

· In software engineering, the blend of technical and human behavioral aspects lends itself to combining qualitative and quantitative methods in order to take advantage of the strengths of both.

· Advantage of qualitative methods: they force the researched to delve into the complexity of the problem rather than abstract it away. The results are richer but labor-intensive.

· Participant observation and interviews are one of the most common data collection methods. Interviews can be structured or unstructured (in the latter case, interviewees are the source of both questions and answers).

· “Coding” is the process of extracting vales for quantitative variables from qualitative data in order to perform statistical/quantitative analysis. This approach is especially difficult when the concept to be coded is subjective in nature, when the terminology used to describe it varies and is difficult to interpret, and when different data sources disagree.

· The distinction between qualitative and quantitative data has to do with how the information represented, not whether it is subjective or objective.

· The “constant comparison methods” is a data analysis method that tags qualitative data with terms, and then groups related information together to look for relationships.

· Cross-case Analysis a data analysis method that cross-compiles data.

· A hypothesis cannot be proven; it can only be supported or refuted. This is true independent from the usage of qualitative or quantitative methods.

· One of the most important ways to help confirm a qualitatively generated proposition is to ensure the validity of the methods used to generate it. Some validation concerns are: representativeness, possibility of researcher effects on the study, triangulation, anomalies in the data, negative case analysis, replication and member checking.

· Researchers have a marketing role as well, trying to promote the importance and usefulness of the empirical study in software engineering.

· Empirical studies can be classified in: blocked subproject-project (multiple projects and subjects to reduce bias), replicated project study (same project, multiple subjects), multiproject variation (single subject, projects before/after some treatment), single project study (single project, single subject, similar to a case study, possibly compared to some organization baseline).

BR,
-- AFurtado

These are the projects of individuals/companies who presented in the Microsoft's Development Tools Ecosystem Summit 2009 how they are extending Visual Studio:

• Atmel - IDEs for AVR microcontrollers
• Oleg Synch - T4 Toolbox: a set of ready-to-use code generation templates and supporting tools
• Collabnet - Subversion integration
• ComponentOne - enriched VS/SharePoint components, such as a spell-checker for VS and a Silverlight XAP file optimizer
• GamCom - Talmia: process workflow for Team System
• Intel - Parallel Studio: enhances Visual Studio for parallelism (C++)
• JNBridge - .NET / Java interoperability plug-in (for VS and Eclipse)
• Micro Focus - DevPartner Studio integration into VS2010
• Odin Technology - Coded UI test generation from Excel spreadsheets (cool!)
• OpenMake Software - extends build support for environments with multiple versions of .NET (VS 6.0 through 2010)
• PreEmptive - Runtime Intelligence: code instrumentation for finding different kinds of hotspots (such as code heavily used but poorly tested)

I didn't speak this time, but you are always invited to try out my SharpLudus project which extends VS by combining model-driven development with XNA, hopefully enabling a more productive game development process.

BR,
-- AFurtado

• Singletons are objects and it might be more intuitive to deal with them for state manipulation rather than through the use of static fields in static classes.
• In the same line, you can't pass a static class as parameter, while no such limitation exists for the Singleton object.
• Static classes cannot implement interfaces. The class that defines the Singleton can.
• The global static class can be loaded too early, consuming valuable application resources, while the Singleton supports lazy allocation where an instance is created only as needed.
• Static classes do not benefit from default serialization mechanisms.

BR,
-- AFurtado

The panel “DSLs: The Good, the Bad and the Ugly” that happened at the OOPSLA 2008 conference discussed the advantages, disadvantages and challenges from the industry and academia on the use of domain-specific languages (DSLs).

While the advantages brought by the panelists were somewhat expected (more productivity, more abstraction, etc.), the disadvantages and challenges were quite interesting and not that obvious. Here you can find a compilation of them:

• Composition (integration) among multiple DSLs (this was mentioned several times).
• Interoperability with mainstream languages.
• Key challenge: understanding the domain and defining its scope. Designing a DSL requires strong customer-driven effort. DSLs targeted at too broad domains are ineffective.
• Common error: DSLs based on solution domain (code), instead of the problem domain, therefore becoming low level languages.
• Lack of domain analysis tools and processes.
• Lack of tool support in general. Knowledge in DSL engineering was not transferred to tools yet. The engineering knowledge is out there, many times ad hoc, but it still had not come together.
• Tools are immature for iterative development and use of DSLs.
• A new language implies at reluctant customers. Although they are generally able to understand the return of investment after the using the language for a while, lowering the entry barrier is still a challenge.
• Users cannot benefit from a DSL if it has poor documentation or they are not properly trained.
• Planning and assessing the return on investment (cost-benefit analysis) is hard to perform (some panelists argued that a DSL with a generator pays off if used more than once).
• Lack of systematic approach to replicate processes related to DSLs design and implementation.
• Manually edition of generated code should be avoided. [IMHO, extensibility through other means such as partial classes, inheritance, dependency injection, etc. are still welcome]
• Programming concepts (conditional branches, loops, etc.) might be expected by the DSL users but may not make sense to the domain.
• Backward compatibility: it is hard to evolve the language when model (specs) created with it are already in place.
• Internal DSLs have a couple of additional challenges: (1) users may move out from the DSL abstractions to the host language and (2) compilers for internal DSLs have to process host language code.

BR,
-- AFurtado

For a Visual Studio package developer, one of the most frustrating error messages is the Package Load Failure, that tells that your VS Package was unable to load in the IDE.

For some of my projects, including the FeatureModelDSL, I was able to notice that the root cause of such an error was the eventual corruption of the windows.prf file under C:\Documents and Settings\username\Application Data\Microsoft\VisualStudio\9.0\. Deleting this file (so that it can be automatically re-generated by Visual Studio) makes the package work again.

I’m suspecting a custom toolwindow I have created for such a package might be causing the corruption. To be investigated…

BR,
-- AFurtado

Suppose you have a domain concept (class) with a Namespace property, which will be used in code generation. It would be cool if such a property was automatically filled with the value of the project root namespace when the model (diagram) is loaded for the first time, wouldn’t it?

So how to handle the model Load event? The trick is to add a partial <DslName>DocData class to your project, then override the OnDocumentLoaded method. From there, you can get the this.RootElement property and cast it to your root model element.

For instance, that’s exactly how I’m doing with my GameDefinitionDSL (yet to be released):

internal partial class GameDefinitionDSLDocData
{
    protected override void OnDocumentLoaded(EventArgs e)
    {
        base.OnDocumentLoaded(e);
        Game game = (this.RootElement as Game);
        // if game.Namespace is null or empty, update it with the project root namespace
    }
}

This approach follows the “Convention over Configuration” design paradigm, setting an appropriate default value for the game namespace, that can still be modified by the user later.

BR,
-- AFurtado

Have a string and need to check if it’s a valid C# identifier (to use as a method name in code generation, for example)? Try this code:

Microsoft.CSharp.CSharpCodeProvider.CreateProvider("C#").IsValidIdentifier(myString);

I recommend checking other useful methods of the CodeDomProvider class as well.

BR,
-- AFurtado

The Sandcastle Help File Builder is a great tool for creating .html and .chm help files from .NET XML comments without demanding the complexity of SandCastle. I believe this tool is a better option than DocProject, which requires itself to be added to the current VS solution and seems to be buggy with regard to documenting .exe assemblies

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation.

English - Portuguese

---

O Sandcastle Help File Builder é uma ótima ferramenta para criar arquivos de ajuda .html e .chm a partir de comentários XML do .NET sem exigir a complexidade do Sandcastle. Considero que esta ferramenta é uma opção melhor do que DocProject, que exige ser adicionada à solução corrente do VS e parece ter bugs em relação à documentação assemblies .exe

[]s
--AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation.

---

Some of the foundations of the Microsoft Software Factories Initiative are, among others, domain-specific languages and guidance automation. This last foundation refers to automating common tasks during the development of a product that actually belongs to a family of products (or a software product line).

Let's take game development as an example: in every game, developers should implement game screens and define game entities (main characters, enemies, etc.) following some pre-defined patterns and/or consuming some pre-defined game engines and frameworks in general. In this context, guidance automation intends to automate such tasks by enabling developers to launch them from entry points in the development environment and have all the menial/routine work to be done by the IDE.

In this previous post, I've presented GAT, the Guidance Automation Toolkit, as Microsoft's approach to provide guidance automation. After the PDC 2008, in Los Angeles, Microsoft has introduced to the world the evolution of GAT, which is called Microsoft Blueprints.

From the Blueprints website: "Microsoft Blueprints [...] help you codify conventions, automate tasks, ramp up quickly on new technologies and requirements, and package successful designs and implementations, so that you can use them again. [...] A Blueprint is an accelerator for a specific type of software deliverable like a web service, a rich client, or a mobile application [or games!]. It supplies a process, plus resources like guidelines, patterns, templates, libraries, and tools, to help you implement the process. It’s an SDK for a problem, not a product."

You can download the October CTP version of Microsoft Blueprints and samples from its codeplex website. This post will show my own experience with the technology and hopefully will help you to ramp-up on it.

So after installing Blueprints Oct CTP on you system, you can now notice a new Blueprints Manager entry from the tools menu. That's your starting point.

Clicking there leads you to a dialog which shows the currently installed Blueprints (software factories) in your system.

When you click on the Update button, you can add more Blueprints, either from a file or from a feed. This last option is especially cool: you can subscribe to the Blueprints feeds of specific companies, from Microsoft to "AFurtado Game Labs", to ensure you always have the latest versions of their Blueprints.

So let's get started. To create a new Blueprint (factory), you need to launch... a Blueprint! Yes, there is a Blueprints factory that helps you to create your own Blueprints. In other words, you already have automated guidance for creating your own automated guidance. You can think of the Microsoft Blueprints Factory as a meta-factory that helps you to create your own factories. So, the same way that DSL Tools were built using DSL Tools, Blueprints are also built using Blueprints. Don't you love the meta-meta world?

Enough talk. In this tutorial, we'll create the foundations of a factory for Adventure Games. So let's select Microsoft Blueprints Factory 2.0 from the Blueprints Manager window (picture above) and then click on Unfold, which is just a fancy word for creating and adding solutions, projects and projects items based on guidance automation rules.

VS then opens the "New Project" dialog. I'll select the an empty solution so that my Blueprint projects can be unfolded in a clean environment.

Next, we need to provide a project name for the Blueprint. Let me call it "AdventureGame".

OK, now the Blueprint Editor pops up, and there we can provide more details about our factory. Let me provide some initial information in the Configuration tab and press OK.

In the Configuration tab, you can provide some information that factory consumers (product developers) will use when unfolding your Blueprint. You can even use any specific Visual Studio project template you have exported to be the initial project that appears as a result of the Blueprint unfolding. Having a XNA Studio game project would make a perfect sense for us here, but let me keep this option as "auto-generated" just for the sake of simplicity.

When you press OK, you can see that a solution and a project were created (unfolded) for you, and now the Blueprint workflow appears.

The workflow is one of the hearts of the Blueprints approach. It tells the steps that factory consumers should execute in order to implement finish their product. Two side-notes here:

• I've heard that it will be possible to design the workflow using WF (Windows Workflow Foundation). That would support lots of interesting things such as branches, conditions, loops, etc. However, it seems that, in this current CTP, workflows are still a linear sequence of steps.
• I foresee many opportunities here to bind workflow steps with actual "development recipes" (or tasks, or whatever you want to call it). I'm not sure which are the plans on that front but it is definitively something I'll suggest.

So just to be clear, the workflow of the picture above is NOT the workflow your factory users will see. That workflow is for YOU, the factory/Blueprint creator, to follow. Very shortly, I'll show you how to design our own AdventureGame factory workflow.

So I encourage you to read the workflow steps, since they provide lots of prescriptive guidance on how to carry on your factory deveopment and create your own factory workflow, menus, commands, etc. I won't repeat what is written there but I will carry those actions in the context of our adventure games factory.

So for this exercise, let's suppose we want to automate the way a game developer adds adventure game artifacts to the game. Examples of such artifacts are books, potions, weapons and any other item that players can grab and use in the game.

Normally, game developers would have to add a class to the solution, make it to inherit the Artifact base class, add some properties and fields to describe to artifact and so on. In the real world, lots of other (more complex) things would have to be done, including complying to game engines architecture, other patterns and implementation best practices. So just to recap our main goal here, the question to be answered is: how can we automate, for the game developer, the task of adding a game artifact?

First, let's change our adventure game workflow. Right-click your Blueprint project and then select Blueprints -> Edit Workflow.

The Basic Workflow Editor window opens, where you can specify the steps required by the adventure game factory for game developers to create adventure games. As a best practice, the first step should be an overview of the remaining steps. So click in the first step (Overview) and then in Open Details in Word.

MS Word opens and now you can change the details that AdventureGameBlueprint consumers will see in their own Workflow window. Do your changes and save them.

Edit the other steps or add new ones at will. I'll just add one additional step which is "Add Game Artifact". Notice you can either provide help files (.mht, .htm, .html, .doc and .docx files) to detail a step, or a URL link.

Everything looks great so far, so let's test it. Compile your solution then launch the Blueprints Manager again from the Tools menu:

Sounds nice: our factory is already listed in the Blueprints manager and is ready to use. Let's click on unfold and check what happens.

The dialog above asks us to enter the name of our factory instance, i.e., product. As you can see, the initial experience for consuming Blueprints is similar to the one for authoring Blueprints. Let's enter MyFirstAdventureGame and click OK. As you can see, a new project called MyFirstAdventureGame is there and the Workflow window shows the steps we have just specified for this factory (Overview and Add Game Artifact)!

While having a product project right there for us to test and debug, in the real world, factory users (game developers) would unfold this Blueprint in an empty environment and, as soon as the unfolding is complete, they would have a XNA project ready, empowered by guidance automation to help them to complete their game development tasks.

If you right-click the MyFirstAdventureGame project, you can see a Blueprints menu is there, but it only contains the Workflow and Feedback options.

So let's implement our final task here, which is to add a new menu item to add a new game artifact to the game, collect some information from the game developer and then add a class to our project based on such info.

Notice: if you want, you can do something much simpler than that, such as displaying a "Hello World" message box. Case you want to do that, just ignore the steps below to create a Windows Form, a T4 generation script and code to interact with the Visual Studio IDE. You'll only need to handle the command from the generated ExtensionClass as I explain below.

A very easy way to implement commands in our factory is to right click the main factory project then select BluePrints -> Add Extension. Then you should enter a name for such kind of "extension project" that will help us to implement ArcadeGameBlueprint commands. (I'll show you how to bind commands to menu items very shortly.)

This will (guess what?) unfold a new project in our Blueprint solution, containing the foundations for we to add a new factory command.

So since we'll collect information from the game developer to create the game artifact, let's create a new Windows Form and add it to the AdventureGameExtensions project. Please notice: I'm going to create such a form in a different (temporary) project and only then add it to the AdventureGameExtensions project, because it seems that a bug in the Blueprints Oct CTP doesn't allow you to properly edit Windows Forms.

So here you have my form:

And some code-behind just to expose the values entered by the game developer:

Then we should copy the form to the AdventureGameExtensions project and add there a reference to System.Windows.Forms and System.Drawing.

Ok, now we need just a couple of things. First of all, we need to generate, in memory, the contents of the new class that will be added to the game developer project. For that, we can benefit from Visual Studio's T4 technology. T4 is the Text Templating Transformation Toolkit, a text transformation technology Microsoft created to make code generation easier.

If you check the AdventureGameExtensions project, there is a MyTemplate.t4 file there ready for us to implement our code generation scripts. Let's rename that to NewArtifact.t4 and enter the following generation script:

Even if you've never seen a T4 script before, it is pretty simple to understand its purpose here: I'm receiving an ArtifactName and an ArtifactDescription as parameters, while using them to name my class and to create two strings that will be returned from two class properties. The generated artifact class inherits from the fictitious class MyGameEngine.Artifact class just to illustrate the idea in the real world.

Now let's go to the ExtensionClass and implement the behavior that will read the input from the game development using our form, call the T4 transformation using our script, and finally interact with Visual Studio development environment (DTE object) to add a new file to the current solution. The code follows below (you'll need to add a reference to the EnvDTE assembly to make it compile):

First, we handle the switch case for the AddNewArtifact command. This will be our hook from the main AdventureGameBlueprint project (that's the final step which will be shown very shortly). Then we instantiate the form to get user input and show it. Then, we create some T4 parameters and use the T4Transform method of a T4Helper object to call the code generation. Finally, we save the generated stuff into a temporary file and add it to Visual Studio using the DTE property of the context object, which we receive in this method.

Now we need to bind a menu item to the command implementation we have just provided. To do that, right-click your AdventureGame project -> Blueprints -> Edit Configuration. In the commands tab, add a new command called "AddNewArtifact" pointing it to the AdventureGame.ExtensionClass.dll and its AdventureGameExtensions.ExtensionClass class where we implemented the command. That is shown below:

Then you just need to create a menu entry in the Menu tab, pointing to the command, as shown below.

"ThisProject" tells that the command will be available from the adventure game project, but you could have specified other target elements in the Solution Explorer for this command to appear (such as a folder with a given name or a file with a given extension, for example).

Finally, add the NewArtifact.t4 file to the content folder of the AdventureGame project and you'll be ready to go.

Now let's test it! Compile your project, open a new instance of Visual Studio and unfold an AdventureGameBlueprint blueprint. Right-click you solution and notice that the Add New Artifact... menu will be there!

Clicking in this menu entry will launch our form to collect game developer information, as expected:

And, finally, after entering the info and pressing OK, VS will unfold our code generation script and add a new class for that game artifact to our project.

Sweet, isn't it? Now imagine that, if instead of adding an artifact class to our project based on user input, we had a much more complex task required to be executed many many times by game developers. Can you imagine how much development time things like Blueprints, DSL Tools and code generation technolgies can save in such scenarios? Me too!

You can download the source code here. Hope to keep bringing interesting software factories/automation content often.

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation.

As some of the Visual Studio Extensibility Developer Conference (VSX DevCon) 2008 screencasts are getting published, here you have the (quick) presentation of my SharpLudus PhD project, which happened in the How do I extend Visual Studio? session:

Converting 200 pages of research in a 4 minute presentation is indeed a challenge!

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

Dado que alguns screencasts da Visual Studio Extensibility Developer Conferência (VSX DevCon) 2008 foram publicados, aqui você tem a apresentação (rápida) do meu projecto de doutorado, o SharpLudus, que aconteceu na sessão How do I extend Visual Studio:

 

Converter 200 páginas de pesquisa em 4 minutos de apresentação é um verdadeiro um desafio!

[]s
-- AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation.

---

For those interested in creating feature model diagrams, I'm pleased to announce the first release of my implementation of the FeatureModelDSL: http://www.codeplex.com/FeatureModelDSL.

The original design of the language was proposed by Gunther Lenz and Christoph Wienands in the Practical Software Factories in .NET book. My version extends the idea to support Visual Studio 2008 and provides the following features:

• Feature model modeling experience supported by an integrated Visual Studio experience, including visual designer, Toolbox and Properties Window.
• Feature model validation through Errors List toolbar.
• Cross-diagram navigation.
• HTML report automatically generated from feature model diagram.
• Export feature model diagram to .png file.

Check a screenshot:

Feedback is welcome. The project is open-source, so any contributions are even more welcome.

Thanks,
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

 

Para os interessados na criação de feature models, acabo de publicar a FeatureModelDSL, linguagem visual integrada ao Visual Studio para a criação de feature models: http://www.codeplex.com/FeatureModelDSL

O design original dessa DSL foi proposto por Gunther Lenz e Christoph Wienands no livro Practical Software Factories in .NET. Minha versão estende a ideia com suporte do Visual Studio 2008 e fornece os seguintes recursos:

• Experiência de modelagem integrada ao Visual Studio (designer visual, Properties Window, Toolbox, etc.);
• Validação semântica dos diagramas modelados através da Error List do VS;
• Navegação entre modelos de uma mesma solução;
• Geração automática de relatórios HTML a partir dos modelos;
• Exportação do diagrama modelado para .png.

Confira um screenshot:

 

Feedback é muito bem-vindo. O projeto é open-source, portanto qualquer colaboração é mais bem-vinda ainda!

Obrigado,
--AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation.

---

For those who are not aware about Microsoft's Olso Project yet, check it here and here.

Oslo is supposed to be Microsoft's new platform for model-driven development, based on executable (live) models. It encompasses a tool (to manipulate models), a language (to define textual domain-specific languages - DSLs) and a repository (to store models). The whole picture is still not clear to me, especially how that fits into previous modeling initiatives such as the Microsoft DSL Tools. hope to find it out soon.

One interesting thing I was able to check at PreDC was Oslo's M language, aimed at the creation of textual DSLs. Basically you declaratively define a DSL using M and a compiler for that DSL is generated for you. You can then invoke that compiler, even programmatically from a C# program, to process an input text and get, as result, an instance of the domain object model.

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

Para aqueles que ainda não conhecem o Projeto Olso da Microsoft, chequem aqui e aqui.

Oslo é supostamente a nova plataforma nova da Microsoft para a desenvolvimento guiado por modelos, com base em modelos executáveis ("vivos"). O projeto engloba um ferramenta (para manipular modelos), uma linguagem (para definir linguagens específicas de domínio textuais - DSLs) e um repositório (para armazenar modelos). A fotografia inteira é ainda não está clara para mim, especialmente como isso se encaixa em iniciativas anteriores de modelagem, como o Microsoft DSL Tools. Espero descobrir em breve.

Uma coisa interessante que tive a oportunidade de verificar no PreDC foi a linguagem M do Oslo, que visa a criação de DSLs textuais. Basicamente, você define a DSL declarativamente e ele lhe gera um compilador para essa DSL. Esse compilador pode ser invocado (por um código C# programaticamente, por exemplo) para processar um texto de input e se obter como resposta uma instância do object model do domínio.

[] s
--AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation.

---

Today at PreDC (a preliminar version of Microsoft's PDC, where presenters can rehearse their stuff) I was introduced to MEF, the Managed Extensibility Framework.

If you've been reading this blog for a while, you may have noticed that almost everytime I post about extensibility, that's related to Visual Studio. MEF, on the other hand, is a more generic solution for providing extensibility to any .NET-based application.

Its essence is to streamline the process of component retrieval and discoverability by means of adding well-defined C# attributes to classes. As always, let me give an (high-level) example in the game development universe:

• Suppose a class responsible for managing the graphics elements of a game uses a C# attribute to tell "I'm interested in any component that implements a Heads-Up Display (HUD). If such components are available, I'll be able to ask them to be drawn on the screen, position them on the screen and make them to interact with game properties".
• A game control which implements radars, similar to the one used by the game Rally-X (check picture below) uses C# attributes to say "I implement a HUD. If anyone consumes me I'll be able to draw a radar on the screen according to the game entities' position".

• Other game control says "I also implement a HUD. If anyone consumes me I'm able to show a timer in the screen."
• The beauty is that those things don't need to be compiled together to interact with each other. Tomorrow, I can just copy to my game folder a .NET assembly (.dll) containing the implementation of another component that offers a HUD (e.g., a "progress bar" HUD) and, the next time I run the game, it will appear as well.

Sounds powerful and easy. And it really seems to be. I believe lots of Microsoft products will follow this direction in order to provide extensibility. Check the MEF website for more.

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

Hoje no PreDC (uma versão preliminar doa Microsoft PDC, onde os apresentadores podem ensaiar suas apresentações) fui introduzido ao MEF, o Managed Extensibility Framework.

Se você tiver sido lendo este blog por um tempo, talvez tenha notado que quase sempre que me refireo acerca de extensibilidade, estou falando do Visual Studio. O MEF, por outro lado, é uma solução mais genérica para fornecer extensibilidade para qualquer aplicativo baseado em .NET.

Sua essência é simplificar o processo de recuperação de componente e detectabilidade por meio de adicionar atributos de C# bem definidos a classes. Como sempre, permitam-me dar um exemplo (em alto nível) no universo de desenvolvimento de jogos:

• Suponha que uma classe responsável pela gerência dos elementos de gráficos de um jogo usa um atributo de C# para dizer "Estou interessado em qualquer componente que implementa um Heads-Up Display (HUD). Se esses componentes estiverem disponíveis, vou ser capaz de lhes pedir que sejam desenhados na tela, posicioná-los na tela e fazê-los interagir com propriedades do jogo".
• Um game control que implementa radares, semelhante ao utilizado pelo jogo Rally-X (veja imagem abaixo) usa atributos de C# para dizer "Eu implemento um HUD. Se alguém me consomir, sou capaz de desenhar um radar na tela de acordo com a posição das entidades do jogo".

• Diz de outro controle de jogo: "Eu também implemento um HUD. Se alguém me consumir sou capaz de demonstrar um timer na tela."
• A beleza aqui é que essas coisas não precisam ser compiladas em conjunto para interagir mutuamente. Amanhã, posso apenas copiar para minha pasta jogo um assembly .NET (.dll) contendo a implementação de outro componente que oferece um HUD (por exemplo, um HUD de barra de progresso) e, na próxima vez que executar o jogo, ele será exibido.

Isso aparenta ser poderoso e fácil. E realmente parece ser. Imagino que vários produtos Microsoft seguirão nesse sentido para fornecer extensibilidade. Verifique o site do MEF para obter mais informações.

[]
--AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation.

---

The call for the second RiSS (RiSE Summer School on Software Product Lines) follows below. Such an international event happens in Recife, my hometown, and it's a great opportunity for all those interested in software engineering. I was there last year and it was great.

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

A chamada do segundo RiSS (RiSE Summer School on Software Product Lines) segue abaixo. Tal evento internacional acontece em Recife, minha cidade natal, e é uma grande oportunidade para todos os interessados em engenharia de software. Estava lá no ano passado e foi uma ótima experiência.

[]s
--AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation

---

In this summer (November 27-29) will occur the most expected school, the Second RiSS - RiSE Summer School on Software Product Lines (http://riss.rise.com.br/). You will have the unique chance to learn about Software Product Lines - a software development paradigm which improves you productivity, reduce your costs and allow to you and your company accelerate the time-to-market - with the main subjects in the field. Names such as Klaus Schmid, from University of Hildesheim, Germany; Kyo C. Kang, from Pohang University of Science and Technology (POSTECH), Korea; Paul Clements, from Software Engineering Institute, US; Rob van Ommering, from Philips Research, the Netherlands; and, Michalis Anastasopoulos, from Fraunhofer Institute for Experimental Software Engineering (IESE), Germany.

Besides, this year we will also have the First Workshop on Software Reuse Efforts (WSRE), which is addressed to discuss practical issues of software reuse in industry, new trends in software product lines and, mainly, learn more and more about reuse and its problems and solutions with real experiences.

Besides all technological characteristics that surround the school and its realization in Recife - Pernambuco, it is worth to stand out the advantaged that nature brought to Recife with sunny days,  several  beaches (Boa Viagem, Maracaípe, Porto de Galinhas), delicious culinary (crab, shrimp, goat), the human heat of the people from Pernambuco, culture (carnival, frevo and maracatu) and one of the most animated technological people from the country. It will be a pleasure to receive you for RiSS 2008.

You better hurry up, because the school is limited to 100 participants, and there is less than 60 registrations available.

Welcome all of you!!!

In short, components are way cool. They encapsulate features, allowing them to be reused by exposing well-defined interfaces. They are key to provide automation and realize the vision of software factories.

For example, lots of XNA games require the user to enter some sort of text information. Isn't it cool that you can easily use a XNA Text Entry Component to add such a feature to your game, without having to implement it from scratch and allowing a reusable, consistent behavior across games?

In a previous post, I've provided some highlights about the discussion the Software Engineering Radio had about plug-ins. This time, I'd like to share some highlights regarding their episode about components.

• "Component" is an overloaded software engineering term. A reasonable definition says that a component is a piece of software that can be used and deployed in an independent way.
• In a UI context, components are usually composed by the following elements: classes + properties + events.
• The basic idea of components is reusability. Components are minimaly redundant and maximally composed. The LEGO analogy fits well here.

• Component metadata is key to components, so that environments (containers) can read component info and compose them with other components.
• Components should not have any implicit dependency on the environment to run. It should be know in advance (i.e., compile/design time) if a component works in an environment or not.
• Component modeling features presented by UML are limited and not very useful.
• Components can be stateless or stateful.
• The component marketplace vision (component-based development) has not yet been fully realized.
• Components are to architectures what classes are to programming languages. They are the smallest architectural relevant building blocks; they are the foundations of architecture.
• Components are composed by having their instances to be interconnected to other components instances.
• From the top-down approach, components could be identified/selected and then mapped by tools to specific technologies.
• Components are not necessarily related to object-orientation.
• Components are different from component instances. But in some systems in which there is only one instance of a given component, this discussion becomes needless.
• Component metadata should minimally include the interfaces and services it provides and requires.
• Component versioning is always a concern: will the new component version crash in an old environment? Ideally new versions should present compatibility.
• Ideally, components should also allow the envornment to parameterize them.
• Component roles can be implemented by component ports.

• Naming services allow components to proper communicate.
• Containers manage component resources, lifecycle and access to resources.
• SOA x components: components can be seen as an implementation of services, which sometimes are more concerned with providing the interfaces. The authors of the podcast say that SOA is a hype, but to that I particularly disagree.

[]s
-- AFurtado
The statements or testimonies I offer in this post represent my own personal views.

English - Portuguese

---

Indo direto ao ponto, componentes são extremamente legais. Eles encapsulam funcionalidades, permitindo-as serem reutilizadas através de interfaces bem definidas. Eles são essenciais para fornecer automação e concretizar a visão de fábricas de software.

Por exemplo, vários jogos XNA exigem que o usuário insira algum tipo de entrada de texto. Não é interessante o fato de que você pode facilmente usar um XNA Text Entry Component para adicionar tal recurso ao jogo, sem ter que implementá-lo a partir do zero e permitindo um comportamento reutilizável, consistente em jogos?

Em uma postagem anterior, forneci alguns destaques sobre a discussão que a Software Engineering Radio teve sobre plug-ins. Nesse momento, gostaria de compartilhar alguns destaques no que diz respeito à seu episódio sobre componentes.

• "Componente" é um termo de engenharia de software sobrecarregado. Uma definição razoável afirma que um componente é uma peça de software que pode ser utilizado e implantado de forma independente.
• Em um contexto de interface do usuário, componentes geralmente são compostos pelos seguintes elementos: classes, propriedades e eventos.
• A idéia básica de componentes é reutilização. Os componentes são minimamente redundante e "maximamente" compostos. A analogia do LEGO se adapta bem aqui.

• Metadados de componentes é fundamental, para que ambientes (containers) possam ler informações de componentes e compô-los com outros componentes.
• Componentes não devem ter qualquer dependência implícita para com o ambiente para serem executados. É necessário saber antecipadamente (ou seja, tempo de compilação/design), se um componente funcionará em um ambiente ou não.
• Recursos de modelagem de componente apresentados pela UML são limitados e não muito úteis.
• Componentes podem ser sem estado ou com estado.
• A visão de mercado do componentes (desenvolvimento baseado em componentes) ainda não foi atingida plenamente.
• Componentes são, para arquiteturas, o que classes são para linguagens de programação. Componentes são os menores e mais relevantes relevantes blocos arquiteturais de construção; são os alicerces da arquitetura.
• Componentes são compostos tendo seus instâncias interligadas a outras instâncias de componentes.
• Na abordagem top-down, componentes podem ser identificados/selecionados e, em seguida, mapeado por ferramentas a tecnologias específicas.
• Componentes não são necessariamente relacionadas com a orientação de objetos.
• Componentes são diferentes de instâncias de componente. Mas em alguns sistemas em que existe apenas uma instância de um determinado componente, este debate se torna desnecessário.
• Metadados do componente minimamente devem incluir interfaces e serviços que ele fornece e requer.
• Versionamento de componente é sempre uma preocupação: será que uma versão nova de um componente falhará em um ambiente antigo? Idealmente, novas versões devem apresentar compatibilidade.
• Idealmente, componentes também devem permitir que o ambiente os parametrize.
• Papéis de componentes podem ser implementadas por portas.

• Nomes de serviços permitem a correta comunicação e descoberta de componentes.
• Containers gerenciam recursos de componentes, seu ciclo de vida e acesso a recursos.
• SOA x componentes: componentes podem ser vistos como uma implementação de serviços, estando estes últimos mais preocupados com a fornecer as interfaces. Os autores do podcast afirm a SOA é um hype, mas eu particularmente discordo com isso.

[]
--AFurtado
Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation.

---

VSX DevCon is a great opportunity to get a deep dive into the Visual Studio extensibility world. I'm really looking forward to attending to the event, which belongs to the fascinating area of providing automation to enable the software factories vision.

Does it get any better? Yes, all attendees will receive a free copy of the book Professional Visual Studio Extensibility!

Does it get even better? Yes, the event walking distance from my home! :) If you're going to VSX DevCon, drop by for a couple of tea (I mean, a Xbox match) if you will.

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

VSX DevCon é uma grande oportunidade de dar um mergulho profundo no mundo da extensibilidade do Visual Studio. Eu estou olhando ansioso para ir ao evento, que pertence à área fascinante de fornecer a automação para permitir a realização da visão das fábricas de software.

E pode ficar melhor? Sim, todos os participantes receberão uma cópia gratuita do livro Professional Visual Studio Extensibility!

E pode ficar ainda melhor? Sim, afinal dá para ir andando ao evento da minha casa! :) Se você está indo ao VSX DevCon, apareça para tomar um chá (digo, jogar uma partida de Xbox) se você quiser.

[] s
-- AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation.

---

These days I was asking myself: besides placing XML comments in the code, what an API developer should do so that its consumers (clients) are able to check the API documentation in the Object Browser in Visual Studio or as tooltips when developing the client code, as shown in the pictures below?

The first (obvious) thing is to place the XML comments in the API code, using the Visual Studio “///” (triple slash) feature, which automatically creates the XML skeleton for you to populate:

If your client code is in the same Visual Studio project or solution of the API code, then nothing special needs to be done: the documentation support will be there automagically. However, if the API is being consumed as an external dll, as it is generally the case, something else needs to be done, since the comments are not stored in the .NET assembly. We actually need to enable the generation of XML documentation files in the project properties (as shown below) and make those files available to API clients as well.

When a client adds a reference to such assemblies and its corresponding XML documentation file is there, then Visual Studio is able to build the documentation cache and show it in object browser, code tooltip, etc.

The built-in .NET assemblies (System.dll, System.Data.dll, etc.) are no exception to this rule: if you check your c:\Windows\Microsoft.NET\Framework\v2.0.50727 folder, the XML documentation files for those built-in assemblies will be there as well.

PS: If you want to generate .chm help files from the XML comments, so that your API documentation is even more clear (and navigation-enabled) to your users, I suggest you to use a simple tool I’ve created, that leverages the SandCastle documentation compiler, to easily generate such kind of files.

[]s
-- AFurtado
The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

Atualmente eu estava perguntando-me: além dos comentários XML no código, o que mais um desenvolvedor de API deve fazer de modo que seus consumidores (clientes) possam checar a documentação da API no Object Browser do Visual Studio ou como tooltips ao desenvolver o código cliente, como mostrado pelas figuras abaixo?

A primeira coisa (óbvia) é colocar os comentários de XML no código da API, usando “///” (barras triplas), que criam automaticamente o esqueleto de XML para que você preencha:

Se seu código cliente está no mesmo projeto ou solução do código da API, nada especial precisa ser feito: o suporte à documentação estará lá automagicamente. Entretanto, se a API está sendo consumida como uma DLL externa, como é geralmente o caso, algo mais deve de ser feito, já que os comentários não são armazenados no assembly .NET. Nós precisamos na verdade habilitar a geração de arquivos de documentação de XML nas propriedades do projeto (como mostrado abaixo) e fazer também esses arquivos disponíveis aos clientes da API.

Quando um cliente adiciona uma referência a tais assemblies e seu arquivo correspondente de documentação XML está lá, o Visual Studio pode construir o cache da documentação e mostrá-lo no Object Browser, no tooltip do código, etc.

Os assemblies que acompanham o .NET Framework (System.dll, System.Data.dll, etc.) não são nenhuma exceção a esta regra: se você verificar o c:\Windows\Microsoft.NET\Framework\v2.0 .50727, os arquivos de documentação XML para esses assemblies internos estarão lá também.

PS: Se você quer gerar arquivos da ajuda .chm a partir dos comentários XML, de modo que sua documentação da API seja ainda mais clara (e com navegação) para seus usuários, eu sugiro usar uma ferramenta que simples eu criei, que usa o compilador de documentação SandCastle, para gerar facilmente tal tipo de arquivo .chm.

[] s
-- AFurtado
Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation

---

This episode of the Software Engineering radio brings the interesting topic of plug-ins in application development. Here you have my highlights from it:

• A plug-in is an extension to an application that is supposed to be extended, while components doesn't really know their target application.
• Interesting analogy: plug-ins extend the behavior of an application the same way as OS device drivers extend the behavior of the OS.
• Plug-ins can be self-contained, i.e., they doesn't build on top of each other. On the other hand, they can be designed so that they consume or are reused by other plug-ins.
• Plug-ins should be discoverable, not only for the target application but eventually for other plug-ins. This remembers me the VSTS services for registering and un-registering its implemented extensions.
• Plug-ins should raise events so that the target app and others plug-ins can properly react.
• It's all about extensibility points. There should be contracts (this can be as formal as you want) between extensibility points and extension code.
• Entry points (menu items, events, etc.) support extensibility points. That's where the value of having something such as GAT (Guidance Automation Toolkit) is really shown.
• Separation of concerns in traditional architectural layers (UI, logic, persistence, etc.) generally is completely orthogonal to the plug-in architecture. Plug-ins are likely to be focused on a specific layer.
• Plug-ins should be loaded on demand to improve performance.
• Plug-ins help to focus on what's essential to the app and what is optional. Optional items can come in the flavour of plug-ins.
• When to not use plug-ins? In small systems with few classes, or in performance-constrained environments.
• Should we always provide extension points or only if a client is there to use it? I prefer using the common sense and always provide extension points if I see cool extensibility opportunities, unless that turns to be too cumbersome. It is important to evaluate the trade-off between the overhead of the project versus the overhead of the plug-in infrastructure.

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

Este episódio do Software Engineering Radio traz o tópico interessante dos plug-ins no desenvolvimento de aplicações. Aqui você tem meus destaques:

• Um plug-in é uma extensão a uma aplicação que supostamente deve ser estendida, quando componentes não conhecem realmente sua aplicação-alvo.
• Analogia interessante: os plug-ins estendem o comportamento de uma aplicação a mesma maneira que device drivers estendem o comportamento do sistema operacional.
• Os plug-ins podem ser independentes, isto é, não se baseiam em demais. Por outro lado, podem ser projetados de modo que eles consumam ou reusem outros.
• Os plug-ins devem ser capazes de serem descobertos, não somente pela app-alvo mas eventualmente por outros plug-ins. Isto me lembra dos serviços do VSTS para registar e des-registar suas extensões implementadas.
• Os plug-ins devem levantar eventos de modo que a app alvo e outros plug-ins possam corretamente reagir.
• Tudo está relacionado a pontos da extensibilidade. Deve haver contratos (tão formais como você quiser) entre pontos da extensibilidade e código de extensão.
• Pontos de entrada (entradas de menu, eventos, etc.) suportam pontos de extensibilidade. Isso mostra o valor de ter algo tal como o GAT (Guidance Automation Toolkit).
• A separação de interesses nas camadas tradicionais (UI, lógica, persistência, etc.) é geralmente completamente ortogonal à arquitetura de plug-ins. Os plug-ins são geralmente focados em uma camada específica.
• Os plug-ins devem ser carregados sob demanda para melhorar o desempenho.
• Os plug-ins ajudam a focar em o que é essencial à app e em o que é opcional. Os itens opcionais podem vir na forma de plug-ins.
• Quando não usar plug-ins? Em sistemas pequenos com poucas classes, ou em ambientes de desempenho restrito.
• Devemos sempre fornecer pontos de extensiblidade ou somente se um cliente está lá a usar? Eu prefiro usar o senso comum e forneço sempre pontos da extensão se eu ver oportunidades interessantes de extensibilidade, a menos que a implementação da extensibilidade traga muito trabalho. É importante avaliar o trade-off entre o overhead geral do projeto contra o overhead da infra-estrutura de plug-ins.

[] s
-- AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation

---

Sandcastle is a tool that extracts XML comments from code and generates documentation files. The tool is very flexible, but unfortunately, since it requires some scripting from the end-user, it may not be intuitive for those who simply want the basic scenario of generating a .chm (help file) from a .NET assembly.

I've created a simple .NET app (BuildDoc.exe) together with a hacked Sandcastle script (build.bat) to help you to generate basic documentation from XML comments. You just need to follow the steps below:

1. Comment your code with XML comments (duh!). A warning is that your class should be public, otherwise it won't appear in the generated documentation files.

2. In the project properties Build tab, select the option XML documentation file. Now when your solution is built, a .xml file with the name of your .NET assembly will be generated as well, containing the documentation.

3. Download Sandcastle.

4. Create a new folder in the c:\Program Files\Sandcastle\Examples folder to be used temporarily for the documentation generation. For example, call it "TestDoc".

5. Copy your .NET assembly and its .xml file to the TestDoc folder.

6. Copy my BuildDoc.exe program and build.bat script (get these files here) to that same TestDoc folder. If Sandcastle in your machine is installed in a folder other than c:\Program Files\Sandcastle\, change this twice in the build.bat file.

7. Open a command prompt session. If running Vista, use elevated privileges.

8. Go to TestDoc folder and then run BuildDoc <AssemblyName>.dll.

9. Wait for the generation process to happen. It may take a few minutes.

10. Your generated documentation will be at TestDoc\Output\<AssemblyName>.chm:

If you want more control in the generation process, you can do further hacking in my script and other Sandcastle scripts. For example, you can change the generation style from "vs2005" to "hana". I'll leave this as an exercise to the reader. ;)

[]s
-- AFurtado

The statements or testimonies I offer in this post represent my own personal views.
I am speaking for myself and not on behalf of my employer, Microsoft Corporation

English - Portuguese

---

 

O Sandcastle é uma ferramenta que extrai comentários XML do código e gera arquivos de documentação. A ferramenta é muito flexível, mas infelizmente, desde que exige scripting do usuário final, ela pode não ser intuitiva para aquelas que querem simplesmente o cenário básico de gerar um .chm (arquivo de ajuda) de um assembly .NET.

Eu criei uma app .NET simples (BuildDoc.exe) junto com um script hackeado do Sandcastle (build.bat) para ajudá-lo a gerar documentação básica de comentários XML. Você apenas precisa seguir as etapas abaixo:

1. Comente seu código com comentários XML (dã!). Um aviso é que sua classe deve ser pública, senão ela não aparecerá nos arquivo de documentação gerado.

2. Nas propriedades do projeto, aba Build, selecione a opção XML documentation file. Agora quando você construir sua solução, um arquivo .xml com o nome de seu assembly .NET será gerado também, contendo a documentação.

3. Baixe o Sandcastle

4. Crie uma nova pasta em c:\Program Files\Sandcastle\Examples a ser usada temporariamente para a geração da documentação. Por exemplo, chame-a “TestDoc”.

5. Copie seu assembly .NET e seu arquivo XML à pasta TestDoc.

6. Copie meu programa BuildDoc.exe e o script build.bat (baixe-os aqui) para essa mesma pasta TestDoc. Se o Sandcastle em sua máquina é instalado em uma pasta à exceção de c:\Program Files\Sandcastle\, mude isto duas vezes no arquivo build.bat.

7. Abra uma sessão de prompt de comando. Se estiver no Vista, use privilégios elevados.

8. Navegue para a pasta TestDoc e rode BuildDoc <AssemblyName>.dll.

9. Espere a geração. Pode levar alguns minutos.

10. O arquivo de documentação estará gerado em TestDoc\Output\<AssemblyName>.chm

Se quiser mais controle do processo de geração, mude o meu script ou os scripts do Sancastle. Por exemplo, você pode mudar o estilo de geração de "vs2005" para "hana". Deixarei isso como um exercício para o leitor. ;)

[]s
-- AFurtado

Os relatos e opiniões deste post apresentam pontos de vista pessoais,
não refletindo necessariamente a opinião da Microsoft Corporation.

---