Best Practices should not be the end of a conversation

Sometimes, Best Practices can be used as an end all to a conversation. No more needs to be said, because Best Practices have laid out the final statement … and that doesn’t really feel right.

Best practices weren’t always best practices. At some point a new technology came around and people started working with it to create their own practices. And the practices that worked stuck around. Over time, those practices might be written down as suggested practices for a particular technology stack. And, when coming from the authoritative source for a technology stack, they might be labeled as Best Practices.

But, usually, when I hear Best Practices used as an end all to a conversation, it’s not in reference to a particular technology stack. It’s used as a generalization, to explain guidance to approach an area. The guidance is supposed to help people who haven’t done something before start off in the right direction. It’s supposed to be a starting point. And I think you’re supposed to continue to study the usage of those practices, to determine what the right practices are for your environment and your technology stack. Maybe even setup criteria to evaluate if a practice is working successfully in your environment. And, then change a practice if it doesn’t meet your needs.

That isn’t a trivial thing to do. You have to first understand where the practices came from and what they were accomplishing. But, once you do, you should be able to see where their limitations are and where they can be expanded. Sometimes a technology stack wasn’t available when a practice was written, and that changes the possible ways a desired outcome can be achieved. To change a practice, you have to be knowledgeable of what outcomes are trying to be achieved, and the pitfalls that come with them; and then make a decision based on the trade-offs of going to a new practice.

The only way to create a new practice, is if Best Practices are the start of a conversation, not the end of one.

(Maybe we could also drop the word “Best”, and just make them practices?)

More Andon Cord

I was listening to Gene Kim’s new podcast, Idealcast, interview with Dr. Steven Spear (Decoding the DNA of the Toyota Production System), and the subject of Andon Cords came up. Since I had recently written a post on Andon Cords, I was very curious if their conversation would line up with my thoughts or if it would show a different angle or new depths. The text of the conversation was (from Ep 5):

---

Gene Kim

The notion of the Andon Cord is that anyone on the front line would be thanked for exposing an ignorance/deficiency for trying to solve a problem that the dominant architecture or current processes didn't foresee.

Dr. Steven Spear

That's right. Basically, the way the Andon Cord works is you, Gene, have asked me, Steve, to do something and I can't. And, I'm calling it to your attention. Such that the deficiencies in my doing become a reflection of the deficiencies in your thinking / your planning / your designing. And we're going to use the deficiencies in my doing as a trigger to get together and improve on 'your thinking and my doing' or 'our thinking and our doing'.

Gene Kim

And the way that's institutionalized amplifies signals in the system to self correct.

---

To me, that definitely feels like a new angle or view point on Andon Cords. It still feels like it aligns with the “popular definition”, but it’s more clear in it’s description. It seems to follow a line of thinking that “We’ve got a problem occurring right now; let’s use this as an opportunity to look at the problem together. And, then let’s think about ways to improve the process in the future.” Which feels like a more directed statement than “the capability to pause/halt any manufacturing line in order to ensure quality control and understanding.”

But, the definition Gene (Mr. Kim?) and Dr. Spear’s give does imply something I want to point out: Gene’s scenario is one where the person using the Andon Cord is someone directly involved in the processing line. It’s by someone who is directly on the line and seeing a problem as it’s happening. The cord isn’t being pulled by someone who wasn’t asked to be involved in the process.

I wonder if there are any texts on recognizing when an Andon Cord is being used inappropriately? Is that even a thing?

Record Request Body in ASP.NET Core 3.0–Attempt 2

In the original post (Record Request Body in ASP.NET Core 3.0), the ITelemetryInitializer was creating some unexpected behavior. It was preventing the Operation ID associated with each request from changing/being updated. So, all the requests that were going through the system were being displayed on the same Performance graph. This created a nearly unusable performance graph as all the request were squished together and unreadable for timing purposes.

So, I needed to remove the ITelemetryInitializer from the code. But, I still wanted to record the JsonBody. The work around I used (which isn’t great) was to create a fake dependency on the request and record the body within the properties of the dependency.

