diff --git a/docs/csharp/programming-guide/classes-and-structs/destructors.md b/docs/csharp/programming-guide/classes-and-structs/destructors.md index 71c9941e805b9..64866e31b0fc5 100644 --- a/docs/csharp/programming-guide/classes-and-structs/destructors.md +++ b/docs/csharp/programming-guide/classes-and-structs/destructors.md @@ -58,7 +58,7 @@ protected override void Finalize() It is possible to force garbage collection by calling , but most of the time, this should be avoided because it may create performance issues. ## Using finalizers to release resources - In general, C# does not require as much memory management as is needed when you develop with a language that does not target a runtime with garbage collection. This is because the .NET Framework garbage collector implicitly manages the allocation and release of memory for your objects. However, when your application encapsulates unmanaged resources such as windows, files, and network connections, you should use finalizers to free those resources. When the object is eligible for finalization, the garbage collector runs the `Finalize` method of the object. + In general, C# does not require as much memory management as is needed when you develop with a language that does not target a runtime with garbage collection. This is because the .NET garbage collector implicitly manages the allocation and release of memory for your objects. However, when your application encapsulates unmanaged resources, such as windows, files, and network connections, you should use finalizers to free those resources. When the object is eligible for finalization, the garbage collector runs the `Finalize` method of the object. ## Explicit release of resources If your application is using an expensive external resource, we also recommend that you provide a way to explicitly release the resource before the garbage collector frees the object. You do this by implementing a `Dispose` method from the interface that performs the necessary cleanup for the object. This can considerably improve the performance of the application. Even with this explicit control over resources, the finalizer becomes a safeguard to clean up resources if the call to the `Dispose` method failed. diff --git a/docs/csharp/programming-guide/classes-and-structs/extension-methods.md b/docs/csharp/programming-guide/classes-and-structs/extension-methods.md index 751ba624581ad..84d5eb7d8fda1 100644 --- a/docs/csharp/programming-guide/classes-and-structs/extension-methods.md +++ b/docs/csharp/programming-guide/classes-and-structs/extension-methods.md @@ -92,7 +92,7 @@ static class DomainEntityExtensions ### Extending Predefined Types -Rather than creating new objects when reusable functionality needs to be created, we can often extend an existing type such as a .NET Framework or CLR type. As an example, if we don't use extension methods, we might create an `Engine` or `Query` class to do the work of executing a query on a SQL Server that may be called from multiple places in our code. However we can instead extend the class using extension methods to perform that query from anywhere we have a connection to a SQL Server. Other examples might be to add common functionality to the class, extend the data processing capabilities of the and objects, and objects for specific error handling functionality. These types of use-cases are limited only by your imagination and good sense. +Rather than creating new objects when reusable functionality needs to be created, we can often extend an existing type, such as a .NET or CLR type. As an example, if we don't use extension methods, we might create an `Engine` or `Query` class to do the work of executing a query on a SQL Server that may be called from multiple places in our code. However we can instead extend the class using extension methods to perform that query from anywhere we have a connection to a SQL Server. Other examples might be to add common functionality to the class, extend the data processing capabilities of the and objects, and objects for specific error handling functionality. These types of use-cases are limited only by your imagination and good sense. Extending predefined types can be difficult with `struct` types because they're passed by value to methods. That means any changes to the struct are made to a copy of the struct. Those changes aren't visible once the extension method exits. Beginning with C# 7.2, you can add the `ref` modifier to the first argument of an extension method. Adding the `ref` modifier means the first argument is passed by reference. This enables you to write extension methods that change the state of the struct being extended. @@ -109,7 +109,7 @@ If you do implement extension methods for a given type, remember the following p - An extension method will never be called if it has the same signature as a method defined in the type. - Extension methods are brought into scope at the namespace level. For example, if you have multiple static classes that contain extension methods in a single namespace named `Extensions`, they'll all be brought into scope by the `using Extensions;` directive. -For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. If you want to add significant functionality to a library for which you own the source code, you should follow the standard .NET Framework guidelines for assembly versioning. For more information, see [Assembly Versioning](../../../standard/assembly/versioning.md). +For a class library that you implemented, you shouldn't use extension methods to avoid incrementing the version number of an assembly. If you want to add significant functionality to a library for which you own the source code, follow the .NET guidelines for assembly versioning. For more information, see [Assembly Versioning](../../../standard/assembly/versioning.md). ## See also diff --git a/docs/csharp/programming-guide/classes-and-structs/how-to-implement-and-call-a-custom-extension-method.md b/docs/csharp/programming-guide/classes-and-structs/how-to-implement-and-call-a-custom-extension-method.md index cd17d9c6afed3..49c9890e00f4d 100644 --- a/docs/csharp/programming-guide/classes-and-structs/how-to-implement-and-call-a-custom-extension-method.md +++ b/docs/csharp/programming-guide/classes-and-structs/how-to-implement-and-call-a-custom-extension-method.md @@ -29,7 +29,7 @@ This topic shows how to implement your own extension methods for any .NET type. [!code-csharp[csProgGuideExtensionMethods#1](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideExtensionMethods/cs/extensionmethods.cs#1)] -## .NET Framework Security +## .NET Security Extension methods present no specific security vulnerabilities. They can never be used to impersonate existing methods on a type, because all name collisions are resolved in favor of the instance or static method defined by the type itself. Extension methods cannot access any private data in the extended class. ## See also diff --git a/docs/csharp/programming-guide/classes-and-structs/implicitly-typed-local-variables.md b/docs/csharp/programming-guide/classes-and-structs/implicitly-typed-local-variables.md index e562169fb1b87..634bb6a49cfaa 100644 --- a/docs/csharp/programming-guide/classes-and-structs/implicitly-typed-local-variables.md +++ b/docs/csharp/programming-guide/classes-and-structs/implicitly-typed-local-variables.md @@ -8,7 +8,7 @@ ms.assetid: b9218fb2-ef5d-4814-8a8e-2bc29b0bbc9b --- # Implicitly typed local variables (C# Programming Guide) -Local variables can be declared without giving an explicit type. The `var` keyword instructs the compiler to infer the type of the variable from the expression on the right side of the initialization statement. The inferred type may be a built-in type, an anonymous type, a user-defined type, or a type defined in the .NET Framework class library. For more information about how to initialize arrays with `var`, see [Implicitly Typed Arrays](../arrays/implicitly-typed-arrays.md). +Local variables can be declared without giving an explicit type. The `var` keyword instructs the compiler to infer the type of the variable from the expression on the right side of the initialization statement. The inferred type may be a built-in type, an anonymous type, a user-defined type, or a type defined in the .NET class library. For more information about how to initialize arrays with `var`, see [Implicitly Typed Arrays](../arrays/implicitly-typed-arrays.md). The following examples show various ways in which local variables can be declared with `var`: diff --git a/docs/csharp/programming-guide/classes-and-structs/index.md b/docs/csharp/programming-guide/classes-and-structs/index.md index 60f1765149ae5..4b4e5d8653bd5 100644 --- a/docs/csharp/programming-guide/classes-and-structs/index.md +++ b/docs/csharp/programming-guide/classes-and-structs/index.md @@ -11,8 +11,9 @@ helpviewer_keywords: - "C# language, classes" ms.assetid: cc39dbda-8754-423e-b5b1-16a1db0734c0 --- -# Classes and Structs (C# Programming Guide) -Classes and structs are two of the basic constructs of the common type system in the .NET Framework. Each is essentially a data structure that encapsulates a set of data and behaviors that belong together as a logical unit. The data and behaviors are the *members* of the class or struct, and they include its methods, properties, and events, and so on, as listed later in this topic. +# Classes and structs (C# programming guide) + +Classes and structs are two of the basic constructs of the common type system in .NET. Each is essentially a data structure that encapsulates a set of data and behaviors that belong together as a logical unit. The data and behaviors are the *members* of the class or struct, and they include its methods, properties, and events, and so on, as listed later in this topic. A class or struct declaration is like a blueprint that is used to create instances or objects at run time. If you define a class or struct called `Person`, `Person` is the name of the type. If you declare and initialize a variable `p` of type `Person`, `p` is said to be an object or instance of `Person`. Multiple instances of the same `Person` type can be created, and each instance can have different values in its properties and fields. @@ -25,7 +26,7 @@ Classes and structs are two of the basic constructs of the common type system in For more information, see [Classes](./classes.md), [Objects](./objects.md), and [Structure types](../../language-reference/builtin-types/struct.md). ## Example - In the following example, `CustomClass` in the `ProgrammingGuide` namespace has three members: an instance constructor, a property named `Number`, and a method named `Multiply`. The `Main` method in the `Program` class creates an instance (object) of `CustomClass`, and the object’s method and property are accessed by using dot notation. + In the following example, `CustomClass` in the `ProgrammingGuide` namespace has three members: an instance constructor, a property named `Number`, and a method named `Multiply`. The `Main` method in the `Program` class creates an instance (object) of `CustomClass`, and the object's method and property are accessed by using dot notation. [!code-csharp[csProgGuideObjects#1](../../../../samples/snippets/csharp/programming-guide/classes-and-structs/class1.cs#1)] diff --git a/docs/csharp/programming-guide/classes-and-structs/objects.md b/docs/csharp/programming-guide/classes-and-structs/objects.md index 350b1f31fd46a..9d2607ff7ab08 100644 --- a/docs/csharp/programming-guide/classes-and-structs/objects.md +++ b/docs/csharp/programming-guide/classes-and-structs/objects.md @@ -23,7 +23,7 @@ A class or struct definition is like a blueprint that specifies what the type ca [!code-csharp[csProgGuideStatements#31](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideStatements/CS/Statements.cs#31)] - The memory for both `p1` and `p2` is allocated on the thread stack. That memory is reclaimed along with the type or method in which it is declared. This is one reason why structs are copied on assignment. By contrast, the memory that is allocated for a class instance is automatically reclaimed (garbage collected) by the common language runtime when all references to the object have gone out of scope. It is not possible to deterministically destroy a class object like you can in C++. For more information about garbage collection in the .NET Framework, see [Garbage Collection](../../../standard/garbage-collection/index.md). + The memory for both `p1` and `p2` is allocated on the thread stack. That memory is reclaimed along with the type or method in which it is declared. This is one reason why structs are copied on assignment. By contrast, the memory that is allocated for a class instance is automatically reclaimed (garbage collected) by the common language runtime when all references to the object have gone out of scope. It is not possible to deterministically destroy a class object like you can in C++. For more information about garbage collection in .NET, see [Garbage Collection](../../../standard/garbage-collection/index.md). > [!NOTE] > The allocation and deallocation of memory on the managed heap is highly optimized in the common language runtime. In most cases there is no significant difference in the performance cost of allocating a class instance on the heap versus allocating a struct instance on the stack. diff --git a/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md b/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md index c3e8d0a83f37c..febcd4b256618 100644 --- a/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md +++ b/docs/csharp/programming-guide/classes-and-structs/static-classes-and-static-class-members.md @@ -17,7 +17,7 @@ A [static](../../language-reference/keywords/static.md) class is basically the s UtilityClass.MethodA(); ``` - A static class can be used as a convenient container for sets of methods that just operate on input parameters and do not have to get or set any internal instance fields. For example, in the .NET Framework Class Library, the static class contains methods that perform mathematical operations, without any requirement to store or retrieve data that is unique to a particular instance of the class. That is, you apply the members of the class by specifying the class name and the method name, as shown in the following example. + A static class can be used as a convenient container for sets of methods that just operate on input parameters and do not have to get or set any internal instance fields. For example, in the .NET Class Library, the static class contains methods that perform mathematical operations, without any requirement to store or retrieve data that is unique to a particular instance of the class. That is, you apply the members of the class by specifying the class name and the method name, as shown in the following example. ```csharp double dub = -3.14; @@ -31,7 +31,7 @@ Console.WriteLine(Math.Round(Math.Abs(dub))); // 3 ``` - As is the case with all class types, the type information for a static class is loaded by the .NET Framework common language runtime (CLR) when the program that references the class is loaded. The program cannot specify exactly when the class is loaded. However, it is guaranteed to be loaded and to have its fields initialized and its static constructor called before the class is referenced for the first time in your program. A static constructor is only called one time, and a static class remains in memory for the lifetime of the application domain in which your program resides. + As is the case with all class types, the type information for a static class is loaded by the .NET runtime when the program that references the class is loaded. The program cannot specify exactly when the class is loaded. However, it is guaranteed to be loaded and to have its fields initialized and its static constructor called before the class is referenced for the first time in your program. A static constructor is only called one time, and a static class remains in memory for the lifetime of the application domain in which your program resides. > [!NOTE] > To create a non-static class that allows only one instance of itself to be created, see [Implementing Singleton in C#](https://docs.microsoft.com/previous-versions/msp-n-p/ff650316%28v=pandp.10%29). diff --git a/docs/csharp/programming-guide/concepts/async/handling-reentrancy-in-async-apps.md b/docs/csharp/programming-guide/concepts/async/handling-reentrancy-in-async-apps.md index 7901ccd6e1d44..6b6b65b5e058e 100644 --- a/docs/csharp/programming-guide/concepts/async/handling-reentrancy-in-async-apps.md +++ b/docs/csharp/programming-guide/concepts/async/handling-reentrancy-in-async-apps.md @@ -25,7 +25,7 @@ When you include asynchronous code in your app, you should consider and possibly > To run the example, you must have Visual Studio 2012 or newer and .NET Framework 4.5 or newer installed on your computer. > [!NOTE] -> Transport Layer Security (TLS) version 1.2 is now the minimum version to use in your app development. If your app targets a .NET Framework version earlier than 4.7, refer to the following article for [Transport Layer Security (TLS) best practices with the .NET Framework](../../../../framework/network-programming/tls.md). +> Transport Layer Security (TLS) version 1.2 is now the minimum version to use in your app development. If your app targets a .NET Framework version earlier than 4.7, refer to the following article for [Transport Layer Security (TLS) best practices with .NET Framework](../../../../framework/network-programming/tls.md). ## Recognizing Reentrancy @@ -132,7 +132,7 @@ private async void StartButton_Click(object sender, RoutedEventArgs e) } ``` -As a result of the changes, the button doesn't respond while `AccessTheWebAsync` is downloading the websites, so the process can’t be reentered. +As a result of the changes, the button doesn't respond while `AccessTheWebAsync` is downloading the websites, so the process can't be reentered. ### Cancel and Restart the Operation @@ -142,7 +142,7 @@ For more information about cancellation, see [Fine-Tuning Your Async Application To set up this scenario, make the following changes to the basic code that is provided in [Reviewing and Running the Example App](#BKMD_SettingUpTheExample). You can also download the finished app from [Async Samples: Reentrancy in .NET Desktop Apps](https://code.msdn.microsoft.com/Async-Sample-Preventing-a8489f06). The name of the project is CancelAndRestart. -1. Declare a variable, `cts`, that’s in scope for all methods. +1. Declare a variable, `cts`, that's in scope for all methods. ```csharp public partial class MainWindow : Window // Or class MainPage @@ -223,7 +223,7 @@ In `AccessTheWebAsync`, make the following changes. - Use the method to download the websites because `GetAsync` accepts a argument. -- Before calling `DisplayResults` to display the results for each downloaded website, check `ct` to verify that the current operation hasn’t been canceled. +- Before calling `DisplayResults` to display the results for each downloaded website, check `ct` to verify that the current operation hasn't been canceled. The following code shows these changes, which are marked with asterisks. @@ -530,7 +530,7 @@ The output shows the following patterns. TOTAL bytes returned: 915908 ``` -- The `pendingWork` task is null at the start of `FinishOneGroupAsync` only for group A, which started first. Group A hasn’t yet completed an await expression when it reaches `FinishOneGroupAsync`. Therefore, control hasn't returned to `AccessTheWebAsync`, and the first assignment to `pendingWork` hasn't occurred. +- The `pendingWork` task is null at the start of `FinishOneGroupAsync` only for group A, which started first. Group A hasn't yet completed an await expression when it reaches `FinishOneGroupAsync`. Therefore, control hasn't returned to `AccessTheWebAsync`, and the first assignment to `pendingWork` hasn't occurred. - The following two lines always appear together in the output. The code is never interrupted between starting a group's operation in `StartButton_Click` and assigning a task for the group to `pendingWork`. @@ -578,13 +578,13 @@ The following section provides the code to build the example as a WPF app. 4. In the list of project types, choose **WPF Application**. -5. Name the project `WebsiteDownloadWPF`, choose .NET Framework version of 4.6 or higher and then click the **OK** button. +5. Name the project `WebsiteDownloadWPF`, choose .NET Framework version of 4.6 or higher, and then click the **OK** button. The new project appears in **Solution Explorer**. 6. In the Visual Studio Code Editor, choose the **MainWindow.xaml** tab. - If the tab isn’t visible, open the shortcut menu for MainWindow.xaml in **Solution Explorer**, and then choose **View Code**. + If the tab isn't visible, open the shortcut menu for MainWindow.xaml in **Solution Explorer**, and then choose **View Code**. 7. In the **XAML** view of MainWindow.xaml, replace the code with the following code. diff --git a/docs/csharp/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md b/docs/csharp/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md index 19faaa5afd2b1..2719bff703e6d 100644 --- a/docs/csharp/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md +++ b/docs/csharp/programming-guide/concepts/async/how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md @@ -4,13 +4,13 @@ ms.date: 07/20/2015 ms.assetid: 19745899-f97a-4499-a7c7-e813d1447580 --- # How to make multiple web requests in parallel by using async and await (C#) -In an async method, tasks are started when they’re created. The [await](../../../language-reference/operators/await.md) operator is applied to the task at the point in the method where processing can’t continue until the task finishes. Often a task is awaited as soon as it’s created, as the following example shows. +In an async method, tasks are started when they're created. The [await](../../../language-reference/operators/await.md) operator is applied to the task at the point in the method where processing can't continue until the task finishes. Often a task is awaited as soon as it's created, as the following example shows. ```csharp var result = await someWebAccessMethodAsync(url); ``` - However, you can separate creating the task from awaiting the task if your program has other work to accomplish that doesn’t depend on the completion of the task. + However, you can separate creating the task from awaiting the task if your program has other work to accomplish that doesn't depend on the completion of the task. ```csharp // The following line creates and starts the task. @@ -26,7 +26,7 @@ var result = await myTask; Between starting a task and awaiting it, you can start other tasks. The additional tasks implicitly run in parallel, but no additional threads are created. - The following program starts three asynchronous web downloads and then awaits them in the order in which they’re called. Notice, when you run the program, that the tasks don’t always finish in the order in which they’re created and awaited. They start to run when they’re created, and one or more of the tasks might finish before the method reaches the await expressions. + The following program starts three asynchronous web downloads and then awaits them in the order in which they're called. Notice, when you run the program, that the tasks don't always finish in the order in which they're created and awaited. They start to run when they're created, and one or more of the tasks might finish before the method reaches the await expressions. > [!NOTE] > To complete this project, you must have Visual Studio 2012 or higher and the .NET Framework 4.5 or higher installed on your computer. @@ -130,7 +130,7 @@ var result = await myTask; 5. Choose the F5 key to run the program, and then choose the **Start** button. - Run the program several times to verify that the three tasks don’t always finish in the same order and that the order in which they finish isn't necessarily the order in which they’re created and awaited. + Run the program several times to verify that the three tasks don't always finish in the same order and that the order in which they finish isn't necessarily the order in which they're created and awaited. ## Example The following code contains the full example. diff --git a/docs/csharp/programming-guide/concepts/async/task-asynchronous-programming-model.md b/docs/csharp/programming-guide/concepts/async/task-asynchronous-programming-model.md index c2610fe411869..dc0a15768b0a8 100644 --- a/docs/csharp/programming-guide/concepts/async/task-asynchronous-programming-model.md +++ b/docs/csharp/programming-guide/concepts/async/task-asynchronous-programming-model.md @@ -32,7 +32,7 @@ The async-based approach adds the equivalent of an automatic transmission to the ## Async methods are easier to write -The [async](../../../language-reference/keywords/async.md) and [await](../../../language-reference/operators/await.md) keywords in C# are the heart of async programming. By using those two keywords, you can use resources in the .NET Framework, .NET Core, or the Windows Runtime to create an asynchronous method almost as easily as you create a synchronous method. Asynchronous methods that you define by using the `async` keyword are referred to as *async methods*. +The [async](../../../language-reference/keywords/async.md) and [await](../../../language-reference/operators/await.md) keywords in C# are the heart of async programming. By using those two keywords, you can use resources in .NET Framework, .NET Core, or the Windows Runtime to create an asynchronous method almost as easily as you create a synchronous method. Asynchronous methods that you define by using the `async` keyword are referred to as *async methods*. The following example shows an async method. Almost everything in the code should look completely familiar to you. @@ -98,7 +98,7 @@ The following characteristics summarize what makes the previous example an async In async methods, you use the provided keywords and types to indicate what you want to do, and the compiler does the rest, including keeping track of what must happen when control returns to an await point in a suspended method. Some routine processes, such as loops and exception handling, can be difficult to handle in traditional asynchronous code. In an async method, you write these elements much as you would in a synchronous solution, and the problem is solved. -For more information about asynchrony in previous versions of the .NET Framework, see [TPL and Traditional .NET Framework Asynchronous Programming](../../../../standard/parallel-programming/tpl-and-traditional-async-programming.md). +For more information about asynchrony in previous versions of .NET Framework, see [TPL and Traditional .NET Framework Asynchronous Programming](../../../../standard/parallel-programming/tpl-and-traditional-async-programming.md). ## What happens in an async method @@ -138,7 +138,7 @@ For more information about control flow, see [Control Flow in Async Programs (C# ## API async methods -You might be wondering where to find methods such as `GetStringAsync` that support async programming. The .NET Framework 4.5 or higher and .NET Core contain many members that work with `async` and `await`. You can recognize them by the "Async" suffix that's appended to the member name, and by their return type of or . For example, the `System.IO.Stream` class contains methods such as , , and alongside the synchronous methods , , and . +You might be wondering where to find methods such as `GetStringAsync` that support async programming. .NET Framework 4.5 or higher and .NET Core contain many members that work with `async` and `await`. You can recognize them by the "Async" suffix that's appended to the member name, and by their return type of or . For example, the `System.IO.Stream` class contains methods such as , , and alongside the synchronous methods , , and . The Windows Runtime also contains many methods that you can use with `async` and `await` in Windows apps. For more information, see [Threading and async programming](/windows/uwp/threading-async/) for UWP development, and [Asynchronous programming (Windows Store apps)](https://docs.microsoft.com/previous-versions/windows/apps/hh464924(v=win.10)) and [Quickstart: Calling asynchronous APIs in C# or Visual Basic](https://docs.microsoft.com/previous-versions/windows/apps/hh452713(v=win.10)) if you use earlier versions of the Windows Runtime. diff --git a/docs/csharp/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md b/docs/csharp/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md index 587b59f9f9540..8cb438f99d1db 100644 --- a/docs/csharp/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md +++ b/docs/csharp/programming-guide/concepts/async/walkthrough-accessing-the-web-by-using-async-and-await.md @@ -34,7 +34,7 @@ If you don't want to build the applications yourself, you can download [Async Sa 1. In the Visual Studio Code Editor, choose the **MainWindow.xaml** tab. -2. If the **Toolbox** window isn’t visible, open the **View** menu, and then choose **Toolbox**. +2. If the **Toolbox** window isn't visible, open the **View** menu, and then choose **Toolbox**. 3. Add a **Button** control and a **TextBox** control to the **MainWindow** window. @@ -68,7 +68,7 @@ If you don't want to build the applications yourself, you can download [Async Sa 3. At the top of the dialog box, verify that your project is targeting the .NET Framework 4.5 or higher. -4. In the **Assemblies** category, choose **Framework** if it isn’t already chosen. +4. In the **Assemblies** category, choose **Framework** if it isn't already chosen. 5. In the list of names, select the **System.Net.Http** check box. @@ -78,7 +78,7 @@ If you don't want to build the applications yourself, you can download [Async Sa 1. In **Solution Explorer**, open the shortcut menu for MainWindow.xaml.cs, and then choose **View Code**. -2. Add the following `using` directives at the top of the code file if they’re not already present. +2. Add the following `using` directives at the top of the code file if they're not already present. ```csharp using System.Net.Http; @@ -212,11 +212,11 @@ Total bytes returned: 1834802 Control returned to startButton_Click. ``` -Notice that it takes a few seconds to display the counts. During that time, the UI thread is blocked while it waits for requested resources to download. As a result, you can't move, maximize, minimize, or even close the display window after you choose the **Start** button. These efforts fail until the byte counts start to appear. If a website isn’t responding, you have no indication of which site failed. It is difficult even to stop waiting and close the program. +Notice that it takes a few seconds to display the counts. During that time, the UI thread is blocked while it waits for requested resources to download. As a result, you can't move, maximize, minimize, or even close the display window after you choose the **Start** button. These efforts fail until the byte counts start to appear. If a website isn't responding, you have no indication of which site failed. It is difficult even to stop waiting and close the program. ## Convert GetURLContents to an asynchronous method -1. To convert the synchronous solution to an asynchronous solution, the best place to start is in `GetURLContents` because the calls to the method and to the method are where the application accesses the web. The .NET Framework makes the conversion easy by supplying asynchronous versions of both methods. +1. To convert the synchronous solution to an asynchronous solution, the best place to start is in `GetURLContents` because the calls to the method and to the method are where the application accesses the web. .NET Framework makes the conversion easy by supplying asynchronous versions of both methods. For more information about the methods that are used in `GetURLContents`, see . @@ -248,13 +248,13 @@ Notice that it takes a few seconds to display the counts. During that time, the The call to `webReq.GetResponseAsync` returns a `Task(Of WebResponse)` or `Task`. Then an await operator is applied to the task to retrieve the `WebResponse` value. - If your async method has work to do that doesn’t depend on the completion of the task, the method can continue with that work between these two statements, after the call to the async method and before the `await` operator is applied. For examples, see [How to make multiple web requests in parallel by using async and await (C#)](./how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md) and [How to extend the async walkthrough by using Task.WhenAll (C#)](./how-to-extend-the-async-walkthrough-by-using-task-whenall.md). + If your async method has work to do that doesn't depend on the completion of the task, the method can continue with that work between these two statements, after the call to the async method and before the `await` operator is applied. For examples, see [How to make multiple web requests in parallel by using async and await (C#)](./how-to-make-multiple-web-requests-in-parallel-by-using-async-and-await.md) and [How to extend the async walkthrough by using Task.WhenAll (C#)](./how-to-extend-the-async-walkthrough-by-using-task-whenall.md). 3. Because you added the `await` operator in the previous step, a compiler error occurs. The operator can be used only in methods that are marked with the [async](../../../language-reference/keywords/async.md) modifier. Ignore the error while you repeat the conversion steps to replace the call to `CopyTo` with a call to `CopyToAsync`. - - Change the name of the method that’s called to . + - Change the name of the method that's called to . - - The `CopyTo` or `CopyToAsync` method copies bytes to its argument, `content`, and doesn’t return a meaningful value. In the synchronous version, the call to `CopyTo` is a simple statement that doesn't return a value. The asynchronous version, `CopyToAsync`, returns a . The task functions like "Task(void)" and enables the method to be awaited. Apply `Await` or `await` to the call to `CopyToAsync`, as the following code shows. + - The `CopyTo` or `CopyToAsync` method copies bytes to its argument, `content`, and doesn't return a meaningful value. In the synchronous version, the call to `CopyTo` is a simple statement that doesn't return a value. The asynchronous version, `CopyToAsync`, returns a . The task functions like "Task(void)" and enables the method to be awaited. Apply `Await` or `await` to the call to `CopyToAsync`, as the following code shows. ```csharp await responseStream.CopyToAsync(content); @@ -277,7 +277,7 @@ Notice that it takes a few seconds to display the counts. During that time, the private async byte[] GetURLContents(string url) ``` -5. The return type of an async method can only be , , or `void` in C#. Typically, a return type of `void` is used only in an async event handler, where `void` is required. In other cases, you use `Task(T)` if the completed method has a [return](../../../language-reference/keywords/return.md) statement that returns a value of type T, and you use `Task` if the completed method doesn’t return a meaningful value. You can think of the `Task` return type as meaning "Task(void)." +5. The return type of an async method can only be , , or `void` in C#. Typically, a return type of `void` is used only in an async event handler, where `void` is required. In other cases, you use `Task(T)` if the completed method has a [return](../../../language-reference/keywords/return.md) statement that returns a value of type T, and you use `Task` if the completed method doesn't return a meaningful value. You can think of the `Task` return type as meaning "Task(void)." For more information, see [Async Return Types (C#)](./async-return-types.md). @@ -299,7 +299,7 @@ Notice that it takes a few seconds to display the counts. During that time, the 1. Repeat the steps from the previous procedure for `SumPageSizes`. First, change the call to `GetURLContents` to an asynchronous call. - - Change the name of the method that’s called from `GetURLContents` to `GetURLContentsAsync`, if you haven't already done so. + - Change the name of the method that's called from `GetURLContents` to `GetURLContentsAsync`, if you haven't already done so. - Apply `await` to the task that `GetURLContentsAsync` returns to obtain the byte array value. @@ -324,7 +324,7 @@ Notice that it takes a few seconds to display the counts. During that time, the - Add "Async" to the method name. - - There is no task return variable, T, this time because `SumPageSizesAsync` doesn’t return a value for T. (The method has no `return` statement.) However, the method must return a `Task` to be awaitable. Therefore, change the return type of the method from `void` to `Task`. + - There is no task return variable, T, this time because `SumPageSizesAsync` doesn't return a value for T. (The method has no `return` statement.) However, the method must return a `Task` to be awaitable. Therefore, change the return type of the method from `void` to `Task`. The following code shows these changes. @@ -336,7 +336,7 @@ Notice that it takes a few seconds to display the counts. During that time, the ## Convert startButton_Click to an asynchronous method -1. In the event handler, change the name of the called method from `SumPageSizes` to `SumPageSizesAsync`, if you haven’t already done so. +1. In the event handler, change the name of the called method from `SumPageSizes` to `SumPageSizesAsync`, if you haven't already done so. 2. Because `SumPageSizesAsync` is an async method, change the code in the event handler to await the result. @@ -375,7 +375,7 @@ Notice that it takes a few seconds to display the counts. During that time, the private async void startButton_Click(object sender, RoutedEventArgs e) ``` - Typically, the names of event handlers aren’t changed. The return type isn’t changed to `Task` because event handlers must return `void`. + Typically, the names of event handlers aren't changed. The return type isn't changed to `Task` because event handlers must return `void`. The conversion of the project from synchronous to asynchronous processing is complete. @@ -385,13 +385,13 @@ Notice that it takes a few seconds to display the counts. During that time, the 2. Output that resembles the output of the synchronous solution should appear. However, notice the following differences. - - The results don’t all occur at the same time, after the processing is complete. For example, both programs contain a line in `startButton_Click` that clears the text box. The intent is to clear the text box between runs if you choose the **Start** button for a second time, after one set of results has appeared. In the synchronous version, the text box is cleared just before the counts appear for the second time, when the downloads are completed and the UI thread is free to do other work. In the asynchronous version, the text box clears immediately after you choose the **Start** button. + - The results don't all occur at the same time, after the processing is complete. For example, both programs contain a line in `startButton_Click` that clears the text box. The intent is to clear the text box between runs if you choose the **Start** button for a second time, after one set of results has appeared. In the synchronous version, the text box is cleared just before the counts appear for the second time, when the downloads are completed and the UI thread is free to do other work. In the asynchronous version, the text box clears immediately after you choose the **Start** button. - - Most importantly, the UI thread isn’t blocked during the downloads. You can move or resize the window while the web resources are being downloaded, counted, and displayed. If one of the websites is slow or not responding, you can cancel the operation by choosing the **Close** button (the x in the red field in the upper-right corner). + - Most importantly, the UI thread isn't blocked during the downloads. You can move or resize the window while the web resources are being downloaded, counted, and displayed. If one of the websites is slow or not responding, you can cancel the operation by choosing the **Close** button (the x in the red field in the upper-right corner). -## Replace method GetURLContentsAsync with a .NET Framework method +## Replace method GetURLContentsAsync with a .NET method -1. The .NET Framework 4.5 provides many async methods that you can use. One of them, the method , does just what you need for this walkthrough. You can use it instead of the `GetURLContentsAsync` method that you created in an earlier procedure. +1. .NET Framework 4.5 and later versions provide many async methods that you can use. One of them, the method , does just what you need for this walkthrough. You can use it instead of the `GetURLContentsAsync` method that you created in an earlier procedure. The first step is to create an `HttpClient` object in method `SumPageSizesAsync`. Add the following declaration at the start of the method. diff --git a/docs/csharp/programming-guide/concepts/attributes/index.md b/docs/csharp/programming-guide/concepts/attributes/index.md index b684302948efd..95261f26a79ad 100644 --- a/docs/csharp/programming-guide/concepts/attributes/index.md +++ b/docs/csharp/programming-guide/concepts/attributes/index.md @@ -35,7 +35,7 @@ Some attributes can be specified more than once for a given entity. An example o [!code-csharp[Using the conditional attribute](~/samples/snippets/csharp/attributes/AttributesOverview.cs#5)] > [!NOTE] -> By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET libraries. However, you do not need to specify the attribute suffix when using attributes in code. For example, `[DllImport]` is equivalent to `[DllImportAttribute]`, but `DllImportAttribute` is the attribute's actual name in the .NET Framework Class Library. +> By convention, all attribute names end with the word "Attribute" to distinguish them from other items in the .NET libraries. However, you do not need to specify the attribute suffix when using attributes in code. For example, `[DllImport]` is equivalent to `[DllImportAttribute]`, but `DllImportAttribute` is the attribute's actual name in the .NET Class Library. ### Attribute parameters diff --git a/docs/csharp/programming-guide/concepts/collections.md b/docs/csharp/programming-guide/concepts/collections.md index 45cc248eb8c78..582fc8946c187 100644 --- a/docs/csharp/programming-guide/concepts/collections.md +++ b/docs/csharp/programming-guide/concepts/collections.md @@ -176,7 +176,7 @@ public class Galaxy ## Kinds of Collections -Many common collections are provided by the .NET Framework. Each type of collection is designed for a specific purpose. +Many common collections are provided by .NET. Each type of collection is designed for a specific purpose. Some of the common collection classes are described in this section: @@ -208,7 +208,7 @@ For additional information, see [Commonly Used Collection Types](../../../standa ### System.Collections.Concurrent Classes -In the .NET Framework 4 or newer, the collections in the namespace provide efficient thread-safe operations for accessing collection items from multiple threads. +In .NET Framework 4 and later versions, the collections in the namespace provide efficient thread-safe operations for accessing collection items from multiple threads. The classes in the namespace should be used instead of the corresponding types in the and namespaces whenever multiple threads are accessing the collection concurrently. For more information, see [Thread-Safe Collections](../../../standard/collections/thread-safe/index.md) and . @@ -476,7 +476,7 @@ public class Car : IComparable You can define a collection by implementing the or interface. -Although you can define a custom collection, it is usually better to instead use the collections that are included in the .NET Framework, which are described in [Kinds of Collections](#BKMK_KindsOfCollections) earlier in this topic. +Although you can define a custom collection, it is usually better to instead use the collections that are included in .NET, which are described in [Kinds of Collections](#BKMK_KindsOfCollections) earlier in this article. The following example defines a custom collection class named `AllColors`. This class implements the interface, which requires that the method be implemented. diff --git a/docs/csharp/programming-guide/concepts/covariance-contravariance/creating-variant-generic-interfaces.md b/docs/csharp/programming-guide/concepts/covariance-contravariance/creating-variant-generic-interfaces.md index 26982a185050f..eac6e73b6c4ae 100644 --- a/docs/csharp/programming-guide/concepts/covariance-contravariance/creating-variant-generic-interfaces.md +++ b/docs/csharp/programming-guide/concepts/covariance-contravariance/creating-variant-generic-interfaces.md @@ -9,7 +9,7 @@ ms.assetid: 30330ec4-9df2-4838-a535-6c406d0ed4df You can declare generic type parameters in interfaces as covariant or contravariant. *Covariance* allows interface methods to have more derived return types than that defined by the generic type parameters. *Contravariance* allows interface methods to have argument types that are less derived than that specified by the generic parameters. A generic interface that has covariant or contravariant generic type parameters is called *variant*. > [!NOTE] -> .NET Framework 4 introduced variance support for several existing generic interfaces. For the list of the variant interfaces in the .NET Framework, see [Variance in Generic Interfaces (C#)](./variance-in-generic-interfaces.md). +> .NET Framework 4 introduced variance support for several existing generic interfaces. For the list of the variant interfaces in .NET, see [Variance in Generic Interfaces (C#)](./variance-in-generic-interfaces.md). ## Declaring Variant Generic Interfaces diff --git a/docs/csharp/programming-guide/concepts/covariance-contravariance/index.md b/docs/csharp/programming-guide/concepts/covariance-contravariance/index.md index 84e9bf80a0bf5..68b22fa0e4470 100644 --- a/docs/csharp/programming-guide/concepts/covariance-contravariance/index.md +++ b/docs/csharp/programming-guide/concepts/covariance-contravariance/index.md @@ -62,7 +62,7 @@ static void Test() } ``` - In .NET Framework 4 or newer C# supports covariance and contravariance in generic interfaces and delegates and allows for implicit conversion of generic type parameters. For more information, see [Variance in Generic Interfaces (C#)](./variance-in-generic-interfaces.md) and [Variance in Delegates (C#)](./variance-in-delegates.md). + In .NET Framework 4 and later versions, C# supports covariance and contravariance in generic interfaces and delegates and allows for implicit conversion of generic type parameters. For more information, see [Variance in Generic Interfaces (C#)](./variance-in-generic-interfaces.md) and [Variance in Delegates (C#)](./variance-in-delegates.md). The following code example shows implicit reference conversion for generic interfaces. diff --git a/docs/csharp/programming-guide/concepts/covariance-contravariance/using-variance-in-interfaces-for-generic-collections.md b/docs/csharp/programming-guide/concepts/covariance-contravariance/using-variance-in-interfaces-for-generic-collections.md index b1a4eabe0c867..ce564ab23a1c2 100644 --- a/docs/csharp/programming-guide/concepts/covariance-contravariance/using-variance-in-interfaces-for-generic-collections.md +++ b/docs/csharp/programming-guide/concepts/covariance-contravariance/using-variance-in-interfaces-for-generic-collections.md @@ -8,7 +8,7 @@ A covariant interface allows its methods to return more derived types than those In .NET Framework 4, several existing interfaces became covariant and contravariant. These include and . This enables you to reuse methods that operate with generic collections of base types for collections of derived types. - For a list of variant interfaces in the .NET Framework, see [Variance in Generic Interfaces (C#)](./variance-in-generic-interfaces.md). + For a list of variant interfaces in .NET, see [Variance in Generic Interfaces (C#)](./variance-in-generic-interfaces.md). ## Converting Generic Collections The following example illustrates the benefits of covariance support in the interface. The `PrintFullName` method accepts a collection of the `IEnumerable` type as a parameter. However, you can reuse it for a collection of the `IEnumerable` type because `Employee` inherits `Person`. diff --git a/docs/csharp/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md b/docs/csharp/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md index f902ebfd298df..72c7cfbccf679 100644 --- a/docs/csharp/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md +++ b/docs/csharp/programming-guide/concepts/covariance-contravariance/variance-in-delegates.md @@ -103,8 +103,9 @@ public static void Test() } ``` -### Generic Delegates That Have Variant Type Parameters in the .NET Framework - .NET Framework 4 introduced variance support for generic type parameters in several existing generic delegates: +### Generic Delegates That Have Variant Type Parameters in .NET + +.NET Framework 4 introduced variance support for generic type parameters in several existing generic delegates: - `Action` delegates from the namespace, for example, and diff --git a/docs/csharp/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md b/docs/csharp/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md index a1c411ab4a62f..afefe9fd7ad9b 100644 --- a/docs/csharp/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md +++ b/docs/csharp/programming-guide/concepts/covariance-contravariance/variance-in-generic-interfaces.md @@ -37,7 +37,7 @@ IEnumerable strings = new List(); IEnumerable objects = strings; ``` -In earlier versions of the .NET Framework, this code causes a compilation error in C# and, if `Option Strict` is on, in Visual Basic. But now you can use `strings` instead of `objects`, as shown in the previous example, because the interface is covariant. +In earlier versions of .NET Framework, this code causes a compilation error in C# and, if `Option Strict` is on, in Visual Basic. But now you can use `strings` instead of `objects`, as shown in the previous example, because the interface is covariant. Contravariance permits a method to have argument types that are less derived than that specified by the generic parameter of the interface. To illustrate contravariance, assume that you have created a `BaseComparer` class to compare instances of the `BaseClass` class. The `BaseComparer` class implements the `IEqualityComparer` interface. Because the interface is now contravariant, you can use `BaseComparer` to compare instances of classes that inherit the `BaseClass` class. This is shown in the following code example. diff --git a/docs/csharp/programming-guide/concepts/expression-trees/index.md b/docs/csharp/programming-guide/concepts/expression-trees/index.md index 4f257c8703014..e34e6f75203ee 100644 --- a/docs/csharp/programming-guide/concepts/expression-trees/index.md +++ b/docs/csharp/programming-guide/concepts/expression-trees/index.md @@ -8,7 +8,7 @@ Expression trees represent code in a tree-like data structure, where each node i You can compile and run code represented by expression trees. This enables dynamic modification of executable code, the execution of LINQ queries in various databases, and the creation of dynamic queries. For more information about expression trees in LINQ, see [How to use expression trees to build dynamic queries (C#)](./how-to-use-expression-trees-to-build-dynamic-queries.md). - Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and the .NET Framework and to enable compiler writers to emit expression trees instead of Microsoft intermediate language (MSIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). + Expression trees are also used in the dynamic language runtime (DLR) to provide interoperability between dynamic languages and .NET and to enable compiler writers to emit expression trees instead of Microsoft intermediate language (MSIL). For more information about the DLR, see [Dynamic Language Runtime Overview](../../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). You can have the C# or Visual Basic compiler create an expression tree for you based on an anonymous lambda expression, or you can create expression trees manually by using the namespace. diff --git a/docs/csharp/programming-guide/concepts/index.md b/docs/csharp/programming-guide/concepts/index.md index f092d6294b558..814ba73f1ffcf 100644 --- a/docs/csharp/programming-guide/concepts/index.md +++ b/docs/csharp/programming-guide/concepts/index.md @@ -13,7 +13,7 @@ This section explains programming concepts in the C# language. |[Assemblies in .NET](../../../standard/assembly/index.md)|Describes how to create and use assemblies.| |[Asynchronous Programming with async and await (C#)](./async/index.md)|Describes how to write asynchronous solutions by using the [async](../../language-reference/keywords/async.md) and [await](../../language-reference/operators/await.md) keywords in C#. Includes a walkthrough.| |[Attributes (C#)](./attributes/index.md)|Discusses how to provide additional information about programming elements such as types, fields, methods, and properties by using attributes.| -|[Collections (C#)](./collections.md)|Describes some of the types of collections provided by the .NET Framework. Demonstrates how to use simple collections and collections of key/value pairs.| +|[Collections (C#)](./collections.md)|Describes some of the types of collections provided by .NET. Demonstrates how to use simple collections and collections of key/value pairs.| |[Covariance and Contravariance (C#)](./covariance-contravariance/index.md)|Shows how to enable implicit conversion of generic type parameters in interfaces and delegates.| |[Expression Trees (C#)](./expression-trees/index.md)|Explains how you can use expression trees to enable dynamic modification of executable code.| |[Iterators (C#)](./iterators.md)|Describes iterators, which are used to step through collections and return elements one at a time.| diff --git a/docs/csharp/programming-guide/concepts/iterators.md b/docs/csharp/programming-guide/concepts/iterators.md index df9901661419d..76095c0c36267 100644 --- a/docs/csharp/programming-guide/concepts/iterators.md +++ b/docs/csharp/programming-guide/concepts/iterators.md @@ -344,7 +344,7 @@ Iterators enable you to maintain the simplicity of a `foreach` loop when you nee - Modify the list sequence after the first `foreach` loop iteration. -- Avoid fully loading a large list before the first iteration of a `foreach` loop. An example is a paged fetch to load a batch of table rows. Another example is the method, which implements iterators within the .NET Framework. +- Avoid fully loading a large list before the first iteration of a `foreach` loop. An example is a paged fetch to load a batch of table rows. Another example is the method, which implements iterators in .NET. - Encapsulate building the list in the iterator. In the iterator method, you can build the list and then yield each result in a loop. diff --git a/docs/csharp/programming-guide/concepts/linq/how-to-query-an-assembly-s-metadata-with-reflection-linq.md b/docs/csharp/programming-guide/concepts/linq/how-to-query-an-assembly-s-metadata-with-reflection-linq.md index c346cc4b59db4..0cd3b9df33e26 100644 --- a/docs/csharp/programming-guide/concepts/linq/how-to-query-an-assembly-s-metadata-with-reflection-linq.md +++ b/docs/csharp/programming-guide/concepts/linq/how-to-query-an-assembly-s-metadata-with-reflection-linq.md @@ -5,7 +5,7 @@ ms.assetid: c4cdce49-b1c8-4420-b12a-9ff7e6671368 --- # How to query an assembly's metadata with Reflection (LINQ) (C#) -The .NET Framework class library reflection APIs can be used to examine the metadata in a .NET assembly and create collections of types, type members, parameters, and so on that are in that assembly. Because these collections support the generic interface, they can be queried by using LINQ. +The .NET reflection APIs can be used to examine the metadata in a .NET assembly and create collections of types, type members, parameters, and so on that are in that assembly. Because these collections support the generic interface, they can be queried by using LINQ. The following example shows how LINQ can be used with reflection to retrieve specific metadata about methods that match a specified search criterion. In this case, the query will find the names of all the methods in the assembly that return enumerable types such as arrays. diff --git a/docs/csharp/programming-guide/concepts/linq/linq-and-generic-types.md b/docs/csharp/programming-guide/concepts/linq/linq-and-generic-types.md index 7b1194b08c704..a44ac511b9b48 100644 --- a/docs/csharp/programming-guide/concepts/linq/linq-and-generic-types.md +++ b/docs/csharp/programming-guide/concepts/linq/linq-and-generic-types.md @@ -8,7 +8,7 @@ helpviewer_keywords: ms.assetid: 660e3799-25ca-462c-8c4a-8bce04fbb031 --- # LINQ and Generic Types (C#) -LINQ queries are based on generic types, which were introduced in version 2.0 of the .NET Framework. You do not need an in-depth knowledge of generics before you can start writing queries. However, you may want to understand two basic concepts: +LINQ queries are based on generic types, which were introduced in version 2.0 of .NET Framework. You do not need an in-depth knowledge of generics before you can start writing queries. However, you may want to understand two basic concepts: 1. When you create an instance of a generic collection class such as , you replace the "T" with the type of objects that the list will hold. For example, a list of strings is expressed as `List`, and a list of `Customer` objects is expressed as `List`. A generic list is strongly typed and provides many benefits over collections that store their elements as . If you try to add a `Customer` to a `List`, you will get an error at compile time. It is easy to use generic collections because you do not have to perform run-time type-casting. diff --git a/docs/csharp/programming-guide/concepts/linq/linq-to-objects.md b/docs/csharp/programming-guide/concepts/linq/linq-to-objects.md index 19cd43c57df3d..6334ac573c6e3 100644 --- a/docs/csharp/programming-guide/concepts/linq/linq-to-objects.md +++ b/docs/csharp/programming-guide/concepts/linq/linq-to-objects.md @@ -4,7 +4,7 @@ ms.date: 07/20/2015 ms.assetid: c5c2c178-3529-4f6c-b3df-2d5267af7f22 --- # LINQ to Objects (C#) -The term "LINQ to Objects" refers to the use of LINQ queries with any or collection directly, without the use of an intermediate LINQ provider or API such as [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md) or [LINQ to XML](./linq-to-xml-overview.md). You can use LINQ to query any enumerable collections such as , , or . The collection may be user-defined or may be returned by a .NET Framework API. +The term "LINQ to Objects" refers to the use of LINQ queries with any or collection directly, without the use of an intermediate LINQ provider or API such as [LINQ to SQL](../../../../framework/data/adonet/sql/linq/index.md) or [LINQ to XML](./linq-to-xml-overview.md). You can use LINQ to query any enumerable collections such as , , or . The collection may be user-defined or may be returned by a .NET API. In a basic sense, LINQ to Objects represents a new approach to collections. In the old way, you had to write complex `foreach` loops that specified how to retrieve data from a collection. In the LINQ approach, you write declarative code that describes what you want to retrieve. diff --git a/docs/csharp/programming-guide/concepts/linq/linq-to-xml-overview.md b/docs/csharp/programming-guide/concepts/linq/linq-to-xml-overview.md index af49bbe2672e0..4bfea4c424f9f 100644 --- a/docs/csharp/programming-guide/concepts/linq/linq-to-xml-overview.md +++ b/docs/csharp/programming-guide/concepts/linq/linq-to-xml-overview.md @@ -19,7 +19,7 @@ Professional developers can use [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md ## What Is LINQ to XML? -[!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] is a LINQ-enabled, in-memory XML programming interface that enables you to work with XML from within the .NET Framework programming languages. +[!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] is a LINQ-enabled, in-memory XML programming interface that enables you to work with XML from within the .NET programming languages. [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] is like the Document Object Model (DOM) in that it brings the XML document into memory. You can query and modify the document, and after you modify it you can save it to a file or serialize it and send it over the Internet. However, [!INCLUDE[sqltecxlinq](~/includes/sqltecxlinq-md.md)] differs from DOM: It provides a new object model that is lighter weight and easier to work with, and that takes advantage of language features in C#. diff --git a/docs/csharp/programming-guide/concepts/linq/namespaces-overview-linq-to-xml.md b/docs/csharp/programming-guide/concepts/linq/namespaces-overview-linq-to-xml.md index 30145931bd7ea..80639b669a8cc 100644 --- a/docs/csharp/programming-guide/concepts/linq/namespaces-overview-linq-to-xml.md +++ b/docs/csharp/programming-guide/concepts/linq/namespaces-overview-linq-to-xml.md @@ -9,7 +9,7 @@ This article introduces namespaces, the class, and ## XML Names -XML names are often a source of complexity in XML programming. An XML name consists of an XML namespace (also called an XML namespace URI) and a local name. An XML namespace is similar to a namespace in a .NET Framework-based program. It enables you to uniquely qualify the names of elements and attributes. This helps avoid name conflicts between various parts of an XML document. When you have declared an XML namespace, you can select a local name that only has to be unique within that namespace. +XML names are often a source of complexity in XML programming. An XML name consists of an XML namespace (also called an XML namespace URI) and a local name. An XML namespace is similar to a namespace in a .NET program. It enables you to uniquely qualify the names of elements and attributes. This helps avoid name conflicts between various parts of an XML document. When you have declared an XML namespace, you can select a local name that only has to be unique within that namespace. Another aspect of XML names is XML *namespace prefixes*. XML prefixes cause most of the complexity of XML names. These prefixes enable you to create a shortcut for an XML namespace, which makes the XML document more concise and understandable. However, XML prefixes depend on their context to have meaning, which adds complexity. For example, the XML prefix `aw` could be associated with one XML namespace in one part of an XML tree, and with a different XML namespace in a different part of the XML tree. diff --git a/docs/csharp/programming-guide/concepts/object-oriented-programming.md b/docs/csharp/programming-guide/concepts/object-oriented-programming.md index 98810dccecbe5..12e07f186bff1 100644 --- a/docs/csharp/programming-guide/concepts/object-oriented-programming.md +++ b/docs/csharp/programming-guide/concepts/object-oriented-programming.md @@ -140,9 +140,9 @@ For more information, see [Constructors](../classes-and-structs/constructors.md) #### Finalizers -A finalizer is used to destruct instances of classes. In the .NET Framework, the garbage collector automatically manages the allocation and release of memory for the managed objects in your application. However, you may still need finalizers to clean up any unmanaged resources that your application creates. There can be only one finalizer for a class. +A finalizer is used to destruct instances of classes. In .NET, the garbage collector automatically manages the allocation and release of memory for the managed objects in your application. However, you may still need finalizers to clean up any unmanaged resources that your application creates. There can be only one finalizer for a class. -For more information about finalizers and garbage collection in the .NET Framework, see [Garbage Collection](../../../standard/garbage-collection/index.md). +For more information about finalizers and garbage collection in .NET, see [Garbage Collection](../../../standard/garbage-collection/index.md). #### Events @@ -336,7 +336,7 @@ For more information, see the programming guide article on [Interfaces](../inter ## Generics -Classes, structures, interfaces and methods in the .NET Framework can include *type parameters* that define types of objects that they can store or use. The most common example of generics is a collection, where you can specify the type of objects to be stored in a collection. +Classes, structures, interfaces, and methods in .NET can include *type parameters* that define types of objects that they can store or use. The most common example of generics is a collection, where you can specify the type of objects to be stored in a collection. To define a generic class: diff --git a/docs/csharp/programming-guide/concepts/serialization/how-to-read-object-data-from-an-xml-file.md b/docs/csharp/programming-guide/concepts/serialization/how-to-read-object-data-from-an-xml-file.md index 7d83f230d8127..32e0458579185 100644 --- a/docs/csharp/programming-guide/concepts/serialization/how-to-read-object-data-from-an-xml-file.md +++ b/docs/csharp/programming-guide/concepts/serialization/how-to-read-object-data-from-an-xml-file.md @@ -52,7 +52,7 @@ Replace the file name "c:\temp\SerializationOverview.xml" with the name of the f - The file does not exist (). -## .NET Framework Security +## .NET Security Always verify inputs, and never deserialize data from an untrusted source. The re-created object runs on a local computer with the permissions of the code that deserialized it. Verify all inputs before using the data in your application. ## See also diff --git a/docs/csharp/programming-guide/concepts/serialization/how-to-write-object-data-to-an-xml-file.md b/docs/csharp/programming-guide/concepts/serialization/how-to-write-object-data-to-an-xml-file.md index 48cdd6cc84281..6e135f517ad5d 100644 --- a/docs/csharp/programming-guide/concepts/serialization/how-to-write-object-data-to-an-xml-file.md +++ b/docs/csharp/programming-guide/concepts/serialization/how-to-write-object-data-to-an-xml-file.md @@ -52,7 +52,7 @@ public class XMLWrite - The disk is full (). -## .NET Framework Security +## .NET Security This example creates a new file, if the file does not already exist. If an application needs to create a file, that application needs `Create` access for the folder. If the file already exists, the application needs only `Write` access, a lesser privilege. Where possible, it is more secure to create the file during deployment, and only grant `Read` access to a single file, rather than `Create` access for a folder. ## See also diff --git a/docs/csharp/programming-guide/concepts/serialization/index.md b/docs/csharp/programming-guide/concepts/serialization/index.md index dbcff6a489c48..0bba0526ab114 100644 --- a/docs/csharp/programming-guide/concepts/serialization/index.md +++ b/docs/csharp/programming-guide/concepts/serialization/index.md @@ -59,7 +59,7 @@ If a serialized class contains references to objects of other classes that are m Binary and XML serialization can be performed in two ways, basic and custom. -Basic serialization uses the .NET Framework to automatically serialize the object. The only requirement is that the class has the attribute applied. The can be used to keep specific fields from being serialized. +Basic serialization uses .NET to automatically serialize the object. The only requirement is that the class has the attribute applied. The can be used to keep specific fields from being serialized. When you use basic serialization, the versioning of objects may create problems. You would use custom serialization when versioning issues are important. Basic serialization is the easiest way to perform serialization, but it does not provide much control over the process. diff --git a/docs/csharp/programming-guide/delegates/using-delegates.md b/docs/csharp/programming-guide/delegates/using-delegates.md index c302832db40d1..459a00b8b3a9d 100644 --- a/docs/csharp/programming-guide/delegates/using-delegates.md +++ b/docs/csharp/programming-guide/delegates/using-delegates.md @@ -17,7 +17,7 @@ A delegate object is normally constructed by providing the name of the method th [!code-csharp[csProgGuideDelegates#23](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideDelegates/CS/Delegates.cs#23)] -Delegate types are derived from the class in the .NET Framework. Delegate types are [sealed](../../language-reference/keywords/sealed.md)—they cannot be derived from— and it is not possible to derive custom classes from . Because the instantiated delegate is an object, it can be passed as a parameter, or assigned to a property. This allows a method to accept a delegate as a parameter, and call the delegate at some later time. This is known as an asynchronous callback, and is a common method of notifying a caller when a long process has completed. When a delegate is used in this fashion, the code using the delegate does not need any knowledge of the implementation of the method being used. The functionality is similar to the encapsulation interfaces provide. +Delegate types are derived from the class in .NET. Delegate types are [sealed](../../language-reference/keywords/sealed.md)—they cannot be derived from— and it is not possible to derive custom classes from . Because the instantiated delegate is an object, it can be passed as a parameter, or assigned to a property. This allows a method to accept a delegate as a parameter, and call the delegate at some later time. This is known as an asynchronous callback, and is a common method of notifying a caller when a long process has completed. When a delegate is used in this fashion, the code using the delegate does not need any knowledge of the implementation of the method being used. The functionality is similar to the encapsulation interfaces provide. Another common use of callbacks is defining a custom comparison method and passing that delegate to a sort method. It allows the caller's code to become part of the sort algorithm. The following example method uses the `Del` type as a parameter: diff --git a/docs/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md b/docs/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md index aede485c06bcd..48d12c76054b4 100644 --- a/docs/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md +++ b/docs/csharp/programming-guide/events/how-to-publish-events-that-conform-to-net-framework-guidelines.md @@ -1,27 +1,27 @@ --- -title: "How to publish events that conform to .NET Framework Guidelines - C# Programming Guide" +title: "Publish events that conform to .NET Guidelines - C# Programming Guide" ms.date: 05/26/2020 helpviewer_keywords: - "events [C#], implementation guidelines" ms.assetid: 9310ae16-8627-44a2-b08c-05e5976202b1 --- -# How to publish events that conform to .NET Framework Guidelines (C# Programming Guide) +# How to publish events that conform to .NET Guidelines (C# Programming Guide) -The following procedure demonstrates how to add events that follow the standard .NET Framework pattern to your classes and structs. All events in the .NET Framework class library are based on the delegate, which is defined as follows: +The following procedure demonstrates how to add events that follow the standard .NET pattern to your classes and structs. All events in the .NET Framework class library are based on the delegate, which is defined as follows: ```csharp public delegate void EventHandler(object sender, EventArgs e); ``` > [!NOTE] -> The .NET Framework 2.0 introduces a generic version of this delegate, . The following examples show how to use both versions. +> .NET Framework 2.0 introduces a generic version of this delegate, . The following examples show how to use both versions. -Although events in classes that you define can be based on any valid delegate type, even delegates that return a value, it is generally recommended that you base your events on the .NET Framework pattern by using , as shown in the following example. +Although events in classes that you define can be based on any valid delegate type, even delegates that return a value, it is generally recommended that you base your events on the .NET pattern by using , as shown in the following example. The name `EventHandler` can lead to a bit of confusion as it doesn't actually handle the event. The , and generic are delegate types. A method or lambda expression whose signature matches the delegate definition is the *event handler* and will be invoked when the event is raised. -### To publish events based on the EventHandler pattern +## Publish events based on the EventHandler pattern 1. (Skip this step and go to Step 3a if you do not have to send custom data with your event.) Declare the class for your custom data at a scope that is visible to both your publisher and subscriber classes. Then add the required members to hold your custom event data. In this example, a simple string is returned. diff --git a/docs/csharp/programming-guide/events/how-to-raise-base-class-events-in-derived-classes.md b/docs/csharp/programming-guide/events/how-to-raise-base-class-events-in-derived-classes.md index 718c44c143e23..3f7d3b11a408e 100644 --- a/docs/csharp/programming-guide/events/how-to-raise-base-class-events-in-derived-classes.md +++ b/docs/csharp/programming-guide/events/how-to-raise-base-class-events-in-derived-classes.md @@ -6,7 +6,7 @@ helpviewer_keywords: ms.assetid: 2d20556a-0aad-46fc-845e-f85d86ea617a --- # How to raise base class events in derived classes (C# Programming Guide) -The following simple example shows the standard way to declare events in a base class so that they can also be raised from derived classes. This pattern is used extensively in Windows Forms classes in the .NET Framework class library. +The following simple example shows the standard way to declare events in a base class so that they can also be raised from derived classes. This pattern is used extensively in Windows Forms classes in the .NET class libraries. When you create a class that can be used as a base class for other classes, you should consider the fact that events are a special type of delegate that can only be invoked from within the class that declared them. Derived classes cannot directly invoke events that are declared within the base class. Although sometimes you may want an event that can only be raised by the base class, most of the time, you should enable the derived class to invoke base class events. To do this, you can create a protected invoking method in the base class that wraps the event. By calling or overriding this invoking method, derived classes can invoke the event indirectly. diff --git a/docs/csharp/programming-guide/events/how-to-subscribe-to-and-unsubscribe-from-events.md b/docs/csharp/programming-guide/events/how-to-subscribe-to-and-unsubscribe-from-events.md index dc727d943db7b..56dcc5d2c92dc 100644 --- a/docs/csharp/programming-guide/events/how-to-subscribe-to-and-unsubscribe-from-events.md +++ b/docs/csharp/programming-guide/events/how-to-subscribe-to-and-unsubscribe-from-events.md @@ -95,6 +95,6 @@ You subscribe to an event that is published by another class when you want to wr - [Events](./index.md) - [event](../../language-reference/keywords/event.md) -- [How to publish events that conform to .NET Framework Guidelines](./how-to-publish-events-that-conform-to-net-framework-guidelines.md) +- [How to publish events that conform to .NET Guidelines](./how-to-publish-events-that-conform-to-net-framework-guidelines.md) - [- and -= operators](../../language-reference/operators/subtraction-operator.md) - [+ and += operators](../../language-reference/operators/addition-operator.md) diff --git a/docs/csharp/programming-guide/events/index.md b/docs/csharp/programming-guide/events/index.md index 7d7a571e52d6c..29ebd26bcbbfa 100644 --- a/docs/csharp/programming-guide/events/index.md +++ b/docs/csharp/programming-guide/events/index.md @@ -32,7 +32,7 @@ In a typical C# Windows Forms or Web application, you subscribe to events raised - [How to subscribe to and unsubscribe from events](./how-to-subscribe-to-and-unsubscribe-from-events.md) -- [How to publish events that conform to .NET Framework Guidelines](./how-to-publish-events-that-conform-to-net-framework-guidelines.md) +- [How to publish events that conform to .NET Guidelines](./how-to-publish-events-that-conform-to-net-framework-guidelines.md) - [How to raise base class events in derived classes](./how-to-raise-base-class-events-in-derived-classes.md) diff --git a/docs/csharp/programming-guide/exceptions/compiler-generated-exceptions.md b/docs/csharp/programming-guide/exceptions/compiler-generated-exceptions.md index 5bf78055f4cc9..8500eb6bcab26 100644 --- a/docs/csharp/programming-guide/exceptions/compiler-generated-exceptions.md +++ b/docs/csharp/programming-guide/exceptions/compiler-generated-exceptions.md @@ -6,7 +6,8 @@ helpviewer_keywords: ms.assetid: 53b52f97-b366-4ed7-b05b-9eb78096b7f9 --- # Compiler-Generated Exceptions (C# Programming Guide) -Some exceptions are thrown automatically by the .NET Framework's common language runtime (CLR) when basic operations fail. These exceptions and their error conditions are listed in the following table. + +Some exceptions are thrown automatically by the .NET runtime when basic operations fail. These exceptions and their error conditions are listed in the following table. |Exception|Description| |---------------|-----------------| diff --git a/docs/csharp/programming-guide/exceptions/index.md b/docs/csharp/programming-guide/exceptions/index.md index 0f43d4f6d2b83..1eb8510f7a1ec 100644 --- a/docs/csharp/programming-guide/exceptions/index.md +++ b/docs/csharp/programming-guide/exceptions/index.md @@ -9,7 +9,7 @@ ms.assetid: 0001887f-4fa2-47e2-8034-2819477e2344 --- # Exceptions and Exception Handling (C# Programming Guide) -The C# language's exception handling features help you deal with any unexpected or exceptional situations that occur when a program is running. Exception handling uses the `try`, `catch`, and `finally` keywords to try actions that may not succeed, to handle failures when you decide that it is reasonable to do so, and to clean up resources afterward. Exceptions can be generated by the common language runtime (CLR), by the .NET Framework or any third-party libraries, or by application code. Exceptions are created by using the `throw` keyword. +The C# language's exception handling features help you deal with any unexpected or exceptional situations that occur when a program is running. Exception handling uses the `try`, `catch`, and `finally` keywords to try actions that may not succeed, to handle failures when you decide that it is reasonable to do so, and to clean up resources afterward. Exceptions can be generated by the common language runtime (CLR), by .NET or third-party libraries, or by application code. Exceptions are created by using the `throw` keyword. In many cases, an exception may be thrown not by a method that your code has called directly, but by another method further down in the call stack. When this happens, the CLR will unwind the stack, looking for a method with a `catch` block for the specific exception type, and it will execute the first such `catch` block that if finds. If it finds no appropriate `catch` block anywhere in the call stack, it will terminate the process and display a message to the user. @@ -30,7 +30,7 @@ Exceptions have the following properties: - Exceptions can be explicitly generated by a program by using the `throw` keyword. - Exception objects contain detailed information about the error, such as the state of the call stack and a text description of the error. - Code in a `finally` block is executed even if an exception is thrown. Use a `finally` block to release resources, for example to close any streams or files that were opened in the `try` block. -- Managed exceptions in the .NET Framework are implemented on top of the Win32 structured exception handling mechanism. For more information, see [Structured Exception Handling (C/C++)](/cpp/cpp/structured-exception-handling-c-cpp) and [A Crash Course on the Depths of Win32 Structured Exception Handling](http://bytepointer.com/resources/pietrek_crash_course_depths_of_win32_seh.htm). +- Managed exceptions in .NET are implemented on top of the Win32 structured exception handling mechanism. For more information, see [Structured Exception Handling (C/C++)](/cpp/cpp/structured-exception-handling-c-cpp) and [A Crash Course on the Depths of Win32 Structured Exception Handling](http://bytepointer.com/resources/pietrek_crash_course_depths_of_win32_seh.htm). ## Related Sections diff --git a/docs/csharp/programming-guide/exceptions/using-exceptions.md b/docs/csharp/programming-guide/exceptions/using-exceptions.md index e5ec7233b2dcb..f4bb554264ad2 100644 --- a/docs/csharp/programming-guide/exceptions/using-exceptions.md +++ b/docs/csharp/programming-guide/exceptions/using-exceptions.md @@ -6,8 +6,9 @@ helpviewer_keywords: - "exceptions [C#], about exceptions" ms.assetid: 71472c62-320a-470a-97d2-67995180389d --- -# Using Exceptions (C# Programming Guide) -In C#, errors in the program at run time are propagated through the program by using a mechanism called exceptions. Exceptions are thrown by code that encounters an error and caught by code that can correct the error. Exceptions can be thrown by the .NET Framework common language runtime (CLR) or by code in a program. Once an exception is thrown, it propagates up the call stack until a `catch` statement for the exception is found. Uncaught exceptions are handled by a generic exception handler provided by the system that displays a dialog box. +# Use exceptions (C# programming guide) + +In C#, errors in the program at run time are propagated through the program by using a mechanism called exceptions. Exceptions are thrown by code that encounters an error and caught by code that can correct the error. Exceptions can be thrown by the .NET runtime or by code in a program. Once an exception is thrown, it propagates up the call stack until a `catch` statement for the exception is found. Uncaught exceptions are handled by a generic exception handler provided by the system that displays a dialog box. Exceptions are represented by classes derived from . This class identifies the type of exception and contains properties that have details about the exception. Throwing an exception involves creating an instance of an exception-derived class, optionally configuring properties of the exception, and then throwing the object by using the `throw` keyword. For example: diff --git a/docs/csharp/programming-guide/file-system/how-to-create-a-file-or-folder.md b/docs/csharp/programming-guide/file-system/how-to-create-a-file-or-folder.md index 5f6be7509213e..d17eb9114773c 100644 --- a/docs/csharp/programming-guide/file-system/how-to-create-a-file-or-folder.md +++ b/docs/csharp/programming-guide/file-system/how-to-create-a-file-or-folder.md @@ -56,10 +56,10 @@ You can programmatically create a folder on your computer, create a subfolder, c - The folder name is only a colon, ":" ( class). -## .NET Framework Security +## .NET Security An instance of the class may be thrown in partial-trust situations. - If you don’t have permission to create the folder, the example throws an instance of the class. + If you don't have permission to create the folder, the example throws an instance of the class. ## See also diff --git a/docs/csharp/programming-guide/file-system/how-to-create-a-key-in-the-registry.md b/docs/csharp/programming-guide/file-system/how-to-create-a-key-in-the-registry.md index cdc584c89bbef..778e500371e24 100644 --- a/docs/csharp/programming-guide/file-system/how-to-create-a-key-in-the-registry.md +++ b/docs/csharp/programming-guide/file-system/how-to-create-a-key-in-the-registry.md @@ -42,7 +42,7 @@ key.Close(); - The registry key is read-only. -## .NET Framework Security +## .NET Security It is more secure to write data to the user folder — `Microsoft.Win32.Registry.CurrentUser` — rather than to the local computer — `Microsoft.Win32.Registry.LocalMachine`. When you create a registry value, you need to decide what to do if that value already exists. Another process, perhaps a malicious one, may have already created the value and have access to it. When you put data in the registry value, the data is available to the other process. To prevent this, use the.`Overload:Microsoft.Win32.RegistryKey.GetValue` method. It returns null if the key does not already exist. diff --git a/docs/csharp/programming-guide/file-system/how-to-get-information-about-files-folders-and-drives.md b/docs/csharp/programming-guide/file-system/how-to-get-information-about-files-folders-and-drives.md index 0c0ccafbe2d30..848925a3968f1 100644 --- a/docs/csharp/programming-guide/file-system/how-to-get-information-about-files-folders-and-drives.md +++ b/docs/csharp/programming-guide/file-system/how-to-get-information-about-files-folders-and-drives.md @@ -6,7 +6,7 @@ helpviewer_keywords: ms.assetid: 22fc2da6-5494-405b-995e-c0b99142a93e --- # How to get information about files, folders, and drives (C# Programming Guide) -In the .NET Framework, you can access file system information by using the following classes: +In .NET, you can access file system information by using the following classes: - diff --git a/docs/csharp/programming-guide/file-system/how-to-iterate-through-a-directory-tree.md b/docs/csharp/programming-guide/file-system/how-to-iterate-through-a-directory-tree.md index ee2a11416345a..d62ba763e67bf 100644 --- a/docs/csharp/programming-guide/file-system/how-to-iterate-through-a-directory-tree.md +++ b/docs/csharp/programming-guide/file-system/how-to-iterate-through-a-directory-tree.md @@ -10,7 +10,7 @@ ms.assetid: c4be4a75-6b1b-46a7-9d38-bab353091ed7 The phrase "iterate a directory tree" means to access each file in each nested subdirectory under a specified root folder, to any depth. You do not necessarily have to open each file. You can just retrieve the name of the file or subdirectory as a `string`, or you can retrieve additional information in the form of a or object. > [!NOTE] -> In Windows, the terms "directory" and "folder" are used interchangeably. Most documentation and user interface text uses the term "folder," but the .NET Framework class library uses the term "directory." +> In Windows, the terms "directory" and "folder" are used interchangeably. Most documentation and user interface text uses the term "folder," but .NET class libraries use the term "directory." In the simplest case, in which you know for certain that you have access permissions for all directories under a specified root, you can use the `System.IO.SearchOption.AllDirectories` flag. This flag returns all the nested subdirectories that match the specified pattern. The following example shows how to use this flag. @@ -27,7 +27,7 @@ root.GetDirectories("*.*", System.IO.SearchOption.AllDirectories); If you have to perform a variety of operations on files and folders, you can modularize these examples by refactoring the operation into separate functions that you can invoke by using a single delegate. > [!NOTE] -> NTFS file systems can contain *reparse points* in the form of *junction points*, *symbolic links*, and *hard links*. The .NET Framework methods such as and will not return any subdirectories under a reparse point. This behavior guards against the risk of entering into an infinite loop when two reparse points refer to each other. In general, you should use extreme caution when you deal with reparse points to ensure that you do not unintentionally modify or delete files. If you require precise control over reparse points, use platform invoke or native code to call the appropriate Win32 file system methods directly. +> NTFS file systems can contain *reparse points* in the form of *junction points*, *symbolic links*, and *hard links*. .NET methods such as and will not return any subdirectories under a reparse point. This behavior guards against the risk of entering into an infinite loop when two reparse points refer to each other. In general, you should use extreme caution when you deal with reparse points to ensure that you do not unintentionally modify or delete files. If you require precise control over reparse points, use platform invoke or native code to call the appropriate Win32 file system methods directly. ## Example The following example shows how to walk a directory tree by using recursion. The recursive approach is elegant but has the potential to cause a stack overflow exception if the directory tree is large and deeply nested. diff --git a/docs/csharp/programming-guide/file-system/how-to-read-a-text-file-one-line-at-a-time.md b/docs/csharp/programming-guide/file-system/how-to-read-a-text-file-one-line-at-a-time.md index f79827210b00d..5b867aea28c08 100644 --- a/docs/csharp/programming-guide/file-system/how-to-read-a-text-file-one-line-at-a-time.md +++ b/docs/csharp/programming-guide/file-system/how-to-read-a-text-file-one-line-at-a-time.md @@ -41,7 +41,7 @@ System.Console.ReadLine(); - The file may not exist. -## .NET Framework Security +## .NET Security Do not make decisions about the contents of the file based on the name of the file. For example, the file `myFile.cs` may not be a C# source file. ## See also diff --git a/docs/csharp/programming-guide/file-system/how-to-read-from-a-text-file.md b/docs/csharp/programming-guide/file-system/how-to-read-from-a-text-file.md index 69ce59b6899ba..1e79ede1fd019 100644 --- a/docs/csharp/programming-guide/file-system/how-to-read-from-a-text-file.md +++ b/docs/csharp/programming-guide/file-system/how-to-read-from-a-text-file.md @@ -31,7 +31,7 @@ If you are not using the text files from [How to write to a text file](./how-to- - The file doesn't exist or doesn't exist at the specified location. Check the path and the spelling of the file name. -## .NET Framework Security +## .NET Security Do not rely on the name of a file to determine the contents of the file. For example, the file `myFile.cs` might not be a C# source file. ## See also diff --git a/docs/csharp/programming-guide/generics/generics-and-reflection.md b/docs/csharp/programming-guide/generics/generics-and-reflection.md index 687ed5f8c280e..aabcfb0eba007 100644 --- a/docs/csharp/programming-guide/generics/generics-and-reflection.md +++ b/docs/csharp/programming-guide/generics/generics-and-reflection.md @@ -9,7 +9,7 @@ ms.assetid: 162fd9b4-dd5b-4abb-8c9b-e44e21e2f451 # Generics and Reflection (C# Programming Guide) Because the Common Language Runtime (CLR) has access to generic type information at run time, you can use reflection to obtain information about generic types in the same way as for non-generic types. For more information, see [Generics in the Run Time](./generics-in-the-run-time.md). - In the .NET Framework 2.0, several new members are added to the class to enable run-time information for generic types. See the documentation on these classes for more information on how to use these methods and properties. The namespace also contains new members that support generics. See [How to: Define a Generic Type with Reflection Emit](../../../framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit.md). + In .NET Framework 2.0, several new members were added to the class to enable run-time information for generic types. See the documentation on these classes for more information on how to use these methods and properties. The namespace also contains new members that support generics. See [How to: Define a Generic Type with Reflection Emit](../../../framework/reflection-and-codedom/how-to-define-a-generic-type-with-reflection-emit.md). For a list of the invariant conditions for terms used in generic reflection, see the property remarks. diff --git a/docs/csharp/programming-guide/generics/index.md b/docs/csharp/programming-guide/generics/index.md index 4d4ac697f0b24..090a644d76530 100644 --- a/docs/csharp/programming-guide/generics/index.md +++ b/docs/csharp/programming-guide/generics/index.md @@ -8,13 +8,13 @@ ms.assetid: 75ea8509-a4ea-4e7a-a2b3-cf72482e9282 --- # Generics (C# Programming Guide) -Generics introduce the concept of type parameters to the .NET Framework, which make it possible to design classes and methods that defer the specification of one or more types until the class or method is declared and instantiated by client code. For example, by using a generic type parameter `T`, you can write a single class that other client code can use without incurring the cost or risk of runtime casts or boxing operations, as shown here: +Generics introduce the concept of type parameters to .NET, which make it possible to design classes and methods that defer the specification of one or more types until the class or method is declared and instantiated by client code. For example, by using a generic type parameter `T`, you can write a single class that other client code can use without incurring the cost or risk of runtime casts or boxing operations, as shown here: [!code-csharp[csProgGuideGenerics#1](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuideGenerics/CS/Generics.cs#1)] Generic classes and methods combine reusability, type safety, and efficiency in a way that their non-generic counterparts cannot. Generics are most frequently used with collections and the methods that operate on them. The namespace contains several generic-based collection classes. The non-generic collections, such as are not recommended and are maintained for compatibility purposes. For more information, see [Generics in .NET](../../../standard/generics/index.md). -Of course, you can also create custom generic types and methods to provide your own generalized solutions and design patterns that are type-safe and efficient. The following code example shows a simple generic linked-list class for demonstration purposes. (In most cases, you should use the class provided by the .NET Framework class library instead of creating your own.) The type parameter `T` is used in several locations where a concrete type would ordinarily be used to indicate the type of the item stored in the list. It is used in the following ways: +Of course, you can also create custom generic types and methods to provide your own generalized solutions and design patterns that are type-safe and efficient. The following code example shows a simple generic linked-list class for demonstration purposes. (In most cases, you should use the class provided by .NET instead of creating your own.) The type parameter `T` is used in several locations where a concrete type would ordinarily be used to indicate the type of the item stored in the list. It is used in the following ways: - As the type of a method parameter in the `AddHead` method. - As the return type of the `Data` property in the nested `Node` class. @@ -32,7 +32,7 @@ The following code example shows how client code uses the generic `GenericList namespace. These should be used whenever possible instead of classes such as in the namespace. +- The .NET class library contains several generic collection classes in the namespace. These should be used whenever possible instead of classes such as in the namespace. - You can create your own generic interfaces, classes, methods, events, and delegates. - Generic classes may be constrained to enable access to methods on particular data types. - Information on the types that are used in a generic data type may be obtained at run-time by using reflection. diff --git a/docs/csharp/programming-guide/index.md b/docs/csharp/programming-guide/index.md index 3c1c03b0b8206..23af049430b3a 100644 --- a/docs/csharp/programming-guide/index.md +++ b/docs/csharp/programming-guide/index.md @@ -12,11 +12,11 @@ ms.assetid: ac0f23a2-6bf3-4077-be99-538ae5fd3bc5 --- # C# programming guide -This section provides detailed information on key C# language features and features accessible to C# through the .NET Framework. +This section provides detailed information on key C# language features and features accessible to C# through .NET. Most of this section assumes that you already know something about C# and general programming concepts. If you are a complete beginner with programming or with C#, you might want to visit the [Introduction to C# Tutorials](../tutorials/intro-to-csharp/index.md) or [.NET In-Browser Tutorial](https://dotnet.microsoft.com/learn/dotnet/in-browser-tutorial/1), where no prior programming knowledge is required. - For information about specific keywords, operators and preprocessor directives, see [C# Reference](../language-reference/index.md). For information about the C# Language Specification, see [C# Language Specification](/dotnet/csharp/language-reference/language-specification/introduction). + For information about specific keywords, operators, and preprocessor directives, see [C# Reference](../language-reference/index.md). For information about the C# Language Specification, see [C# Language Specification](/dotnet/csharp/language-reference/language-specification/introduction). ## Program sections diff --git a/docs/csharp/programming-guide/inside-a-program/hello-world-your-first-program.md b/docs/csharp/programming-guide/inside-a-program/hello-world-your-first-program.md index 6b647dfc52383..d13741171d43e 100644 --- a/docs/csharp/programming-guide/inside-a-program/hello-world-your-first-program.md +++ b/docs/csharp/programming-guide/inside-a-program/hello-world-your-first-program.md @@ -108,7 +108,7 @@ For more information about how to use command-line arguments, see the examples i ## Input and output -C# programs generally use the input/output services provided by the run-time library of the .NET Framework. The statement `System.Console.WriteLine("Hello World!");` uses the method. This is one of the output methods of the class in the run-time library. It displays its string parameter on the standard output stream followed by a new line. Other methods are available for different input and output operations. If you include the `using System;` directive at the beginning of the program, you can directly use the classes and methods without fully qualifying them. For example, you can call `Console.WriteLine` instead of `System.Console.WriteLine`: +C# programs generally use the input/output services provided by the run-time library of .NET. The statement `System.Console.WriteLine("Hello World!");` uses the method. This is one of the output methods of the class in the run-time library. It displays its string parameter on the standard output stream followed by a new line. Other methods are available for different input and output operations. If you include the `using System;` directive at the beginning of the program, you can directly use the classes and methods without fully qualifying them. For example, you can call `Console.WriteLine` instead of `System.Console.WriteLine`: [!code-csharp[csProgGuide#1](~/samples/snippets/csharp/VS_Snippets_VBCSharp/csProgGuide/CS/using.cs#1)] diff --git a/docs/csharp/programming-guide/interop/example-com-class.md b/docs/csharp/programming-guide/interop/example-com-class.md index d4849ac765cd6..1f6e11093b321 100644 --- a/docs/csharp/programming-guide/interop/example-com-class.md +++ b/docs/csharp/programming-guide/interop/example-com-class.md @@ -19,7 +19,7 @@ The following is an example of a class that you would expose as a COM object. Af - Events must be declared in the event interface. - Other public members in the class that are not declared in these interfaces will not be visible to COM, but they will be visible to other .NET Framework objects. + Other public members in the class that are not declared in these interfaces will not be visible to COM, but they will be visible to other .NET objects. To expose properties and methods to COM, you must declare them on the class interface and mark them with a `DispId` attribute, and implement them in the class. The order in which the members are declared in the interface is the order used for the COM vtable. diff --git a/docs/csharp/programming-guide/interop/index.md b/docs/csharp/programming-guide/interop/index.md index 579efe2e496b0..95a75c1cbf60f 100644 --- a/docs/csharp/programming-guide/interop/index.md +++ b/docs/csharp/programming-guide/interop/index.md @@ -9,9 +9,10 @@ helpviewer_keywords: ms.assetid: 238bb95a-e962-4026-bbd5-197055bdb8ee --- # Interoperability (C# Programming Guide) + Interoperability enables you to preserve and take advantage of existing investments in unmanaged code. Code that runs under the control of the common language runtime (CLR) is called *managed code*, and code that runs outside the CLR is called *unmanaged code*. COM, COM+, C++ components, ActiveX components, and Microsoft Windows API are examples of unmanaged code. - The .NET Framework enables interoperability with unmanaged code through platform invoke services, the namespace, C++ interoperability, and COM interoperability (COM interop). +.NET enables interoperability with unmanaged code through platform invoke services, the namespace, C++ interoperability, and COM interoperability (COM interop). ## In This Section [Interoperability Overview](./interoperability-overview.md) diff --git a/docs/csharp/programming-guide/interop/interoperability-overview.md b/docs/csharp/programming-guide/interop/interoperability-overview.md index 2ae6faedad91f..f5394aa49f049 100644 --- a/docs/csharp/programming-guide/interop/interoperability-overview.md +++ b/docs/csharp/programming-guide/interop/interoperability-overview.md @@ -21,7 +21,7 @@ For more information, see [Consuming Unmanaged DLL Functions](../../../framework > The [Common Language Runtime](../../../standard/clr.md) (CLR) manages access to system resources. Calling unmanaged code that is outside the CLR bypasses this security mechanism, and therefore presents a security risk. For example, unmanaged code might call resources in unmanaged code directly, bypassing CLR security mechanisms. For more information, see [Security in .NET](../../../standard/security/index.md). ## C++ Interop - You can use C++ interop, also known as It Just Works (IJW), to wrap a native C++ class so that it can be consumed by code that is authored in C# or another .NET Framework language. To do this, you write C++ code to wrap a native DLL or COM component. Unlike other .NET Framework languages, Visual C++ has interoperability support that enables managed and unmanaged code to be located in the same application and even in the same file. You then build the C++ code by using the **/clr** compiler switch to produce a managed assembly. Finally, you add a reference to the assembly in your C# project and use the wrapped objects just as you would use other managed classes. + You can use C++ interop, also known as It Just Works (IJW), to wrap a native C++ class so that it can be consumed by code that is authored in C# or another .NET language. To do this, you write C++ code to wrap a native DLL or COM component. Unlike other .NET languages, Visual C++ has interoperability support that enables managed and unmanaged code to be located in the same application and even in the same file. You then build the C++ code by using the **/clr** compiler switch to produce a managed assembly. Finally, you add a reference to the assembly in your C# project and use the wrapped objects just as you would use other managed classes. ## Exposing COM Components to C\# You can consume a COM component from a C# project. The general steps are as follows: @@ -30,7 +30,7 @@ For more information, see [Consuming Unmanaged DLL Functions](../../../framework 2. Add to the project a reference to the COM component or type library. - When you add the reference, Visual Studio uses the [Tlbimp.exe (Type Library Importer)](../../../framework/tools/tlbimp-exe-type-library-importer.md), which takes a type library as input, to output a .NET Framework interop assembly. The assembly, also named a runtime callable wrapper (RCW), contains managed classes and interfaces that wrap the COM classes and interfaces that are in the type library. Visual Studio adds to the project a reference to the generated assembly. + When you add the reference, Visual Studio uses the [Tlbimp.exe (Type Library Importer)](../../../framework/tools/tlbimp-exe-type-library-importer.md), which takes a type library as input, to output a .NET interop assembly. The assembly, also named a runtime callable wrapper (RCW), contains managed classes and interfaces that wrap the COM classes and interfaces that are in the type library. Visual Studio adds to the project a reference to the generated assembly. 3. Create an instance of a class that is defined in the RCW. This, in turn, creates an instance of the COM object. diff --git a/docs/csharp/programming-guide/namespaces/how-to-use-the-my-namespace.md b/docs/csharp/programming-guide/namespaces/how-to-use-the-my-namespace.md index 4d96302a72593..d53ff465e64c1 100644 --- a/docs/csharp/programming-guide/namespaces/how-to-use-the-my-namespace.md +++ b/docs/csharp/programming-guide/namespaces/how-to-use-the-my-namespace.md @@ -6,14 +6,16 @@ helpviewer_keywords: ms.assetid: e7152414-0ea5-4c8e-bf02-c8d5bbe45ff4 --- # How to use the My namespace (C# Programming Guide) -The namespace (`My` in Visual Basic) provides easy and intuitive access to a number of .NET Framework classes, enabling you to write code that interacts with the computer, application, settings, resources, and so on. Although originally designed for use with Visual Basic, the `MyServices` namespace can be used in C# applications. + +The namespace (`My` in Visual Basic) provides easy and intuitive access to a number of .NET classes, enabling you to write code that interacts with the computer, application, settings, resources, and so on. Although originally designed for use with Visual Basic, the `MyServices` namespace can be used in C# applications. For more information about using the `MyServices` namespace from Visual Basic, see [Development with My](../../../visual-basic/developing-apps/development-with-my/index.md). -## Adding a Reference +## Add a reference + Before you can use the `MyServices` classes in your solution, you must add a reference to the Visual Basic library. -#### To add a reference to the Visual Basic library +### Add a reference to the Visual Basic library 1. In **Solution Explorer**, right-click the **References** node, and select **Add Reference**. diff --git a/docs/csharp/programming-guide/namespaces/using-namespaces.md b/docs/csharp/programming-guide/namespaces/using-namespaces.md index 4ea7dd93d1959..51560c455bfe0 100644 --- a/docs/csharp/programming-guide/namespaces/using-namespaces.md +++ b/docs/csharp/programming-guide/namespaces/using-namespaces.md @@ -10,7 +10,7 @@ ms.assetid: 1fe8bf39-addc-438a-bd9e-86410e32381d --- # Using namespaces (C# Programming Guide) -Namespaces are heavily used within C# programs in two ways. Firstly, the .NET Framework classes use namespaces to organize its many classes. Secondly, declaring your own namespaces can help control the scope of class and method names in larger programming projects. +Namespaces are heavily used within C# programs in two ways. Firstly, the .NET classes use namespaces to organize its many classes. Secondly, declaring your own namespaces can help control the scope of class and method names in larger programming projects. ## Accessing namespaces diff --git a/docs/csharp/programming-guide/statements-expressions-operators/anonymous-functions.md b/docs/csharp/programming-guide/statements-expressions-operators/anonymous-functions.md index 3ba65534e456f..0b9aadc927e9a 100644 --- a/docs/csharp/programming-guide/statements-expressions-operators/anonymous-functions.md +++ b/docs/csharp/programming-guide/statements-expressions-operators/anonymous-functions.md @@ -15,7 +15,7 @@ You can use a [lambda expression](lambda-expressions.md) or an [anonymous method ## The Evolution of Delegates in C\# - In C# 1.0, you created an instance of a delegate by explicitly initializing it with a method that was defined elsewhere in the code. C# 2.0 introduced the concept of anonymous methods as a way to write unnamed inline statement blocks that can be executed in a delegate invocation. C# 3.0 introduced lambda expressions, which are similar in concept to anonymous methods but more expressive and concise. These two features are known collectively as *anonymous functions*. In general, applications that target version 3.5 and later of the .NET Framework should use lambda expressions. + In C# 1.0, you created an instance of a delegate by explicitly initializing it with a method that was defined elsewhere in the code. C# 2.0 introduced the concept of anonymous methods as a way to write unnamed inline statement blocks that can be executed in a delegate invocation. C# 3.0 introduced lambda expressions, which are similar in concept to anonymous methods but more expressive and concise. These two features are known collectively as *anonymous functions*. In general, applications that target .NET Framework 3.5 or later should use lambda expressions. The following example demonstrates the evolution of delegate creation from C# 1.0 to C# 3.0: diff --git a/docs/csharp/programming-guide/statements-expressions-operators/equality-comparisons.md b/docs/csharp/programming-guide/statements-expressions-operators/equality-comparisons.md index 684513105eaaa..2b9f01af5bc03 100644 --- a/docs/csharp/programming-guide/statements-expressions-operators/equality-comparisons.md +++ b/docs/csharp/programming-guide/statements-expressions-operators/equality-comparisons.md @@ -48,7 +48,7 @@ However, there is no requirement that equivalence be based on all the fields in |-----------|-----------------| |[How to test for reference equality (Identity)](./how-to-test-for-reference-equality-identity.md)|Describes how to determine whether two variables have reference equality.| |[How to define value equality for a type](./how-to-define-value-equality-for-a-type.md)|Describes how to provide a custom definition of value equality for a type.| -|[C# Programming Guide](../index.md)|Provides links to detailed information about important C# language features and features that are available to C# through the .NET Framework.| +|[C# Programming Guide](../index.md)|Provides links to detailed information about important C# language features and features that are available to C# through .NET.| |[Types](../types/index.md)|Provides information about the C# type system and links to additional information.| ## See also diff --git a/docs/csharp/programming-guide/strings/how-to-determine-whether-a-string-represents-a-numeric-value.md b/docs/csharp/programming-guide/strings/how-to-determine-whether-a-string-represents-a-numeric-value.md index 15e5526855401..0b8646e015b88 100644 --- a/docs/csharp/programming-guide/strings/how-to-determine-whether-a-string-represents-a-numeric-value.md +++ b/docs/csharp/programming-guide/strings/how-to-determine-whether-a-string-represents-a-numeric-value.md @@ -29,7 +29,7 @@ bool result = int.TryParse(s, out i); //i now = 108 ## Robust Programming Primitive numeric types also implement the `Parse` static method, which throws an exception if the string is not a valid number. `TryParse` is generally more efficient because it just returns false if the number is not valid. -## .NET Framework Security +## .NET Security Always use the `TryParse` or `Parse` methods to validate user input from controls such as text boxes and combo boxes. ## See also diff --git a/docs/csharp/programming-guide/types/using-type-dynamic.md b/docs/csharp/programming-guide/types/using-type-dynamic.md index 4439b232a8303..98a7450be9452 100644 --- a/docs/csharp/programming-guide/types/using-type-dynamic.md +++ b/docs/csharp/programming-guide/types/using-type-dynamic.md @@ -53,7 +53,7 @@ Overload resolution occurs at run time instead of at compile time if one or more ## Dynamic language runtime -The dynamic language runtime (DLR) is a new API in .NET Framework 4. It provides the infrastructure that supports the `dynamic` type in C#, and also the implementation of dynamic programming languages such as IronPython and IronRuby. For more information about the DLR, see [Dynamic Language Runtime Overview](../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). +The dynamic language runtime (DLR) is an API that was introduced in .NET Framework 4. It provides the infrastructure that supports the `dynamic` type in C#, and also the implementation of dynamic programming languages such as IronPython and IronRuby. For more information about the DLR, see [Dynamic Language Runtime Overview](../../../framework/reflection-and-codedom/dynamic-language-runtime-overview.md). ## COM interop