Command Query Separation

Recently, I was reading about some basic encapsulation concepts and I came across command query separation. So this week I will be talking about what command query separation is and how it is useful.

Command Query Separation (CQS)

The term Command Query Separation was introduced by Bertrand Meyer in his book on object oriented design. The command query separation pattern is not only limited to object oriented design but can also be applied to functional programming or anywhere else.
According to CQS, any operations in the system should be either command or query but not both.

Command: Any operation that has observable side effect on the system. 
Query: Any operation that returns data and does not mutate observable state.

For example, in one of your class, you have

public void SaveName(int employeeId, string name)

This is saving Employee name into the system. Note the return type void. So this is changing the system state and returning nothing. So it's a command.


Another example, suppose you have

public string GetEmployeeName(int employeeId)

This should return the Employee name from the system and should not change the state of the system in any way. Note the return type is string (not void). So it should be query operation. The query operation should be idempotent i.e. no matter how many times you invoke a query, it should return the same response for a given system state.

Why Useful

This makes the code easier to read and helps us in separating the concerns. Imagine if you have some Get method which also changes the system state. The consumer of your code might get different response on calling the same GET operation. Such a system is non-intuitive and prone to errors and difficult to maintain. 

Similarly, if you have some Save method like this:

public string SaveName(int employeeId, string name)

The Save method here is returning a string as well as changing the state of the system. This is against the command query separation principle. Any operation can either return something or change the system state but not both.

By looking at the method signature, we don't know what the string return is. Whether the string returns the Employee name or error message or employeeId casted as string or something else. The consumer of the method will have to look into the method definition to find this out. Imagine if it's a complicated method. So now the consumer will have to either go through all of it or test it by passing different types of values or read through the whole documentation, if any. Any of these is not very favorable and makes us feel that the code sucks.

Having clear separation makes our code more readable, more intuitive and easy to follow. Furthermore, it helps in the maintainability of the code as well. When reading the system state, the consumer should be carefree that he/she is not changing the system state in any way.

Conclusion

CQS gives you a good foundation on which you can build good quality software.
As everything is life, the answer to when to use this principle is: "it depends". This is a generic principle to keep in mind when writing code. Nothing prevents you from disobeying the principle but if it can be followed, we should adhere to it.

However, we might have some exceptions where we can't follow the principle verbatim. For example, if you have an email system, where reading an email marks the email as Read. So here the Query operation could be changing the system state and marking the email as Read. So personally I would prefer to follow the principle when I can but I should be ready to break it when needed.

For future updates to my weekly blog, please subscribe to my blog via the "Subscribe By Email" feature at the right.

FAQ about Windows Forms (.NET)

How can I programmatically maximize or minimize a form?


The Brushes Sample shows you how to use four different brushes in several shapes. Below is a code snippet showing how to use hatched and gradient brushes.

Rectangle rect = new Rectangle(35, 190, 100, 100);
LinearGradientBrush brush2 = new LinearGradientBrush(rect,
Color.DarkOrange, Color.Aquamarine,
LinearGradientMode.ForwardDiagonal);
g.FillEllipse(brush2, 35, 190, 100, 100);

HatchBrush brush1 = new HatchBrush(HatchStyle.DiagonalCross,
Color.DarkOrange, Color.Aquamarine);
g.FillEllipse(brush1, 35, 190, 100, 100);





How can I display a pop up a confirmation dialog when the user closes the form?