Here’s the code:

	using System.IO;
	using System.Text;
	using System.Threading.Tasks;
	using Microsoft.ApplicationInsights;
	using Microsoft.ApplicationInsights.DataContracts;
	using Microsoft.AspNetCore.Mvc.Filters;
	namespace YourNamespace
	{
	public class TrackConstants
	{
	public const string JsonBody = "JsonBody";
	}
	public class TrackRequestBodyAttribute : ActionFilterAttribute
	{
	private readonly TelemetryClient _telemtry;
	public TrackRequestBodyAttribute(
	TelemetryClient telemetry = null
	)
	{
	_telemtry = telemetry;
	}
	public override async Task OnActionExecutionAsync(ActionExecutingContext context, ActionExecutionDelegate next)
	{
	var request = context.HttpContext.Request;
	request.Body.Position = 0;
	using var stream = new StreamReader(request.Body, Encoding.UTF8, false, 1024, true);
	var body = await stream.ReadToEndAsync();
	request.Body.Position = 0;
	context.HttpContext.Items.Add(TrackConstants.JsonBody, body);
	var toperation = _telemtry.StartNewOperation<DependencyTelemetry>("JsonBody");
	toperation.TData.Add(TrackConstants.JsonBody, body);
	toperation.Stop();
	await base.OnActionExecutionAsync(context, next);
	}
	}
	}

view raw TrackRequestBodyAttribute.cs hosted with ❤ by GitHub

	using System;
	using System.Collections.Generic;
	using System.Linq;
	using System.Net.Http;
	using Microsoft.ApplicationInsights.Extensibility;
	using Microsoft.Extensions.DependencyInjection;
	using Microsoft.Extensions.DependencyInjection.Extensions;
	namespace YourNamespace
	{
	public static class IServiceCollectionExtensions
	{
	public static IServiceCollection AddYourDependencies(
	this IServiceCollection services
	)
	{
	// add other dependencies
	services.TryAddTransient<TrackRequestBodyAttribute>();
	return services;
	}
	}
	}

view raw IServiceCollectionExtensions.cs hosted with ❤ by GitHub

	using System.Collections.Generic;
	using System.IO;
	using System.Text;
	using System.Threading.Tasks;
	using Microsoft.ApplicationInsights;
	using Microsoft.AspNetCore.Builder;
	using Microsoft.AspNetCore.Hosting;
	using Microsoft.AspNetCore.Http;
	using Microsoft.Extensions.Configuration;
	using Microsoft.Extensions.DependencyInjection;
	using Microsoft.Extensions.Hosting;
	namespace YourNamespace
	{
	public class Startup
	{
	// This method gets called by the runtime. Use this method to add services to the container.
	public void ConfigureServices(IServiceCollection services)
	{
	services.AddControllers();
	services.AddYourDependencies()
	}
	// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
	public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
	{
	app.UseMiddleware<EnableBufferingMiddleware>();
	// use that middleware before everything else
	}
	}
	}

view raw Startup.cs hosted with ❤ by GitHub

	using System.IO;
	using System.Threading.Tasks;
	using Microsoft.AspNetCore.Http;
	using Microsoft.AspNetCore.Http.Features;
	namespace YourNamespace
	{
	public static class HttpRequestExtensions
	{
	public static bool CanReadBody(this HttpRequest request)
	{
	return (
	request.Method == HttpMethods.Post
	|| request.Method == HttpMethods.Put
	)
	&& request.Body.CanRead;
	}
	}
	public class EnableBufferingMiddleware
	{
	private readonly RequestDelegate _next;
	public EnableBufferingMiddleware(
	RequestDelegate next
	)
	{
	_next = next;
	}
	public async Task InvokeAsync(HttpContext context)
	{
	var request = context.Request;
	if (request.CanReadBody())
	{
	request.EnableBuffering();
	}
	await _next(context);
	}
	}
	}

view raw EnableBufferingMiddleware.cs hosted with ❤ by GitHub

	using System.Linq;
	using System.Threading.Tasks;
	using Microsoft.ApplicationInsights;
	using Microsoft.AspNetCore.Mvc;
	namespace YourNamespace
	{
	[ApiController]
	[Route("[controller]")]
	public class ExampleController : ControllerBase
	{
	public CodePushedController() {}
	[ServiceFilter(typeof(TrackRequestBodyAttribute))]
	public async Task<IActionResult> PostAsync([FromBody] CodePushedRequest request)
	{
	// your code
	}
	}
	}

view raw ExampleController.cs hosted with ❤ by GitHub

Baseline C# Objects to Populate Jira DevInfo Pt. 2

From the previous post, Baseline C# Objects to Populate Jira DevInfo Pt. 1:

Jira has this great “Development Information” (DevInfo) that can be associated with your work items. Which has an API described here. The information provided in the development tabs are for Branches, Commits, Pull Requests, Builds, Deployments and Feature Flags. Which is a way to have visibility into all the development/code activity that is related to a particular work item. It’s a great way to connect everything together.

On the previous post, there’s also a list of “gotcha’s” with the Jira documentation and a list of things could be improved.

