Skip to content

Commit 814b828

Browse files
michael-hawkermichael-hawker
authored
Merge pull request #302 from Sergio0694/feature/guard-apis
Guard APIs docs
2 parents d180512 + a919c11 commit 814b828

File tree

2 files changed

+137
-0
lines changed

2 files changed

+137
-0
lines changed

‎docs/developer-tools/Guard.md

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
---
2+
title: Guard
3+
author: Sergio0694
4+
description: Helper methods to verify conditions when running code
5+
keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, debug, net core, net standard
6+
dev_langs:
7+
- csharp
8+
---
9+
10+
# Guard
11+
12+
The [Guard](https://docs.microsoft.com/dotnet/api/microsoft.toolkit.diagnostics.guard) can be used to validate method arguments in a streamlined manner, which is also faster, less verbose, more expressive and less error prone than manually writing checks and throwing exceptions.
13+
14+
## How it works
15+
16+
These `Guard` APIs are built with three core principles in mind:
17+
18+
- Being **fast**. To achieve that, all the APIs have been designed to produce as little code as possible in the caller, and each single Guard API will (almost always) be inlined. Furthermore, specialized methods are generated with T4 templates to achieve the most efficient assembly code possible when working with common types (eg. primitive numeric types).
19+
- Being **helpful**. Each `Guard` API produces a detailed exception message that clearly specifies what went wrong, along with additional info (eg. current variable values), when applicable.
20+
- Being **intuitive**. To achieve this, all the `Guard` APIs have expressive and self-explanatory names that make it immediately clear what each API is supposed to do. This shifts the burden of writing checks away from the developers, letting them express conditions using natural language.
21+
22+
## Syntax
23+
24+
Here is a sample method, with some checks being done with explicitly and with manual throw statements:
25+
26+
```csharp
27+
public static void SampleMethod(int[] array, int index, Span<int> span, string text)
28+
{
29+
if (array is null)
30+
{
31+
throw new ArgumentNullException(nameof(array), "The array must not be null");
32+
}
33+
34+
if (array.Length >= 10)
35+
{
36+
throw new ArgumentException($"The array must have less than 10 items, had a size of {array.Length}", nameof(array));
37+
}
38+
39+
if (index < 0 || index >= array.Length)
40+
{
41+
throw new ArgumentOutOfRangeException(nameof(index), $"The index must be in the [0, {array.Length}) range, was {index}");
42+
}
43+
44+
if (span.Length < array.Length)
45+
{
46+
throw new ArgumentException($"The target span is shorter than the input array, had a length of {span.Length}", nameof(span));
47+
}
48+
49+
if (string.IsNullOrEmpty(text))
50+
{
51+
throw new ArgumentException("The input text can't be null or empty", nameof(text));
52+
}
53+
}
54+
```
55+
56+
And here is the same method, but using the new `Guard.APIs` to validate the input arguments:
57+
58+
```csharp
59+
public static void SampleMethod(int[] array, int index, Span<int> span, string text)
60+
{
61+
Guard.IsNotNull(array, nameof(array));
62+
Guard.HasSizeGreaterThanOrEqualTo(array, 10, nameof(array));
63+
Guard.IsInRangeFor(index, array, nameof(index));
64+
Guard.HasSizeLessThanOrEqualTo(array, span, nameof(span));
65+
Guard.IsNotNullOrEmpty(text, nameof(text));
66+
}
67+
```
68+
69+
The `Guard` APIs will perform the required checks in the fastest way possible, and will throw the appropriate exception with a well formated message if they fail.
70+
71+
## Methods
72+
73+
There are dozens of different APIs and overloads in the `Guard` class, here are a few of them:
74+
75+
### General
76+
77+
| Methods | Return Type | Description |
78+
| -- | -- | -- |
79+
| IsNotNull&lt;T>(T, string) | void | Asserts that the input value is not null |
80+
| IsOfType&lt;T>(object, string) | void | Asserts that the input value is of a specific type |
81+
| IsAssignableToType&lt;T>(object, string) | void | Asserts that the input value can be assigned to a specified type |
82+
| IsReferenceEqualTo&lt;T>(T, T, string) | void | Asserts that the input value must be the same instance as the target value |
83+
| IsTrue(bool, string) | void | Asserts that the input value must be true |
84+
85+
### Comparisons
86+
87+
| Methods | Return Type | Description |
88+
| -- | -- | -- |
89+
| IsEqualTo&lt;T>(T, T, string) | void | Asserts that the input value must be equal to a specified value |
90+
| IsBitwiseEqualTo&lt;T>(T, T, string) | void | Asserts that the input value must be a bitwise match with a specified value |
91+
| IsLessThan&lt;T>(T, T, string) | void | Asserts that the input value must be less than a specified value |
92+
| IsLessThanOrEqualTo&lt;T>(T, T, string) | void | Asserts that the input value must be less than or equal to a specified value |
93+
| IsInRange&lt;T>(T, T, T, string) | void | Asserts that the input value must be in the [minimum, maximum) range |
94+
| IsBetween&lt;T>(T, T, T, string name) | void | Asserts that the input value must be in the (minimum, maximum) interval |
95+
| IsBetweenOrEqualTo&lt;T>(T, T, T, string name) | void | Asserts that the input value must be in the [minimum, maximum] interval |
96+
97+
### Strings
98+
99+
| Methods | Return Type | Description |
100+
| -- | -- | -- |
101+
| IsNotNullOrEmpty(string, string) | void | Asserts that the input string instance must not be null or empty |
102+
| IsNotNullOrWhitespace(string, string) | void | Asserts that the input string instance must not be null or whitespace |
103+
104+
### Collections
105+
106+
| Methods | Return Type | Description |
107+
| -- | -- | -- |
108+
| IsNotEmpty&lt;T>(T[], string) | void | Asserts that the input array instance must not be empty |
109+
| HasSizeEqualTo&lt;T>(T[], int, string) | void | Asserts that the input array instance must have a size of a specified value |
110+
| HasSizeAtLeast&lt;T>(T[], int, string) | void | Asserts that the input array must have a size of at least or equal to a specified value |
111+
| IsInRangeFor&lt;T>(int, T[], string) | void | Asserts that the input index is valid for a given array |
112+
| HasSizeLessThanOrEqualTo&lt;T>(T[], T[], string) | void | Asserts that the source array must have a size of less than or equal to that of the destination array |
113+
114+
### Tasks
115+
116+
| Methods | Return Type | Description |
117+
| -- | -- | -- |
118+
| IsCompleted(Task, string) | void | Asserts that the input task is in a completed state |
119+
| IsNotCanceled(Task, string) | void | Asserts that the input task is not canceled |
120+
121+
## Sample Code
122+
123+
You can find more examples in our [unit tests](https://github.com/Microsoft/WindowsCommunityToolkit//blob/master/UnitTests/Diagnostics/Test_Guard.cs)
124+
125+
## Requirements
126+
127+
| Implementation | .NET Standard 2.0 |
128+
| --- | --- |
129+
| Namespace | Microsoft.Toolkit.Diagnostics |
130+
| NuGet package | [Microsoft.Toolkit](https://www.nuget.org/packages/Microsoft.Toolkit/) |
131+
132+
The Guard class supports .NET Standard
133+
134+
## API
135+
136+
* [Guard source code](https://github.com/Microsoft/WindowsCommunityToolkit//blob/master/Microsoft.Toolkit/Diagnostics)

‎docs/toc.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -187,6 +187,7 @@
187187
# Developer tools
188188
## [AlignmentGrid](developer-tools/AlignmentGrid.md)
189189
## [FocusTracker](developer-tools/FocusTracker.md)
190+
## [Guard](developer-tools/Guard.md)
190191

191192
# [GazeInteractionLibrary](gaze/GazeInteractionLibrary.md)
192193

0 commit comments

Comments
 (0)