You can listen to the Form's Closing event, where you can display a MessageBox as show below:
[C#]
private void Form1_Closing(object sender, System.ComponentModel.CancelEventArgs e)
{
if (MessageBox.Show("Do you want to close the application?", "Close Application", MessageBoxButtons.YesNo) == DialogResult.No)
e.Cancel = true;

}
[VB.NET]
Private Sub Form1_Closing(ByVal sender As Object, ByVal e As System.ComponentModel.CancelEventArgs)
If MessageBox.Show("Do you want to close the application?","Close Application",MessageBoxButtons.YesNo) = DialogResult.No Then
e.Cancel = True
End If

End Sub



How can I center my form?


You can set the Form's StartPosition property to CenterScreen to achieve this.




How do I prevent users from resizing a form?


You can prevent the users from resizing a form by setting the FormBorderStyle to FixedDialog and setting the MaximizeBox property to false.



How do I programmatically set an image as Form's Icon ?


You could do so as shown in the code below :
[C#]
Form form1 = new Form();
Bitmap bmp = imageList1.Images[index] as Bitmap;
form1.Icon = Icon.FromHandle(bmp.GetHicon());

[VB.NET]
Dim form1 As Form = New Form()
Dim bmp As Bitmap = imageList1.Images(index) as Bitmap
form1.Icon = Icon.FromHandle(bmp.GetHicon())



How can I add items to the System Menu of a form.


To do this, you can use use iterop to access the GetSystemMenu and AppendMenu Win32 APIs. You also need to override the form's WndProc method to catch and act on the menu message. This idea was posted in the Microsoft newsgroups by Lion Shi.



How can I have a form with no title bar, but yet keep the resizing borders?


Set your form's Text and ControlBox properties.
myForm.Text = "";
myForm.ControlBox = false;




How can I tell if a form is closed from the controlbox (system menu) or from a call to Form.Close?


One way to do this is to override the form's WndProc method and check for WM_SYSCOMMAND and SC_CLOSE. Looking for WM_CLOSE in the override is not sufficient as WM_CLOSE is seen in both cases. A sample is available for download (C#, VB).
public const int SC_CLOSE = 0xF060;
public const int WM_SYSCOMMAND = 0x0112;

//_closeClick is a bool member of the form initially set false...
// It can be tested in the Closing event to see how the closing came about.

protected override void WndProc(ref System.Windows.Forms.Message m)
{
if(m.Msg == WM_SYSCOMMAND && (int)m.WParam == SC_CLOSE)
this._closeClick = true;

base.WndProc(ref m);
}





I have two forms. How can I access a textbox on one form from the other form?


One way to do this is to make the TextBox either a public property or a public field. Then you will be able to access it through the instance of its parent form. So, if TextBox1 is a public member of FormA and myFormA is an instance of FormA, then you can use code such as
[VB.NET]
Dim strValue as String = myFormA.TextBox1.Text

[C#]
string strValue = myFormA.TextBox1.Text;

anywhere myFormA is known.





How do I create a non-modal top level form that always stays on top of all the app's windows (like the VS.Net find dialog)?


Make your main form the "Owner" of the form in question. Refer to Form.Owner in class reference for more information.

[C#]
findReplaceDialog.Owner = this; // Your main form.
findReplaceDialog.TopLevel = false;
[VB.Net]
findReplaceDialog.Owner = Me ' Your main form.
findReplaceDialog.TopLevel = False




How can I display a form that is 'TopMost' for only my application, but not other applications?


The idea is to create the 'bound' table in your dataset, and then add an extra 'unbound' column. The steps are to derive a custom columnstyle that overrides Paint where you calculate and draw the unbound value. You can also override Edit to prevent the user from selecting your unbound column. Then to get your datagrid to use this special column style, you create a tablestyle and add the column styles to it in the order you want the columns to appear in the datagrid. Here are code snippets that derive the column and use the derived column.

// custom column style that is an unbound column
public class DataGridUnboundColumn : DataGridTextBoxColumn
{
protected override void Edit(System.Windows.Forms.CurrencyManager source, int rowNum, System.Drawing.Rectangle bounds, bool readOnly, string instantText, bool cellIsVisible)
{
//do not allow the unbound cell to become active
if(this.MappingName == "UnBound")
return;

base.Edit(source, rowNum, bounds, readOnly, instantText, cellIsVisible);
}

protected override void Paint(System.Drawing.Graphics g, System.Drawing.Rectangle bounds, System.Windows.Forms.CurrencyManager source, int rowNum, System.Drawing.Brush backBrush, System.Drawing.Brush foreBrush, bool alignToRight)
{

//clear the cell
g.FillRectangle(new SolidBrush(Color.White), bounds);

//compute & draw the value
//string s = string.Format("{0} row", rowNum);
// col 0 + 2 chars from col 1
DataGrid parent = this.DataGridTableStyle.DataGrid;
string s = parent[rowNum, 0].ToString() + ((parent[rowNum, 1].ToString())+ " ").Substring(0,2);
Font font = new Font("Arial", 8.25f);
g.DrawString(s, font, new SolidBrush(Color.Black), bounds.X, bounds.Y);
font.Dispose();

}
}


//code that uses this unbound column
private void Form1_Load(object sender, System.EventArgs e)
{
// Set the connection and sql strings
// assumes your mdb file is in your root
string connString = @"Provider=Microsoft.JET.OLEDB.4.0;data source=C:\northwind.mdb";
string sqlString = "SELECT * FROM customers";

OleDbDataAdapter dataAdapter = null;
DataSet _dataSet = null;

try
{
// Connection object
OleDbConnection connection = new OleDbConnection(connString);

// Create data adapter object
dataAdapter = new OleDbDataAdapter(sqlString, connection);

// Create a dataset object and fill with data using data adapter's Fill method
_dataSet = new DataSet();
dataAdapter.Fill(_dataSet, "customers");
connection.Close();
}
catch(Exception ex)
{
MessageBox.Show("Problem with DB access-\n\n connection: "
+ connString + "\r\n\r\n query: " + sqlString
+ "\r\n\r\n\r\n" + ex.ToString());
this.Close();
return;
}

// Create a table style that will hold the new column style
// that we set and also tie it to our customer's table from our DB
DataGridTableStyle tableStyle = new DataGridTableStyle();
tableStyle.MappingName = "customers";

// since the dataset has things like field name and number of columns,
// we will use those to create new columnstyles for the columns in our DB table
int numCols = _dataSet.Tables["customers"].Columns.Count;

//add an extra column at the end of our customers table
_dataSet.Tables["customers"].Columns.Add("Unbound");

DataGridTextBoxColumn aColumnTextColumn ;
for(int i = 0; i < numCols; ++i) { aColumnTextColumn = new DataGridTextBoxColumn(); aColumnTextColumn.HeaderText = _dataSet.Tables["customers"].Columns[i].ColumnName; aColumnTextColumn.MappingName = _dataSet.Tables["customers"].Columns[i].ColumnName; tableStyle.GridColumnStyles.Add(aColumnTextColumn); //display the extra column after column 1. if( i == 1) { DataGridUnboundColumn unboundColStyle = new DataGridUnboundColumn(); unboundColStyle.HeaderText = "UnBound"; unboundColStyle.MappingName = "UnBound"; tableStyle.GridColumnStyles.Add(unboundColStyle); } } // make the dataGrid use our new tablestyle and bind it to our table dataGrid1.TableStyles.Clear(); dataGrid1.TableStyles.Add(tableStyle); dataGrid1.DataSource = _dataSet.Tables["customers"]; } } How do I automatically resize the Form when the screen resolution changes between design-time and runtime? The framework automatically resizes the form if the current Font size during runtime is different from the font size in design-time. It however doesn't auto size when the resolution changes. But it should be easy for you to accomplish. You could derive a custom Form, provide a "ScreenResolutionBase" property that could return the current screen resolution (Screen.PrimarScreen.Bounds will give you this). This value will get serialized in code during design time. Then during runtime in the Form's OnLoad you could check for the current screen resolution and resize the Form appropriately. How can I ensure that my form will always be on the desktop? To set or control the location of the form using desktop coordinates, you can use the SetDeskTopLocation property. You can do this by setting the child form's TopMost to False and setting its Owner property to the Main Form. [C#] this.SetDesktopLocation(1,1); [VB.NET] Me.SetDesktopLocation(1,1) How can I restrict or control the size of my form? You can restrict the size of a form by setting it's MaximumSize and MinimumSize properties. This will help you control the maximum and minimum size the form can be resized to. Also note that WindowState property of the form plays a part in how the form can be resized. [C#] //Minimum width = 300, Minimum height= 300 this.MinimumSize = new Size(300, 300); //Maximum width = 800, Maximum height= unlimited this.MaximumSize = new Size(800, int.MaxValue); [VB.NET] 'Minimum width = 300, Minimum height= 300 Me.MinimumSize = New Size(300, 300) 'Maximum width = 800, Maximum height= unlimited Me.MaximumSize = New Size(800, Integer.MaxValue) How can I prevent a form from being shown in the taskbar? You need to set the form's ShowInTaskbar property to False to prevent it from being displayed in the Windows taskbar. [C#] this.ShowInTaskbar = false; [VB.NET] Me.ShowInTaskbar = False How do I prevent a user from moving a form at run time? The following code snippet (posted in the Windows Forms FAQ forums) shows how you can prevent a user from moving a form at run time: [C#] protected override void WndProc(ref Message m) { const int WM_NCLBUTTONDOWN = 161; const int WM_SYSCOMMAND = 274; const int HTCAPTION = 2; const int SC_MOVE = 61456; if((m.Msg == WM_SYSCOMMAND) && (m.WParam.ToInt32() == SC_MOVE)) { return; } if((m.Msg == WM_NCLBUTTONDOWN) && (m.WParam.ToInt32() == HTCAPTION)) { return; } base.WndProc (ref m); } [VB.NET] Protected Overrides Sub WndProc(ByRef m As Message) const Integer WM_NCLBUTTONDOWN = 161 const Integer WM_SYSCOMMAND = 274 const Integer HTCAPTION = 2 const Integer SC_MOVE = 61456 If (m.Msg = WM_SYSCOMMAND) &&(m.WParam.ToInt32() = SC_MOVE) Then Return End If If (m.Msg = WM_NCLBUTTONDOWN) &&(m.WParam.ToInt32() = HTCAPTION) Then Return End If MyBase.WndProc( m) End Sub How can I create a non rectangular form? This MSDN article titled Shaped Windows Forms and Controls in Visual Studio .NET shows how you can create non rectangular forms.




How can I make my form cover the whole screen including the TaskBar?


The following code snippet demonstrates how you can make your form cover the whole screen including the Windows Taskbar.
[C#]
// Prevent form from being resized.
this.FormBorderStyle = FormBorderStyle.FixedSingle;
// Get the screen bounds
Rectangle formrect = Screen.GetBounds(this);
// Set the form's location and size
this.Location = formrect.Location;
this.Size = formrect.Size;

[VB.NET]
' Prevent form from being resized.
Me.FormBorderStyle = FormBorderStyle.FixedSingle
' Get the screen bounds
Dim formrect As Rectangle = Screen.GetBounds(Me)
' Set the form's location and size
Me.Location = formrect.Location
Me.Size = formrect.Size







How can I move a Borderless form?


This code snippet shows how you can move a borderless form.
[C#]
public const int WM_NCLBUTTONDOWN = 0xA1;
public const int HTCAPTION = 0x2;
[DllImport("User32.dll")]
public static extern bool ReleaseCapture();
[DllImport("User32.dll")]
public static extern int SendMessage(IntPtr hWnd, int Msg, int wParam, int lParam);

private void Form1_MouseDown(object sender, System.Windows.Forms.MouseEventArgs e)
{
if (e.Button == MouseButtons.Left)
{
ReleaseCapture();
SendMessage(Handle, WM_NCLBUTTONDOWN, HTCAPTION, 0);
}
}






How do I force a Windows Form application to exit?


Your main form is an object of type System.Windows.Forms.Form. Use its Close method to exit the application. If you wish to Exit from a Form's constructor, this will not work. A workaround is to set a boolean flag that you can later check in the Form's Load method to call Close if required.

Another way is to use the Application.Exit() method.



How do I set the default button for a form?


Set the form's AcceptButton property. You can do this either through the designer, or through code such as
Form1.AcceptButton = button1;



How do I get an HWND for a form?


See the Control.Handle property which returns the HWND. Be careful if you pass this handle to some Win32 API as Windows Forms controls do their own handle management so they may recreate the handle which would leave this HWND dangling.



How can I detect if the user clicks into another window from my modal dialog?


Use the Form.Deactivate event:
this.Deactivate += new EventHandle(OnDeactivate);
//...

private void OnDeactivate(object s, EventArgs e)
{
this.Close();
}




How do I create a form with no border?


Use the Form.FormBorderStyle property to control a form's border.
public void InitMyForm()
{
// Adds a label to the form.
Label label1 = new Label();
label1.Location = new System.Drawing.Point(80,80);
label1.Name = "label1";
label1.Size = new System.Drawing.Size(132,80);
label1.Text = "Start Position Information";
this.Controls.Add(label1);

// Changes the border to Fixed3D.
FormBorderStyle = FormBorderStyle.Fixed3D;

// Displays the border information.
label1.Text = "The border is " + FormBorderStyle;
}

(From the .NET Framework SDK documentation)




How do I prevent a Form from closing when the user clicks on the close button on the form's system menu?


Handle the form's Closing event.
private void Form1_Closing(object sender, System.ComponentModel.CancelEventArgs e)
{
if( NotOkToClose() )
e.Cancel = true; //don't close
}




How do I display a splash screen type form, one with only client area (no border or titlebar)?


public void CreateMyBorderlessWindow()
{
this.FormBorderStyle = FormBorderStyle.None;
this.MaximizeBox = false;
this.MinimizeBox = false;
this.StartPosition = FormStartPosition.CenterScreen;
this.ControlBox = false;
}





How do I get the window handle (HWND) of my form or control?


Use the Control.Handle property.




How can I make sure I don't open a second instance modeless dialog that is already opened from my main form?


There are a several of ways to do this. Here are a few:

1) Insert a carriage return-linefeed, "\r\n", between your lines.
textBox1.Text = "This is line 1.\r\nThis is line 2";
// or textBox1.Text = stringvar1 + "\r\n" + stringvar2;

2) Use the Environment.NewLine property. This property is normally set to "\r\n".
textBox1.Text = "This is line 1." + Environment.NewLine + "This is line 2";

3) Use the Lines property of the TextBox. Make sure you populate your array before you set the property.
string[] arr = new string[2];
arr[0] = "this is line1";
arr[1] = "this is line 2";

textBox3.Lines = arr;








Is there a way to halt a screen from painting until all the controls on the form are initialized?


Shawn Burke responded to this question in a posting on microsoft.public.dotnet.framework.windowsforms newsgroup. There is not currently a way to do this built into the framework, but WM_SETREDRAW will do what you're looking for. It can't be called recursively, so here's code for a property you can add to your form to handle it.

private const int WM_SETREDRAW = 0xB;

[DllImport("User32")]
private static extern bool SendMessage(IntPtr hWnd, int msg, int wParam, int lParam);

private bool FreezePainting
{
get { return paintFrozen > 0; }
set {
if (value && IsHandleCreated && this.Visible)
{
if (0 == paintFrozen++)
{
SendMessage(Handle, WM_SETREDRAW, 0, 0);
}
}
if (!value)
{
if (paintFrozen == 0)
{
return;
}

if (0 == --paintFrozen)
{
SendMessage(Handle, WM_SETREDRAW, 1, 0);
Invalidate(true);
}
}
}
}




How do I return values from a form?


Add public properties to your form. Then these properties can be accessed by any object that creates an instance of your form.



How can I easily manage whether controls on my form are readonly or not?


One way is to place all the controls into a single GroupBox and then use the GroupBox.Enabled property to manage whether the controls are editable or not.






The controls that I've try to add to my form at runtime don't show up. What's wrong?


Make sure you implemented and executed code similar to the InitializeComponent method that VS adds to your Windows Forms project for controls added during design time. Recall that InitializeComponent() is called from your Forms constructor to create the controls, size, position and show the controls, and finally add the controls to the form's Controls collection. So, your code at runtime should also implement these same steps. In particular, don't forget the this.Controls.AddRange call that adds your new controls to the form's Controls collection.





How to make a form transparent?


The opacity property enables you to specify a level of transparency for the form and its child controls.

The TransparencyKey property will let you make the form transparent while keeping it's child controls visible (provided they have a different BackColor).

See the .NET documentation for Form.Opacity for differences between Opacity and TransparencyKey properties.
Opacity only works with Windows 2000 and later.





How can I create an instance of a Form class just from knowing its name in a string?


You can use the System.Reflection.Assembly.CreateInstance method to create a form from its name. Below is a code snippet. The name in the textbox has to be the full name including its namespace. So if there is a class named Form2 in namespace MyCompanyName, then the textbox would contain MyCompanyName.Form2. This snippet also assumes that the class is defined in the current executing assembly. If not, you would have to create an instance of the assembly that contains the class instead of calling the static method GetExecutingAssembly. As noted on this board, using reflection in this manner might affect performance.

[C#]
try
{
Assembly tempAssembly = Assembly.GetExecutingAssembly();
// if class is located in another DLL or EXE, use something like
// Assembly tempAssembly = Assembly.LoadFrom("myDLL.DLL");
// or
// Assembly tempAssembly = Assembly.LoadFrom("myEXE.exe");

Form frm1 = (Form) tempAssembly.CreateInstance(textBox1.Text);// as Form;
frm1.Show();
}
catch(Exception ex)
{
MessageBox.Show("Error creating: "+ textBox1.Text);
}

[VB.NET]
textBox1.Text = "MyNameSpace.Form2"
......

Try
Dim tempAssembly As System.Reflection.Assembly = System.Reflection.Assembly.GetExecutingAssembly()

' if class is located in another DLL or EXE, use something like
' tempAssembly = Assembly.LoadFrom("myDLL.DLL")
' or
' tempAssembly = Assembly.LoadFrom("myEXE.exe")

Dim frm1 As Form = CType(tempAssembly.CreateInstance(textBox1.Text), Form) ' as Form;
frm1.Show()
Catch ex As Exception
MessageBox.Show("Error creating: " + ex.ToString())
End Try



I don't want to have the Close box on my form's title bar. How do I remove this system menu box?


Set the property Form.ControlBox to false.




How do I change my application's icon?


In the Solution Explorer window, you'll see a file called app.ico in your project. This file contains your application icon. You can change this to a different file in the project properties screen which you see by right-clicking the project node in the Solution Explorer, and selecting Properties..