But, this post is about the baseline C# objects which can be used to push information to the Atlassian/Jira DevInfo API.

	using System;
	using System.Collections.Generic;
	using System.Linq;
	using System.Threading.Tasks;
	using Atlassian.Jira;
	namespace YourProject
	{
	public class JiraDevInfoBulkRequest
	{
	public List<JiraRepository> Repositories { get; set; }
	public bool PreventTransitions { get; set; }
	public Dictionary<string,string> Properties { get; set; }
	public JiraProviderMetadata ProviderMetadata { get; set; }
	}
	public class JiraRepository
	{
	public string Id { get; set; }
	public string Name { get; set; }
	public string Description { get; set; }
	public string Url { get; set; }
	public string Avatar { get; set; }
	public string AvatarDescription { get; set; }
	public string ForkOf { get; set; }
	public List<JiraCommit> Commits { get; set; } = new List<JiraCommit>();
	public List<JiraPullRequest> PullRequests { get; set; } = new List<JiraPullRequest>();
	public List<JiraBranch> Branches { get; set; } = new List<JiraBranch>();
	public long UpdateSequenceId { get; set; }
	}
	public class JiraCommit
	{
	public string Id { get; set; }
	public string Hash { get; set; }
	public string Message { get; set; }
	public List<string> IssueKeys { get; set; }
	public string Url { get; set; }
	public string DisplayId { get; set; }
	public DateTime AuthorTimestamp { get; set; }
	public JiraAuthor Author { get; set; }
	public int FileCount { get; set; }
	public List<string> Flags { get; set; }
	public List<JiraCommitFile> Files { get; set; }
	public long UpdateSequenceId { get; set; }
	}
	public class JiraAuthor
	{
	public string Name { get; set; }
	public string Email { get; set; }
	public string Username { get; set; }
	public string Url { get; set; }
	public string Avatar { get; set; }
	}
	public class JiraCommitFile
	{
	public string Path { get; set; }
	public string Url { get; set; }
	public string ChangeType { get; set; }
	public string LinesAdded { get; set; }
	public string LinesRemoved { get; set; }
	}
	public class JiraProviderMetadata
	{
	public string Product { get; set; }
	}
	public class JiraPullRequest
	{
	public string Id { get; set; }
	public List<string> IssueKeys { get; set; }
	public string Status { get; set; }
	public string Title { get; set; }
	public string DisplayId { get; set; }
	public string Url { get; set; }
	public JiraAuthor Author { get; set; }
	public int CommentCount { get; set; }
	public string SourceBranch { get; set; }
	public string SourceBranchUrl { get; set; }
	public DateTime LastUpdate { get; set; }
	public string DestinationBranch { get; set; }
	public List<JiraReviewer> Reviewers { get; set; }
	public string Avatar { get; set; }
	public string AvatarDescription { get; set; }
	public long UpdateSequenceId { get; set; }
	}
	public class JiraReviewer
	{
	public string Name { get; set; }
	public string ApprovalStatus { get; set; }
	public string Url { get; set; }
	public string Avatar { get; set; }
	}
	public class JiraBranch
	{
	public string Id { get; set; }
	public List<string> IssueKeys { get; set; }
	public string Name { get; set; }
	public JiraCommit LastCommit { get; set; }
	public string CreatePullRequestUrl { get; set; }
	public string Url { get; set; }
	public long UpdateSequenceId { get; set; }
	}
	}

view raw JiraDevInfoBulkRequestModels.cs hosted with ❤ by GitHub

	using System.Collections.Generic;
	namespace YourProject
	{
	public class JiraDevInfoResponse
	{
	public Dictionary<string, JiraDevInfoResponseEntitySet> AcceptedDevInfoEntities { get; set; }
	public Dictionary<string, JiraDevInfoResponseEntitySet> FailedDevInfoEntities { get; set; }
	public List<string> UnknownIssueKeys { get; set; }
	}
	public class JiraDevInfoResponseEntitySet
	{
	public List<string> Branches { get; set; }
	public List<string> Commits { get; set; }
	public List<string> PullRequests { get; set; }
	}
	}

