Azure DevOps Server (TFS) Operational Intelligence Activity Log

There is a little known feature of Azure DevOps Server, at least the on-prem version, that allows admins to look at the requests made to the server as well as the activity of the JobAgent.

This feature can be accessed by pointing your browser to 
<Base Server URL>/_oi/_diagnostics/activityLog
for example:
https://TFSServer/tfs/_oi/_diagnostics/activityLog


Once there you can switch between two views the Activity log and Job Monitoring by clicking on the tabs on the left.

The activity log shows a list of the requests being made to the server, including the identity of the requestor, the source IP address as well as the HTTP Response Code. I have found this helpful in tracking down when people are having issues.

One of the other nice things is that the activity log is exportable to CSV (see the green highlight above, which makes it very easy to work with in MS Excel and drill down to see just a single requestor.

The Job Monitoring tab shows a number of graphs about the Job Agent, the internal worker process. The graphs are all clickable and drill down to further information. 

I don't access this operational Intelligence information very often, but when I need it, it is information I can't find anywhere else. Hope you find it useful as well

Passing variables by Reference in PowerShell

I often have to write PowerShell scripts that perform some operation on a set of files. Sometimes I need to validate something about the files, for example that they are all well formed XML. 

The requirements are that 

1. All files are examined
2. Any files that have an issue are called out
3. The script returns a failure if one or more files fails the check.

To examine all of the files I use Get-ChildItem and then pipe that into a function to do the verification. 

Get-Childitem -path $directoryToCheck -filter '*.xml' -recurse | VerifyXMLFileFormat

and VerifyXMLFileFormat looks like

function VerifyXMLFileFormat
{
    foreach ($o in $input)
    {
        Write-host 'Reading:' $o.FullName

        try
        {
            [xml]$xml = Get-Content $o.FullName
        }
        catch
        {
            Write-Host "$($o.FullName) is not a valid XML file"
        }
    }
}

The challenge I have run into is that I have been unable to easily set a value in the called function and use it outside of the function because of how it is called as part of a pipeline. If in the catch block I use Write-Host-Error, or return $false, or throw, then not all of the files are processed. 

What I wanted was to pass a variable by reference so that VerifyXMLFileFormat can set the value and the calling function can reference the value. To do that I had to add a [REF] and access the .Value of the variable like this in the function

        catch
        {
            Write-Host "$($o.FullName) is not a valid XML file"
            $invalidFileFound.Value = $true
        }

Now I call the function like this

[bool] $invalidFileFound = false

Get-Childitem -path $directoryToCheck -filter '*.xml' -recurse | VerifyXMLFileFormat ([REF]$invalideFileFound)

Using that I can now meet all three requirements that I had

Can we avoid learned intuitiveness?

Learned intuitiveness, sounds like an oxymoron right? Learned intuitiveness is when you need to learn the general principles of how an interface works before it is intuitive (obvious) how to make it do what you want. In other words it is NOT automatically understood. Let's take a look at what Merriam Webster says about intuitiveness. There are two definitions that we should look at, the others are defined (in terms of intuitive)

1. directly apprehended
2. readily learned or understood

It is the later one that defines learned intuitiveness, it is easily understood, but perhaps not instantaneously. As an example of this, take an iPhone user and hand them and Android phone, or visa versa, and ask them to make a phone call. In my experience, unless one if familiar with both platforms, the user will fumble around trying to do what is natural for them on the platform they are used to because they learned that intuitiveness.

While this is wonderful for vendors because when users need to upgrade they will quite often stay with the platform they are familiar with due to their familiarity with it, they have learned the intuitiveness of that vendor's interface. In UX terms, upgrading to a new version of a platform should not break the users mental model. 

The question that I feel needs to be posed is do we need to rely on learned intuitiveness or can we build an interface that is automatically understood? I am not certain what the answer is and would love to hear your thoughts.

.NetCore - How to enable creation of a NuGet package during build

Before .Net Core if you wanted to generate a NuGet package you could use the csproj itself or a nuspec file, or actually both at the same time. Using a nuspec file, either by itself or in conjunction with the csproj allowed setting of some of the settings that could not be set easily, or at all, with just using the csproj.

With the introduction of the new style csproj files for .Net Core 2.0, the information that was previously stored in a nuspec file and in the assembly file can now be directly stored in the csproj file. Given a default csproj file:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
  </PropertyGroup>

</Project>

It is very easy to include the needed entries to generate a nupkg.

For example:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.0</TargetFramework>
    <Description>PUT THE DESCRIPTION HERE</Description>
    <Company>PUT THE COMPANY NAME HERE</Company>
    <Copyright>Copyright (c) PUT COPYRIGHT INFO HERE</Copyright>
    <Authors>PUT THE AUTHOR INFO HERE</Authors>
    <AssemblyName>PUT THE ASSEMBLY NAME HERE</AssemblyName>
    <PackageId>PUT THE PACKAGE ID HERE</PackageId>
    <PackageTags>PUT ANY APPLICABLE TAGS</PackageTags>
    <NeutralLanguage>en-US</NeutralLanguage>
    <Version>1.0.0</Version>
    <AssemblyVersion>1.0.0.0</AssemblyVersion>
    <FileVersion>1.0.0.0</FileVersion>

  </PropertyGroup>

</Project>

You will of course need to change the ALL CAP ITALICS entries above to the correct values for your project. You should have your automated build process  set the correct values for the three version entries.

There are more entries that can be added as per Additions to the csproj format for .NET Core such as adding the URL to the repository and the type of repository.

Unfortunately there is not an element that allows us to point to a readme file that will then show up in the NuGet GUI in Visual Studio. Because of this lack I hijack the PackageProjectURL element and put there the URL to the readme.md file that is required for all of my projects. If you do this remember to replace any ampersands in the URL with &amp; so that the URL link works correctly when displayed. Consumers of the NuGet package can then click on the link in the NuGet GUI to get more information. 

I find the .Net Core csproj much easier to deal with than the older project format. Teams should find it easier as it should lead to less merge conflicts simply because there is less in it. 

Should we always keep it DRY?

I am not talking about my basement, if I was the answer is a resounding YES! which I why I am having a waterproofing come up to the house to patch a hole in the foundation.

DRY in this case is an acronym for Don't Repeat Yourself.  This first place that I read about this principle was in The Pragmatic Programmer by Andrew Hunt and David Thomas, as far as I am aware they are the ones that made up the acronym DRY. In their words "Every piece of knowledge must have a single, unambiguous, authoritative representation within a system." The goal is to avoid having multiple copies of code that diverge from each other, thereby causing bugs when a change is not applied to all copies.

As with all software development principles, it is important to ensure that we correctly apply this principle. As developers we need to be careful not to create duplicate code as this is, of course, undesirable. At the same time we need to make sure that we do not violate any architectural principles and we also need to be certain that we are looking at actual and not apparent duplication. At this point you may be wondering if I have lost my mind, isn't it fairly obvious if there are 2 methods in the same object of same hierarchy that have identical code. Yes that is obvious and today there are tools that will help us find and remove duplicated code. I am concerned that we remove the duplication in a way that doesn't decrease readability, that doesn't violate architectural design and that it is actual duplication.

I have seen too many developers, who apparently have had the DRY principle driven into their brains apply this relentlessly. In one case small sections of functions had between 2 and 4 lines of duplicated code across modules and architectural boundaries. The "fix" put in made the code significantly harder to read, (bad choices for method names didn't help) and added complexity to the code. Worse was not noting the architectural boundaries, the "fix" added a dependency between modules in the wrong direction across an architectural boundary. It is critical that we manage component and architectural dependencies. (This cannot be overstated and here I leave it as a single line in a blog...left an as exercise to the reader to understand why.)

Lastly, I mentioned apparent duplication. This happens much more often with data structures then method bodies. In apparent, but not real, duplication the two structures are logically separate and exist for separate reasons. Combining them will reduce maintainability because it will add dependencies. In most cases these structures will diverge due to feature requests. If they are forced together into the same structure then all interactions with that data structure will, over time, will not use all fields. One could argue force them together now and refactor later, based on architectural design that may or may not be appropriate. 

In short I just wanted to point out that relentless de-duplication is great as long as we keep in mind the larger architectural concerns of the software.

Do not waste time pre-optimizing your code, but don't pre-pessimize it either!

Regardless of what language you are programming in and what system you are designing, until you have measured performance you cannot know what needs optimization beyond what the compiler already provides out of the box. That is perhaps a rather bold statement. It is true in my experience and I hope you will at least consider its truth if not agree with me by the end of this post. 

Donald Knuth in his paper entitled Structured Programming with go to Statements says
"There is no doubt that the grail of efficiency leads to abuse. Programmers waste enormous amounts of time thinking about, or worrying about, the speed of noncritical parts of their programs, and these attempts at efficiency actually have a strong negative impact when debugging and maintenance are considered. We should forget about small efficiencies, say about 97% of the time: pre- mature optimization is the root of all evil. Yet we should not pass up our opportunities in that critical 3 %. A good programmer will not be lulled into complacency by such reasoning, he will be wise to look carefully at the critical code; but only after that code has been identified. It is often a mistake to make a priori judgments about what parts of a program are really critical, since the universal experience of programmers who have been using measurement tools has been that their intuitive guesses fail."

Note: There is discussion on the internet that part or all of that quote should be attributed to C. A. R. Hoare. However that is incorrect as can be seen here. Given this is the internet we may never know who first said it, regardless of who should get credit for it, it is still good advice.

It is important to read that carefully. Many find the last line hard to believe and to consistently apply. My experience in this area parallels that of Mr. Knuth. "The universal experience of programmers who have been using measurement tools has been that their intuitive guesses fail" The only way to know what needs to be optimized is to measure and then only optimize the part of the system that needs it! One must measure the complete path and then find the piece that needs to be optimized.

Just because we know some code will often be executed, we don't know if improving the performance of that code will actually change the performance of the overall system. There may be other pieces of the system whose performance overshadows the performance of that piece of code. It could be that network hops, or latency or some other piece of code or component of the architecture needs to be addressed first to improve performance. Performance improvement is a cycle of measure, find the bottleneck, optimize to remove the bottleneck, and measure again. If the system (not the piece of code) is still not performant enough repeat the cycle until it is.

I have watched many programmers spend a lot of time optimizing code, because they can make it faster, not because there was a net benefit to the system. In many cases the optimization hurt the system because the optimization was at a micro level, it negatively impacted readability and therefore maintainability of the code and sometimes it prevented a macro optimization across a larger swath of the system. This is what Knuth refers to when he said "the grail of efficiency leads to abuse".

So what is an optimization? An optimization is any change, made for performance reasons, that makes designs and/or code more complex and less readable, and therefore harder to maintain. If the change doesn't lessen readability, then it isn't an optimization.

In their book C++ Coding Standards Herb Sutter and Andrei Alexandrescu propose two guidelines

• Don't optimize prematurely
• Don't pessimize prematurely

The first guideline is exactly what we have been discussing. It is very important to apply the second rule especially when it comes to design. In code this means use the idioms and practices of the language which are usually naturally efficient. If those were not used, changing the code to use those idioms will often increase performance but since using the idioms will increase the readability of the code it is not an optimization. We need to make sure we apply the second guideline to designs as well as code. Building something that will not scale to the required usage would be an instance of pre-pessizming.

There are many articles on the internet discussing the fallacy of the "evil of pre-optimization" in every cases I have seen to date they are really discussing issues that are cases of pre-pessimization including cases where the developers are not yet competent enough to know what the correct performant code and design idioms of the language in use are and there are no experienced developers to guide them.

Do not pre-optimize or pre-pessimize! Using the definition of optimization above it is clear how to differentiate. I have followed these guidelines for many years with great success at creating solid systems and only optimizing the parts that truly needed it. I hope you find these guidelines equally as helpful.

Do you treat SQL code as a first class citizen?

Too many times I have seen developers treating SQL code and the database itself as a second class citizen. They would go into a production database and make stored procedure or table structural changes directly in production. The database was an afterthought and not carefully crafted and discussed the way that their parts of the product coded in their language of choice was, be it C#, Java, C++, etc. In my opinion this is wrong, it leads to bugs and technical debt and for medium to large systems it often leads to performance issues. It is similar in some ways to treating test code as a second class citizen, where one then spends an inordinate amount of time looking for bugs in production code that are actually in the test code because the same care wasn't taken with the test code as the production code, but that is a soap box for another post.

What do I mean as SQL code as a first or second class citizen? What I mean by that is that you give it the same level of care and attention as the rest of the code in your system.

If you treat SQL code as a first class citizen, I expect to see the following:

• Just as you treat the source code in source control as the source of truth you treat the database files in source control as the source of truth. It is very telling when a team treats a database as the source of truth. When this is done in most cases, the team cannot recreate the database from scratch, which makes integration and system testing more difficult. When a team is constantly adjusting the files in the source control to match a database that is an indication that the source control is not being treated as the source of truth. Would you adjust binaries and then go make the source code match?
• Just as source code for the other languages you code in are stored in source control, so are the SQL files. This is regardless of if you deploy the database as a model or via files, you ensure that the artifacts needed to deploy the database are stored in source control. These may be a model or individual SQL file.
• Just as the team takes the time to properly chose algorithms and data structures in their primary language, they make sure to do the same in SQL code. They make sure that the correct key and constraints are in place, using the 
• Just as you author a deployment system for your code, you do the same for the database, in some case they can be part of the same deployment process.
• Just as your team has coding standards for your primary language(s), you also have codding standards for SQL. (You do have standards right?) These standards should all be at the same level of detail.
• Just as your team code reviews their other code, they review SQL and apply the same rigor to those reviews.

I am sure there are more comparisons, but as you can see it is simply a matter of treating the database in all aspects with as much care as we treat our other languages, from source code to design to deployment.

Please feel free to share your thoughts.