You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/diagnostics/Guard.md
+40-40Lines changed: 40 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,29 +1,29 @@
1
1
---
2
-
title: Guard
2
+
title: Guard class
3
3
author: Sergio0694
4
4
description: Helper methods to verify conditions when running code
5
5
keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, debug, net core, net standard
6
6
dev_langs:
7
7
- csharp
8
8
---
9
9
10
-
# Guard
10
+
# Guard class
11
11
12
-
The [Guard](/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 errorprone than manually writing checks and throwing exceptions.
12
+
Use the [Guard class](/dotnet/api/microsoft.toolkit.diagnostics.guard) to validate method arguments in a streamlined manner. This class is faster, less verbose, more expressive, and less error-prone than manually writing checks and throwing exceptions.
These`Guard` APIs are built with three core principles in mind:
18
+
The`Guard` APIs are built with three core principles in mind:
19
19
20
20
- 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).
21
21
- 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.
22
22
- 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.
23
23
24
24
## Syntax
25
25
26
-
Here is a sample method, with some checks being done with explicitly and with manual throw statements:
26
+
The following code snippet shows a sample method, with some checks being done explicitly and manual throw statements:
@@ -68,60 +68,60 @@ public static void SampleMethod(int[] array, int index, Span<int> span, string t
68
68
}
69
69
```
70
70
71
-
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.
71
+
The `Guard` APIs perform the required checks in the fastest way possible, and throw the appropriate exception with a well-formatted message if they fail.
72
72
73
73
> [!NOTE]
74
-
> The `Guard` APIs rely on [`[CallerArgumentExpression]`](/dotnet/csharp/language-reference/proposals/csharp-10.0/caller-argument-expression) to automatically infer the name of the argument being validated. This requires C# 10 to be enabled in the project in use. If you're using a lower version of the language, you will need to manually pass the parameter name, for instance using `nameof()` to refer to it (eg.`Guard.IsNotNull(array, nameof(array)))`).
74
+
> The `Guard` APIs rely on [`[CallerArgumentExpression]`](/dotnet/csharp/language-reference/proposals/csharp-10.0/caller-argument-expression) to automatically infer the name of the argument being validated. This requires C# 10 to be enabled in the project. If you're using a lower version of the language, you need to manually pass the parameter name, for instance using `nameof()` to refer to it (for example,`Guard.IsNotNull(array, nameof(array)))`).
75
75
76
76
## Methods
77
77
78
-
There are dozens of different APIs and overloads in the `Guard` class, here are a few of them:
78
+
There are dozens of different APIs and overloads in the `Guard` class. The following table describes some of them.
79
79
80
80
### General
81
81
82
-
| Methods | Return Type| Description |
83
-
| -- | -- | -- |
84
-
| IsNotNull<T>(T, string)| void | Asserts that the input value is not null |
85
-
| IsOfType<T>(object, string) | void | Asserts that the input value is of a specific type |
86
-
| IsAssignableToType<T>(object, string) | void | Asserts that the input value can be assigned to a specified type |
87
-
| IsReferenceEqualTo<T>(T, T, string) | void | Asserts that the input value must be the same instance as the target value |
88
-
| IsTrue(bool, string)| void | Asserts that the input value must be true |
|`IsNotNullOrEmpty(string, string)`| void| Asserts that the input string instance must not be null or empty |
107
+
|`IsNotNullOrWhiteSpace(string, string)`| void | Asserts that the input string instance must not be null or whitespace |
108
108
109
109
### Collections
110
110
111
-
| Methods | Return Type| Description |
112
-
| -- | -- | -- |
113
-
| IsNotEmpty<T>(T[], string)| void | Asserts that the input array instance must not be empty |
114
-
| HasSizeEqualTo<T>(T[], int, string) | void | Asserts that the input array instance must have a size of a specified value |
115
-
| HasSizeAtLeast<T>(T[], int, string) | void | Asserts that the input array must have a size of at least or equal to a specified value |
116
-
| IsInRangeFor<T>(int, T[], string)| void | Asserts that the input index is valid for a given array |
117
-
| HasSizeLessThanOrEqualTo<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 |
|`IsNotEmpty<T>(T[], string)`| void| Asserts that the input array instance must not be empty |
114
+
|`HasSizeEqualTo<T>(T[], int, string)`| void| Asserts that the input array instance must have a size of a specified value |
115
+
|`HasSizeAtLeast<T>(T[], int, string)`| void| Asserts that the input array must have a size of at least or equal to a specified value |
116
+
|`IsInRangeFor<T>(int, T[], string)`| void| Asserts that the input index is valid for a given array |
117
+
|`HasSizeLessThanOrEqualTo<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 |
118
118
119
119
### Tasks
120
120
121
-
| Methods | Return Type| Description |
122
-
| -- | -- | -- |
123
-
| IsCompleted(Task, string)| void | Asserts that the input task is in a completed state |
124
-
| IsNotCanceled(Task, string) | void | Asserts that the input task is not canceled |
Copy file name to clipboardExpand all lines: docs/diagnostics/Introduction.md
+7-7Lines changed: 7 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,23 +1,23 @@
1
1
---
2
2
title: Introduction to the Diagnostics package
3
+
ms.date: 03/13/2026
3
4
author: Sergio0694
4
5
description: An overview of how to get started with the Diagnostics package and to the APIs it contains
5
6
keywords: windows 10, uwp, windows community toolkit, uwp community toolkit, uwp toolkit, .net community toolkit, csharp, get started, visual studio, diagnostics, exceptions, contract, net core, net standard
6
7
---
7
8
8
9
# Introduction to the Diagnostics package
9
10
10
-
The `CommunityToolkit.Diagnostics` package contains APIs to efficiently validate method parameters and to throw exceptions in faulting code paths. It is meant to be used to help simplify all argument checks and to make them more expressive and easier to read, while at the same time improving codegen quality and performance.
11
+
The [📦 CommunityToolkit.Diagnostics package](https://www.nuget.org/packages/CommunityToolkit.Diagnostics) contains APIs to efficiently validate method parameters and to throw exceptions in faulting code paths. It's meant to be used to help simplify all argument checks and to make them more expressive and easier to read, while at the same time improving codegen quality and performance.
11
12
12
-
This package can be installed through NuGet, and it has the following multi-targets:
13
+
This package can be installed through NuGet, and it has the following multitargets:
13
14
14
15
- .NET Standard 2.0
15
-
- .NET Standard 2.1
16
-
- .NET 6
16
+
- .NET 8
17
17
18
-
This means the package can be used on any available runtime (including .NET Framework, .NET Core, UWP, Unity, Xamarin, Uno, Blazor, etc.). The API surface is almost identical in all cases, while the internal implementation can be optimized when newer APIs are available. The Diagnostics package as a whole is meant to be self-contained and extremely small in scope and binary size.
18
+
This means the package can be used on any available runtime (including .NET Framework, .NET, UWP, Unity, Xamarin, Uno, and Blazor). The API surface is almost identical in all cases, while the internal implementation can be optimized when newer APIs are available. The Diagnostics package as a whole is meant to be self-contained and extremely small in scope and binary size.
19
19
20
-
## Getting started
20
+
## Get started
21
21
22
22
To install the package from within Visual Studio:
23
23
@@ -37,4 +37,4 @@ To install the package from within Visual Studio:
0 commit comments