view raw JiraDevInfoResponse.cs hosted with ❤ by GitHub

	using System;
	using System.Collections.Generic;
	using System.Linq;
	using System.Net.Http;
	using System.Net.Http.Formatting;
	using System.Text;
	using System.Text.Json;
	using System.Threading.Tasks;
	using Microsoft.TeamFoundation.SourceControl.WebApi;
	using Newtonsoft.Json;
	using Newtonsoft.Json.Serialization;
	using JsonSerializer = System.Text.Json.JsonSerializer;
	namespace YourProject
	{
	public class JiraDevInfoHttpClient : IJiraDevInfoHttpClient
	{
	private readonly HttpClient _client;
	private readonly IUpdateSequenceIdManager _idManager;
	public JiraDevInfoHttpClient(
	HttpClient client,
	IUpdateSequenceIdManager idManager
	)
	{
	_client = client;
	_idManager = idManager;
	_client.SetApiBaseUri(AtlassianConstants.YourInstanceCloudId, "devinfo");
	}
	private JiraDevInfoBulkRequest BuildBulkRequest(JiraRepository repository)
	{
	var bulkRequest = new JiraDevInfoBulkRequest()
	{
	Repositories = new List<JiraRepository>() { repository },
	PreventTransitions = true,
	ProviderMetadata = AtlassianConstants.AzDProviderMetadata
	};
	return bulkRequest;
	}
	public async Task<JiraDevInfoResponse> BulkUpdateAsync(
	JiraRepository repository
	) {
	var updateSequenceId = await _idManager.NextAsync();
	repository.UpdateSequenceId = updateSequenceId;
	foreach (var c in repository.Commits)
	{
	c.UpdateSequenceId = updateSequenceId;
	}
	foreach (var b in repository.Branches)
	{
	b.UpdateSequenceId = updateSequenceId;
	}
	foreach (var pr in repository.PullRequests)
	{
	pr.UpdateSequenceId = updateSequenceId;
	}
	var bulkRequest = BuildBulkRequest(repository);
	var content = bulkRequest.ToJsonContent();
	var response = await _client.PostAsync("bulk", content);
	var result = await response.DeserializeAsync<JiraDevInfoResponse>();
	return result;
	}
	}
	public static class HttpClientExtensions
	{
	public static void SetApiBaseUri(this HttpClient client, string cloudId, string entityType)
	{
	client.BaseAddress = ApiBaseUri(cloudId, entityType);
	}
	public static Uri ApiBaseUri(string cloudId, string entityType)
	{
	// example:
	// https://api.atlassian.com/jira/devinfo/0.1/cloud/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/bulk
	var baseUrl = string.Format("{0}jira/{1}/0.1/cloud/{2}/",
	AtlassianConstants.AtlassianApiRootUrl,
	entityType,
	cloudId
	);
	var baseUri = new Uri(baseUrl);
	return baseUri;
	}
	}
	public static class JiraOAuthHttpClientExtensions
	{
	public static readonly JsonSerializerOptions SerializerOptions =
	new JsonSerializerOptions() {PropertyNamingPolicy = JsonNamingPolicy.CamelCase};
	public static HttpContent ToJsonContent<T>(this T value)
	{
	var json = JsonSerializer.Serialize(value, SerializerOptions);
	var content = new StringContent(json, Encoding.UTF8, "application/json");
	return content;
	}
	}
	}

view raw JiraDevInfoHttpClient.cs hosted with ❤ by GitHub

	using System;
	using System.Collections.Generic;
	using System.Linq;
	using System.Threading.Tasks;
	using Microsoft.EntityFrameworkCore;
	using Nito.AsyncEx;
	namespace YourProject
	{
	public interface IUpdateSequenceIdManager // you need to write your own implementation of this
	{
	Task<long> NextAsync();
	Task<long> CurrentAsync();
	}
	// This uses a MSSQL database backend with a very simple table to manage sequence number generation.
	// But, you need to write your own implementation of this. This one is not great.
	// CREATE TABLE [dbo].[tbl_UpdateSequenceIds](
	// [Name] [varchar](50) NULL,
	// [Id] [bigint] NULL
	// ) ON [PRIMARY]
	// GO
	// INSERT INTO [dbo].[tbl_UpdateSequenceIds] ([Name], [Id]) VALUES ('Current', 0)
	// GO
	public class UpdateSequenceIdManager : IUpdateSequenceIdManager
	{
	private readonly AzDPullRequestsDbContext _dbContext;
	private readonly AsyncReaderWriterLock _seqLock = new AsyncReaderWriterLock();
	public UpdateSequenceIdManager(YourProjectsDbContext dbContext)
	{
	_dbContext = dbContext;
	}
	public async Task<long> NextAsync()
	{
	using (await _seqLock.WriterLockAsync())
	{
	var sequenceRecord = await _dbContext.UpdateSequenceIds.FirstAsync(i => i.Name == "Current");
	var next = ++sequenceRecord.Id;
	await _dbContext.SaveChangesAsync();
	return next;
	}
	}
	public async Task<long> CurrentAsync()
	{
	using (await _seqLock.ReaderLockAsync())
	{
	var sequenceRecord = await _dbContext.UpdateSequenceIds.FirstAsync(i => i.Name == "Current");
	return sequenceRecord.Id;
	}
	}
	}
	}

view raw UpdateSequenceIdManager.cs hosted with ❤ by GitHub